molsysmt.interactions.metal_coordination.get_metal_coordination#

molsysmt.interactions.metal_coordination.get_metal_coordination(molecular_system, selection='all', selection_2=None, structure_indices='all', chemical_state='reference', method='metal_ligand_distance', distance_threshold=None, selection_mode='internal', pbc=True, assume_complete_connectivity=False, output_type='molsysmt.Interactions', syntax='MolSysMT', skip_digestion=False, *, max_matches=100000, heavy_mode='auto', profile=None)[source]#

Observing sparse metal-ligand candidates with an inclusive distance cutoff.

Return an independent analysis; attachment to a molecular system is explicit.

Parameters:

molecular_system (molecular system) – Any supported form supplying coordinates and complete declared chemistry: elements, 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 sites.
selection_2 (str, list, tuple, numpy.ndarray, or None, default=None) – Disjoint second selection, required only for between mode.
structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Structure indices (0-based). Evaluate repeated indices once, sorted. Frames without candidates retain explicit evaluated coverage.
chemical_state ({'reference', 'structure'}, int, or None, default='reference') – State supplying sites. Structure assignments must resolve one state.
method (str, default='metal_ligand_distance') – Descriptive pair-distance criterion. The profile fixes chemical sites.
distance_threshold (quantity, str, or None, default=None) – Finite positive scalar length cutoff. None uses 0.28 nm, inclusive without an added tolerance, matching the reference Distance core.
selection_mode ({'internal', 'incident', 'between'}, default='internal') – Both atoms in selection, either atom in selection, or one in each of two disjoint selections. Roles always remain metal followed by ligand.
pbc (bool, default=True) – Use MIC when a valid box exists, anchored on the metal. Preserve the actual periodic image used for the observed pair distance.
assume_complete_connectivity (bool, default=False) – Record a completeness assumption without repairing chemical assignments.
output_type (str, default='molsysmt.Interactions') – Sparse molsysmt.Interactions or typed molsysmt.InteractionsDict.
syntax (str, default='MolSysMT') – Selection syntax used to evaluate selection and selection_2.
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 chemical SMARTS.
heavy_mode ({'auto', 'force', 'off'}, default='auto') – Keyword-only execution policy. Native/H5MSM index selections can stream projected coordinate blocks. Accepted sparse output remains in RAM.
profile (str or None, default=None) – Keyword-only smarts_metal_ligand profile from ProLIF 2.2.2. None selects that profile. The ProLIF package is not required at runtime.

Returns:

Directed distinct pairs, singleton metal and ligand roles, distance in nm, explicit scope, evaluated frames, chemistry evidence, producer versions, reference bibliography and observed periodic images.

Return type:

molsysmt.Interactions or molsysmt.InteractionsDict

Raises:

ArgumentError – If cutoff, units, profile, state, selections or indices are invalid.
StructuralInconsistencyError – If chemistry, finite coordinates or valid periodic boxes are absent.
UnsupportedHeavyOperationError – If a forced streaming route is unsupported or max_matches is exceeded.
MemoryBudgetExceededError – If numerical graph, candidate or resident-result estimates exceed budget.

Notes

Reproduce ProLIF 2.2.2 MetalDonor/Distance sites and <=0.28 nm geometry. This is a broad experimental proximity profile, not a metal-specific physical model or proof of a coordination bond, oxidation state, geometry, coordination number, affinity or energy. Water oxygen can be a ligand. Recognition excludes dative graph edges; stored dative assignments remain independent and are never created or changed by this calculation. Self pairs are excluded. Covalent neighbors and intramolecular pairs are included. If an atom has both site roles, reversed role assignments are distinct relations rather than unordered duplicates.

The calculation retains full source chemistry and accepted sparse output. Coordinate blocks, candidate searches and accumulation use bounded numeric working estimates; Python overhead and process RSS are excluded. Rich H5MSM selections require bounded eager loading. No incremental writer is supplied. Optional Ackredit credits completed calculations; saved producer provenance identifies the original calculation, not the software used on later reads.