Skip to content

Notation

Chemical string notation, parsed by the native core. Three notations are supported — SMILES, CGsmiles and SMARTS — and each is reached through a type; the reader entry points are read_smiles(text) and read_cgsmiles(text). Every notation type mirrors its molrs owner — SMILES in mp.io.smiles (mp.io.smiles.SmilesIr), CGsmiles in mp.io.cgsmiles (mp.io.cgsmiles.CgSmilesIr), SMARTS in mp.perceive (mp.perceive.SmartsPattern).

Quick reference

Expression Input Output Use when
mp.io.smiles.read_smiles(s).to_atomistic() SMILES Atomistic One graph; .-separated components remain disconnected
mp.io.smiles.read_smiles(s) SMILES SmilesIr Inspect before converting
mp.io.smiles.read_smiles(s).n_components SMILES int How many molecules the string names
mp.io.smiles.read_smiles(s).components() dot-separated SMILES list[Atomistic] One graph per component ([Li+].[F-])
mp.perceive.SmartsPattern(p) SMARTS SmartsPattern Pattern matching / typification

Canonical example

import molpy as mp

mol = mp.io.smiles.read_smiles("CCO").to_atomistic() # Atomistic (heavy atoms only)
mol = mp.perceive.add_hydrogens(mol) #... with hydrogens

ions = mp.io.smiles.read_smiles("[Li+].[F-]").components() # [Atomistic, Atomistic]

query = mp.perceive.SmartsPattern("[C;X4][O;H1]") # compiled query
query.find_matches(mol) # -> list[SmartsMatch]

A .-separated string names a set of molecules: to_atomistic() returns them as one disconnected graph, components() returns one graph each, and n_components says how many there are.

Polymer notations

CGsmiles is parsed by mp.io.cgsmiles.CgSmilesIr: templates() gives each fragment as an Atomistic whose bonding descriptors are ports (one fragment body alone: mp.io.smiles.read_smiles_fragment(body).to_template()), and to_coarsegrain() gives the site graph that mp.builder.Assembler builds. BigSMILES and G-BigSMILES are not parsed.

  • mp.perceive.add_hydrogens, assign_aromaticity, assign_rings, assign_stereo — hydrogens, aromaticity, rings, stereo (perceive before you match: X4 and H1 count what is actually in the graph)
  • mp.perceive.RingSet — ring / ring-system queries
  • mp.perceive.Reaction — a reaction SMARTS applied to a graph in place: forms and breaks bonds, deletes the unmapped leaving atoms
  • Guide: Parsing Chemistry

Full API

SmilesIr

Intermediate representation of a parsed SMILES string.

:func:read_smiles hands it out; it has no constructor of its own. str(ir) writes it back as text. A fragment body with bonding descriptors is :func:read_smiles_fragment's, a :class:FragmentIr.

to_atomistic

to_atomistic()

Connectivity only: no implicit hydrogens added, no coordinates.

CgSmilesIr

Intermediate representation of a parsed CGsmiles string.

:func:read_cgsmiles parses, validates, expands and resolves the whole string and hands it out; it has no constructor of its own. levels are the resolution levels (coarsest first), fragments[k] resolves the names of levels[k], and to_atomistic() expands the lowest level into a topology-only graph whose atoms carry frag_id.

templates

templates()

One ported :class:Atomistic template per definition of the last fragment table, keyed by name. One body alone: read_smiles_fragment(body).to_template().

to_coarsegrain

to_coarsegrain()

The coarsest level, levels[0], as a bead graph: one bead per node (bead_type only, no coordinates or mass), one CG bond per edge.

Raises

SmilesError (a ValueError) the IR breaks a reader invariant; no parsed string reaches this.

SmartsPattern

Compiled, atom-map-aware SMARTS query over an :class:Atomistic.

Wraps the core Rust SMARTS engine (non-uniquified, RDKit uniquify=False). Daylight atom maps ([C:1]) add no match constraint; a match's :attr:SmartsMatch.mapping is its {map_number: Atom} dict.

find_matches

find_matches(mol, *, labels=None, root=None, limit=None)

All matches. labels supplies the %LABEL context, root pins query atom 0, limit stops after N embeddings.

Raises

ValueError A labels key or root is an atom of another molecule.

from_environment classmethod

from_environment(
    mol,
    center,
    *,
    reach=1,
    atomic_number=True,
    include_degree=True,
    include_h_count=True,
    include_charge=True,
    include_aromatic=True,
    include_ring_membership=False,
    include_ring_size=False,
    include_explicit_h_atoms=False,
    include_bond_orders=True,
    neighbor_style="chain",
    canonical_neighbor_order=True,
)

The pattern that states the local environment of center in mol out to reach bonds; it matches mol at center.

SmartsMatch

One SMARTS embedding: the molecule's atoms in query-atom order, and the Daylight atom-map projection ({map_number: Atom}, empty without map labels).

SmilesError

Bases: ValueError

Raised when a SMILES / SMARTS / CGsmiles string is refused.

Subclasses ValueError; str(e) is the message the Rust error renders, caret line included. The four attributes are set on every instance.

Attributes

kind : str Variant name of the rule that was broken, payload dropped — "UnclosedBranch", "UnexpectedEnd", "CgNotExpandable", ... span : tuple[int, int] Byte range of the offending text within input; the end is clamped to len(input), since the scanner reports end-of-input one byte past the text. input : str The offending string, empty for errors raised past the parser (the expansion and emit stages are handed an IR, not the text). notation : str Which notation was being read or written: "smiles", "smarts" or "cgsmiles".