molsysmt.build.add_missing_heavy_atoms#

molsysmt.build.add_missing_heavy_atoms(molecular_system, selection='all', syntax='MolSysMT', engine='MolSysMT', skip_digestion=False, *, attribute_policy='intersection')[source]#

Adding missing non-hydrogen atoms to a molecular system.

This function checks for missing heavy atoms (non-hydrogens) in a molecular system and adds them when possible. The missing atoms are identified based on known residue templates and inferred topological context. The coordinates of new atoms are estimated using internal geometry rules or external reconstruction engines such as PDBFixer.

Parameters:

  • molecular_system (molecular system) – Molecular system in any supported form providing residue identity, connectivity, element assignments and coordinates for the repair.

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Selection string or boolean/integer array specifying elements.

  • syntax (str, default='MolSysMT') – Selection syntax used to evaluate selection (e.g., ‘MolSysMT’, ‘MDTraj’).

  • engine (object, default='MolSysMT') – Placement engine. MolSysMT uses bounded exact residue-template alignment; PDBFixer delegates reconstruction to the optional external library.

  • skip_digestion (bool, default=False) – Whether to skip MolSysMT’s internal argument digestion mechanism.

  • attribute_policy ({'intersection', 'strict'}, default='intersection') – Keyword-only native-engine policy for attributes without values for added atoms. Intersection drops them with a diagnostic; strict fails without changing the source. PDBFixer supports only intersection here.

Returns:

A molecular system with the missing heavy atoms added, in the same form as the input system.

Return type:

molecular system

Raises:

  • NotSupportedFormError – Raised if the input molecular system is in an unsupported format.

  • ArgumentError – Raised if one or more input arguments are invalid.

  • EngineError – Raised if the specified engine fails to rebuild the atoms.

  • StructuralInconsistencyError – Raised if native atom expansion has multiple chemical states, or strict attribute policy cannot retain an existing attribute.

  • NotImplementedMethodError – Raised if strict attribute policy is requested with PDBFixer.

Notes

The native engine repairs standard residues and selected incomplete MSE, SEP, and TPO residues from exact chemical templates. Curated modified residues are matched by atom name, element, and connectivity; supported missing atoms are placed from local coordinates. MLY has an exact heavy-atom inventory, but its missing atoms remain unassessed because no placement is validated. Standard residues use the same bounded local preflight: duplicate names, element/connectivity conflicts, nonfinite or collinear anchors, and multiple missing side-chain atoms are unassessed. New-to-observed template bonds must agree within 0.04 nm of reference lengths in every structure. These checks do not validate clashes, stereochemistry, rotamers or an energy minimum. Residues with unvalidated side-chain gaps or conflicting chemistry are left unchanged with an UnassessedResidueWarning. Modified residues without curated templates are also reported as unassessed. Hydrogen atoms require a separate operation. Coordinate placement is an estimate and does not replace experimental refinement.

Native expansion preserves existing atom IDs and chemical assignments in one selected state, including its ID and provenance. New chemical values remain unknown and connectivity completeness becomes partial. Sorting atoms by group can change their indices. Named analyses retain their definitions and remapped source axes; all occurrences and evaluated coverage are cleared because the atom domain changed. Recalculate them on the repaired system. Coordinates of observed atoms, time and box are retained. Atom-aligned structural attributes without new values and existing force-field atom parameters are dropped with a diagnostic under intersection policy; strict rejects that loss. No force-field parameters are assigned for new atoms. These preservation guarantees apply to the native result; conversion to another form follows that form’s supported attributes. PDBFixer is a separate reconstruction route with its own capabilities.

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

The list of supported selection syntaxes is available at: User Guide > Introduction > Selection syntaxes

See also

molsysmt.build.get_missing_heavy_atoms()

Identify heavy atoms that are missing based on residue templates.

molsysmt.basic.remove()

Remove atoms from a molecular system.

molsysmt.basic.contains()

Check whether specific elements are present in a molecular system.

molsysmt.build.build_peptide()

Build capped peptide structures from amino acid sequences.

Examples

>>> import molsysmt as msm
>>> molsys = msm.build.build_peptide('AAA', engine='MolSysMT')
>>> msm.get(molsys, selection='atom_name=="CB"', n_atoms=True)
3
>>> molsys = msm.remove(molsys, selection='atom_name=="CB"')
>>> msm.get(molsys, selection='atom_name=="CB"', n_atoms=True)
0
>>> molsys = msm.build.add_missing_heavy_atoms(molsys)
>>> msm.get(molsys, selection='atom_name=="CB"', n_atoms=True)
3

User guide

Follow this link for a tutorial on how to work with this function: User Guide > Tools > Build > Add missing heavy atoms.

Added in version 1.0.0.