Add force-field-aware pdb2q preprocessing

[David-Araripe]

Motivation

qprep_prot assumes that protein residue and atom names already select the intended templates in the chosen Q force-field library. It can add atoms missing from those templates, but it does not assign protonation states or generally translate names from preparation packages such as Schrödinger, PDB2PQR, or AmberTools.

The existing pdb2amber command addresses part of this problem for AMBER14SB only. Other force fields need similar logic, and silently passing a generically named but explicitly protonated PDB to qprep can change its chemistry. For example, an HG-absent CYS must not automatically select neutral-thiol CYS when the prepared structure explicitly records SG with formal charge 1-.

Proposal

Add an installed, force-field-aware preprocessing command, tentatively named pdb2q:

pdb2q -i prepared.pdb -o q_named.pdb \
  --force-field OPLSAAM \
  --state-map states.csv \
  --strict

This should be a deterministic state encoder and naming normalizer, not a pKa predictor. Protonation prediction should remain the responsibility of an explicit upstream preparation tool. pdb2q should infer a state only where explicit hydrogens, formal charges, and/or connectivity identify it unambiguously.

Required behavior

1. Normalize residue and atom names for the selected Q .lib.
2. Infer protonation/tautomer states only from explicit evidence, including at least HID/HIE/HIP, ASP/ASH, GLU/GLH, LYS/LYN, ARG/ARN, CYS/CYM/CYX, and termini where supported by the library.
3. Accept explicit per-chain/per-residue user overrides in a documented machine-readable format.
4. Compare every output residue and explicit atom-name multiset against the selected .lib template.
5. Detect and report disulfides, metal coordination, alternate locations, duplicate atom names, unsupported terminal states, and ambiguous/inconsistent protonation signatures.
6. Write a machine-readable state report recording source name, selected Q name, evidence, transformations, and warnings/errors.
7. In strict mode, exit nonzero for every unsupported residue, atom mismatch, ambiguous state, inconsistent explicit state, or unsupported metal site.
8. Never modify the input file; write transformed coordinates only to the requested output.
9. Preserve coordinates and atom serials unless an explicitly documented operation requires otherwise.
10. Do not claim that recognizing a metal coordination site provides force-field parameters for it. Detection and parameterization validation must remain distinct.

Relationship to qprep_prot

qprep_prot should reuse the same library preflight and fail before invoking qprep when names/atoms are incompatible. Automatic state-changing normalization inside qprep_prot should be opt-in and should always write the transformed PDB and state report for review.

Migration from pdb2amber

Refactor the reusable parsing, explicit-state inference, atom renaming, terminal handling, and validation currently in pdb2amber into the pdb2q implementation. Keep pdb2amber temporarily as a compatibility wrapper equivalent to:

pdb2q --force-field AMBER14sb ...

Then deprecate the separate implementation after downstream callers have migrated. Force-field-specific conventions should live in adapters/rules rather than in duplicated command implementations.

Suggested implementation details

• Resolve libraries with the existing force-field path helpers and parse them with parse_lib.
• Group residues by chain, sequence number, and insertion code; do not rely on residue number alone.
• Use exact PDB columns for atom names, residue names, element, and formal charge.
• Keep inference rules fail-closed: absence of a hydrogen alone is not enough if qprep is expected to add missing hydrogens.
• Distinguish state recognition, name translation, library compatibility, and energetic/model validation in both code and reporting.
• Add unit fixtures from multiple preparation conventions and integration tests proving that qprep does not silently change an explicitly encoded state.

Acceptance criteria

• OPLSAAM and AMBER14SB are supported initially.
• An explicit-H prepared PDB produces a reproducible output PDB and state report.
• Every output protein residue either exactly matches a selected library template or causes a nonzero exit in strict mode.
• Ambiguous histidines and contradictory charge/hydrogen signatures fail with chain/residue-specific diagnostics.
• Unsupported Zn(Cys)4 chemistry is reported rather than converted to neutral CYS or disulfide CYX.
• pdb2amber compatibility tests pass through the shared implementation or wrapper.