molsysmt.build.get_covalent_bond_candidates#

molsysmt.build.get_covalent_bond_candidates(molecular_system, selection='all', structure_indices='all', chemical_state='reference', syntax='MolSysMT', skip_digestion=False, *, method='exact_heavy_group_templates')[source]#

Getting bounded covalent candidates from exact group templates.

Parameters:

  • molecular_system (molecular system) – Molecular system in any supported form providing atom names, elements and group membership. PDB inputs are converted with inference disabled.

  • selection (str, list, tuple or numpy.ndarray, default='all') – Atom selection. Integer values are source atom indices. Whole containing groups are audited, but both endpoints of each candidate must be selected. Defaults to ‘all’.

  • structure_indices (int, list, tuple or numpy.ndarray, default='all') – Structure indices (0-based). Choose one when structures exist; a topology without structures can also be assessed. Defaults to ‘all’.

  • chemical_state (str, int or None, default='reference') – Stored state to inspect, or ‘structure’ for the selected structure’s association. Ambiguous states remain unassessed. Defaults to ‘reference’.

  • syntax (str, default='MolSysMT') – Syntax used for atom selection. Defaults to ‘MolSysMT’.

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

  • method (str, default='exact_heavy_group_templates') – ‘exact_heavy_group_templates’ proposes only heavy intra-group pairs. ‘observed_hydrogen_template_consensus’ proposes only observed H-parent pairs with a unique reference parent. Defaults to ‘exact_heavy_group_templates’.

Returns:

Detached molsysmt.covalent_bond_candidates@1 report. Sorted source bonded_atom_pairs have shape (n_candidates, 2) and dtype int64; group_indices and missing_mask align with those rows. Each group retains template identity, source indices, exclusions and coverage. Missing means no stored edge has those endpoints; it does not certify existing edge types or chemistry. Producer versions are recorded at calculation time. Empty arrays retain their shapes and dtypes.

Return type:

dict

Raises:

  • ArgumentError – If selections or state/structure indices are invalid, or multiple structures are selected, or the method is unsupported.

  • NotWithThisFormError – If required group hierarchy is unavailable.

  • StructuralInconsistencyError – If atom/group membership or domain correspondence is invalid.

Notes

The method exact_heavy_group_templates reuses the residue-coverage auditor and its exact amino-acid and curated modified-group templates. It never substitutes a sequence parent. Only unambiguous mapped heavy-atom edges are proposed. Missing heavy atoms can leave a partial candidate set; duplicate/unexpected names, unknown/conflicting heavy elements, unresolved states and contradictory stored intra-group chemistry block a group. Unsupported groups, including water, ions, lipids and arbitrary small molecules, remain explicit in this first bounded method.

The optional observed_hydrogen_template_consensus method compares each existing H name with all heavy-compatible variants containing that exact name. Every matching variant must declare the same single heavy parent. H elements and parents must be known, present and compatible; conflicting stored partners, types, multiplicity or nonstandard H assignments block that H. Other H names may remain unassessed. Whole-group joint inventory compatibility is reported separately and is not required for a local parent consensus. No name aliases, first-variant choice, pH or terminal inference is applied. Modified heavy-only templates supply no H reference.

groups[*]['hydrogen_coverage'] retains typed H/parent arrays (unknown parent -1), eligibility and output-selection masks, CSR-style offsets and exact variant indices, joint inventory evidence and sparse issue records.

No geometry is used to propose bonds. The default excludes hydrogen edges. Inter-group polymer links, disulfides, metal coordination, bond orders, protonation and valence certification are unassessed. Coordinates, existing chemical assignments and named interactions are unchanged. PDB parsing remains eager; native H5MSM 0.5 numeric/all coverage reads only the selected coordinate structure.

See also

get_residue_chemical_coverage

Audit exact group-template coverage.

get_missing_bonds

Obtain legacy template/geometric missing-pair lists.

Examples

>>> import molsysmt as msm
>>> report = msm.build.get_covalent_bond_candidates(
...     msm.systems['alanine dipeptide']['alanine_dipeptide.h5msm'],
...     selection='group_index==1', structure_indices=0)
>>> report['bonded_atom_pairs'].tolist()
[[6, 8], [8, 10], [8, 14], [14, 15]]
>>> report['missing_mask'].tolist()
[False, False, False, False]

>>> report = msm.build.get_covalent_bond_candidates(
...     msm.systems['alanine dipeptide']['alanine_dipeptide.h5msm'],
...     selection='group_index==1', structure_indices=0,
...     method='observed_hydrogen_template_consensus')
>>> report['bonded_atom_pairs'].tolist()
[[6, 7], [8, 9], [10, 11], [10, 12], [10, 13]]

User guide

See Get covalent bond candidates for coverage and exclusions.

Added in version 1.0.0.