molsysmt.build.add_missing_hydrogens#

molsysmt.build.add_missing_hydrogens(molecular_system, pH=7.4, engine='OpenMM', skip_digestion=False, *, mode='pH', chemical_state='reference', structure_indices='all', return_report=False, attribute_policy='intersection')[source]#

Adding missing hydrogen atoms to a molecular system.

This function adds hydrogen atoms that are missing from a molecular system, based on its topology, standard chemical templates, and a selected pH. The added atoms are positioned using predefined rules for protonation states and geometry constraints.

Parameters:

molecular_system (molecular system) – Molecular system in any supported MolSysMT format.
pH (float or None, default=7.4) – pH passed to the legacy engine. Fixed-state mode requires None: it materializes a prepared inventory without choosing a protonation state.
engine (str, default='OpenMM') – Legacy engines are OpenMM, PDBFixer and MolSysMT. Explicit RDKit is required for fixed-state mode; missing RDKit never selects a fallback.
skip_digestion (bool, default=False) – Whether to skip MolSysMT’s internal argument digestion mechanism.
mode ({'pH', 'fixed_chemical_state'}, default='pH') – Keyword-only choice between existing residue/pH behavior and adding H to one isolated prepared component with one chemical state and one structure.
chemical_state (str or int, default='reference') – State selected in fixed-state mode; ‘structure’ resolves the structure link.
structure_indices (int, list, tuple or numpy.ndarray, default='all') – Selected structure in fixed-state mode. Extract multiple source structures first.
return_report (bool, default=False) – In fixed-state mode, return a dictionary containing molecular_system and a detached versioned preparation report instead of just the system. Successful reports are retained in the output’s preparation history regardless of this option.
attribute_policy ({'intersection', 'strict'}, default='intersection') – Fixed-state handling of attributes that cannot cover added atoms: intersection drops them with a diagnostic; strict rejects the input.

Returns:

Legacy mode returns the input form. Fixed-state mode returns a new native MolSys, or that system and hydrogen_addition@1 report when return_report=True. Existing atom indices and coordinate values are retained; appended H have deterministic string IDs and parent maps.

Return type:

molecular system or dict

Raises:

NotSupportedFormError – Raised if the input molecular system is not in a supported form.
ArgumentError – Raised if an input argument does not meet the expected format or conditions.
StructuralInconsistencyError – If fixed-state chemistry, geometry or atom-domain preservation is invalid.
ImportError – If an explicitly requested optional engine is unavailable.

Notes

Fixed-state mode requires explicit elements, complete covalent connectivity, atom/bond aromaticity, formal charges, closed-shell assignments and virtual H counts. Nonaromatic bonds require declared integer orders of 1, 2 or 3; explicitly aromatic bonds may retain fractional order 1.5 without an integer bond_order column. No alternating Kekule orders are invented. The optional RDKit AddHs(addCoords=True) primitive generates local H coordinates on the supplied pose. Backend reinterpretation of the declared inventory fails. Source inputs remain unchanged on success and failure. Missing H are appended; existing H are never removed or repositioned. No receptor refinement, minimization or heavy-atom conformer generation runs. Supply compact periodic coordinates; split molecules are rejected rather than reconstructed implicitly. Named interactions become unevaluated on an expanded output; no-addition outputs retain their analyses. Multiple states/structures, metals, radicals, query atoms and virtual isotopic additions are unsupported. Successful fixed-state operations retain both terminal-attachment and hydrogen-generation evidence in ChemicalStates preparation history, including no-addition results. H5MSM preserves original operation indices, structure counts, units and producer versions without storing another coordinate array. The embedded readiness audit uses scalar lists for nullable/mixed values and typed arrays for indices and coverage. History is not a live index map or a certificate after later edits. Import a component’s historical records explicitly with ChemicalStates.append_preparation_history when reinserting H. See Adding hydrogens to a fixed chemical state for the experimental contract.

In legacy pH mode, hydrogen atoms are added based on standard residue templates and general rules for protonation. Ionizable side chains (e.g., ASP, GLU, HIS) and both chain termini are adjusted according to the provided pH.

Warning

pH is applied through fixed pKa thresholds taken from free-amino-acid values, not through a calculation of each residue’s own pKa in its environment. A buried or electrostatically shifted residue can titrate more than a pH unit away from its threshold, and this function will not reflect that. Where the assignment matters — a residue near a threshold, or a pH-dependent result — verify it rather than assuming it, or obtain the protonation from a dedicated pKa predictor. Environment-dependent pKa prediction, comparable to PROPKA, is not implemented in any of the engines offered here.

This function only adds hydrogens. A hydrogen already present that the pH rules would not have placed is left untouched.

The list of supported molecular systems’ forms is available at: User Guide > Introduction > Molecular systems > Forms