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.
Related¶
mp.perceive.add_hydrogens,assign_aromaticity,assign_rings,assign_stereo— hydrogens, aromaticity, rings, stereo (perceive before you match:X4andH1count what is actually in the graph)mp.perceive.RingSet— ring / ring-system queriesmp.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.
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 ¶
One ported :class:Atomistic template per definition of the last
fragment table, keyed by name. One body alone:
read_smiles_fragment(body).to_template().
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 ¶
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".