molsysmt.physchem.get_metal_coordination_sites#

molsysmt.physchem.get_metal_coordination_sites(molecular_system, selection='all', structure_indices='all', chemical_state='reference', method='smarts_metal_ligand', assume_complete_connectivity=False, syntax='MolSysMT', skip_digestion=False, *, max_matches=100000)[source]#

Recognizing metal and candidate ligand atoms from declared chemical graphs.

Parameters:

  • molecular_system (molecular system) – Any supported form supplying elements, complete connectivity, covalent orders, formal charges and atom/bond aromatic flags.

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Source atom selection. Recognize full chemistry before filtering atoms.

  • structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Structure indices (0-based) for state resolution and spatial selections. Recognition does not require coordinates.

  • chemical_state ({'reference', 'structure'}, int, or None, default='reference') – State supplying chemistry. Structure assignments must resolve one state.

  • method (str, default='smarts_metal_ligand') – Exact ProLIF 2.2.2 MetalDonor metal and ligand SMARTS, without geometry.

  • assume_complete_connectivity (bool, default=False) – Record a completeness assumption without repairing chemical assignments.

  • syntax (str, default='MolSysMT') – Selection syntax used to evaluate selection.

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

  • max_matches (int, default=100000) – Keyword-only maximum full-source matches per SMARTS before selection. Exceeded limits raise rather than truncate sites.

Returns:

Sorted int64 metal_atom_indices and ligand_atom_indices, each shape (n_sites,), plus source/selected axes, state, patterns, chemical evidence, reference bibliography and actual producer versions. Empty arrays use (0,).

Return type:

dict

Raises:

  • ArgumentError – If method, selection, state or match limit is invalid.

  • StructuralInconsistencyError – If chemistry is missing or sanitization would change assignments.

  • UnsupportedHeavyOperationError – If chemical matching exceeds max_matches.

  • MemoryBudgetExceededError – If numerical chemical matching exceeds its working estimate.

Notes

The reference metal set is Ca, Cd, Co, Cu, Fe, Mg, Mn, Ni and Zn. It is a bounded profile, not all metals. Ligands include O, chemically restricted N, and negative nonpositive atoms; protonated/quaternary and selected conjugated nitrogens are excluded. A negative atom can be both a metal and a ligand site. Keep those roles distinct; geometry excludes self pairs. Covalent graph matching excludes dative links. These sites are not evidence of oxidation state, coordination number, affinity or a declared bond. ProLIF is a reference implementation, not an executed dependency.

See also

molsysmt.topology.get_substructure_matches

Matching general SMARTS on complete declared chemical graphs.

molsysmt.interactions.metal_coordination.get_metal_coordination

Observing sparse metal-ligand proximity candidates.

Examples

>>> import molsysmt as msm
>>> from rdkit import Chem
>>> sites = msm.physchem.get_metal_coordination_sites(Chem.MolFromSmiles('[Zn+2].O'))
>>> sites['metal_atom_indices'].tolist(), sites['ligand_atom_indices'].tolist()
([0], [1])

User guide

See Getting metal coordination sites.

Added in version 1.0.0.