molsysmt.topology.get_substructure_matches#

molsysmt.topology.get_substructure_matches(molecular_system, patterns, selection='all', structure_indices='all', chemical_state='reference', assume_complete_connectivity=False, syntax='MolSysMT', skip_digestion=False, *, max_matches=100000)[source]#

Matching chemical SMARTS without truncating or changing the source atom axis.

Parameters:

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

  • patterns (str, list, or tuple) – One SMARTS query or a sequence of queries, evaluated in supplied order.

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Retain only matches whose atoms all belong to this atom selection. The full graph is matched before filtering; chemistry is not truncated.

  • structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Structure indices for state resolution and coordinate-based selections. No coordinates are required for index selections or ‘all’.

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

  • assume_complete_connectivity (bool, default=False) – Record an explicit assumption of completeness without filling bonds.

  • syntax (str, default='MolSysMT') – 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 unique matches per query before atom filtering. Exceeding it raises instead of silently returning a truncated result.

Returns:

patterns and matches are aligned tuples. Each match matrix has int64 shape (n_matches, n_query_atoms), including (0, n_query_atoms) when empty. Columns preserve SMARTS query order; values are source atom indices, not IDs. Metadata retains source/selection axes, selected chemistry, RDKit/MolSysMT versions and declared chemistry evidence.

Return type:

dict

Raises:

  • ArgumentError – If a query or match limit is invalid.

  • StructuralInconsistencyError – If required chemistry is absent, contradictory or changed by RDKit sanitization. Atomic elements require a topology inventory.

  • UnsupportedHeavyOperationError – If a query exceeds max_matches. No truncated result is returned.

  • MemoryBudgetExceededError – If bounded matching or its resident numeric output exceeds the budget.

Notes

This experimental tool uses RDKit’s uniquified SMARTS matches and ring perception, including its implicit-hydrogen/valence interpretation. It does not invent missing formal charge or aromatic metadata. Native chemistry is converted through the existing chemistry-aware RDKit adapter without a structural series; RDKit input retains its atom-level hydrogen declarations. Sanitization must preserve declared formal charge and aromatic flags. Pattern ordering is preserved, not canonicalized across different graphs. Numeric matching reserves one quarter of configure.max_ram_usage; source graphs and Python overhead are outside this estimate. RDKit is optional.

See also

molsysmt.physchem.get_aromatic_rings

Perceiving a declared aromatic minimum cycle basis instead of SMARTS.

molsysmt.topology.get_rings

Perceiving covalent rings irrespective of aromaticity.

Examples

>>> import molsysmt as msm
>>> from molsysmt.topology.get_substructure_matches import get_substructure_matches
>>> from rdkit import Chem
>>> matches = get_substructure_matches(Chem.MolFromSmiles('CCO'), ['[O]', '[N]'])
>>> [matrix.tolist() for matrix in matches['matches']]
[[[2]], []]
>>> matches['matches'][1].shape
(0, 1)

User guide

See Getting substructure matches.

Added in version 1.0.0.