Typifier¶

SMARTS-based atom typing and force field parameter assignment.

Quick reference¶

Symbol	Summary	Preferred for
`OplsAtomisticTypifier`	Full OPLS-AA typing pipeline	OPLS force fields
`GaffTypifier`	Full GAFF typing pipeline	GAFF / GAFF2 force fields
`OplsAtomTypifier`	OPLS atom-only typing	When you only need atom types
`GaffAtomTypifier`	GAFF atom-only typing	When you only need atom types
`BondTypifier`	Bond type assignment from atom types	Standalone bonded typing
`AngleTypifier`	Angle type assignment from atom types	Standalone bonded typing
`DihedralTypifier`	Dihedral type assignment from atom types	Standalone bonded typing
`PairTypifier`	Pair (LJ) parameter assignment	Standalone nonbonded typing
`TypifierBase`	ABC for all typifiers	Custom typifier implementations
`.typify(struct)`	Assign all types (atom → pair → bond → angle → dihedral)	One-call complete typing

Canonical example¶

import molpy as mp
from molpy.typifier import OplsAtomisticTypifier

ff = mp.io.read_xml_forcefield("oplsaa.xml")
typifier = OplsAtomisticTypifier(ff, strict_typing=True)
typed_mol = typifier.typify(mol)  # returns NEW Atomistic

Key behavior¶

typify() returns a new Atomistic — the original is not modified
strict_typing=True raises on untyped atoms; False silently skips them
Atom typing uses SMARTS pattern matching with priority/override resolution
Bonded types are derived from atom type assignments (CT-OH → bond type CT-OH)

Full API¶

Base¶

base ¶

Base class for all typifiers.

TypifierBase ¶

TypifierBase(forcefield, strict=True)

Bases: ABC

Base class for all typifiers.

typify `abstractmethod` ¶

typify(elem)

Assign type to element.

atomtype_matches ¶

atomtype_matches(atomtype, type_str)

Check whether an atom type matches a target type/class string.

Match rules: - X or * in type_/class_ acts as a wildcard - otherwise exact match by type_ or class_

OPLS Typifier¶

opls ¶

OPLS-AA atom typifier and full typing orchestrator.

OplsAtomTypifier ¶

OplsAtomTypifier(forcefield, strict=False)

Bases: TypifierBase

OPLS atom typifier using SMARTS patterns.

OPLS uses: - "*" as wildcard in XML (converted to "X" internally) - Override-based priority system - Single SMARTS pattern per atom type

typify ¶

typify(elem)

Assign types to all atoms in Atomistic structure.

Returns a new Atomistic with typed atoms. The input is not modified.

OplsTypifier ¶

OplsTypifier(forcefield, skip_atom_typing=False, skip_pair_typing=False, skip_bond_typing=False, skip_angle_typing=False, skip_dihedral_typing=False, strict_typing=True)

Bases: TypifierBase

OPLS-AA full typing: atom -> pair -> bond -> angle -> dihedral.

typify ¶

typify(elem)

Run full typing pipeline.

Returns a new Atomistic with all types assigned. Input is not modified.

GAFF Typifier¶

gaff ¶

GAFF (Generalized Amber Force Field) typifier implementation.

GaffAtomTypifier ¶

GaffAtomTypifier(forcefield, strict=False)

Bases: ForceFieldAtomTypifier

Assign atom types using SMARTS matcher for GAFF force field.

Key differences from OPLS: - Last-match-wins priority (later rules in the file override earlier ones) - No type references (no %opls_XXX patterns) - Multiple SMARTS rules can map to the same type name

GaffAtomisticTypifier ¶

GaffAtomisticTypifier(forcefield, skip_atom_typing=False, skip_pair_typing=False, skip_bond_typing=False, skip_angle_typing=False, skip_dihedral_typing=False, strict_typing=True)

Bases: ForceFieldAtomisticTypifier

GAFF atomistic typifier orchestrator.

Runs the full typing pipeline: atom typing -> pair typing -> bond typing -> angle typing -> dihedral typing

Bond Typifier¶

bond ¶

Bond typifier — force-field agnostic.

BondTypifier ¶

BondTypifier(forcefield, strict=True)

Bases: TypifierBase

Bond typifier.

Matching rules: - "X" matches any atom type (wildcard) - Otherwise exact match by type or class - Bidirectional matching (A-B same as B-A)

typify ¶

typify(elem)

Assign type to bond.

Angle Typifier¶

angle ¶

Angle typifier — force-field agnostic.

AngleTypifier ¶

AngleTypifier(forcefield, strict=True)

Bases: TypifierBase

Angle typifier.

Matching rules: - "X" matches any atom type (wildcard) - Otherwise exact match by type or class - Bidirectional matching (A-B-C same as C-B-A)

typify ¶

typify(elem)

Assign type to angle.

Dihedral Typifier¶

dihedral ¶

Dihedral typifier — force-field agnostic.

DihedralTypifier ¶

DihedralTypifier(forcefield, strict=True)

Bases: TypifierBase

Dihedral typifier.

Matching rules: - "X" matches any atom type (wildcard) - Otherwise exact match by type or class - Bidirectional matching (A-B-C-D same as D-C-B-A)

typify ¶

typify(elem)

Assign type to dihedral.

Pair Typifier¶

pair ¶

Pair (nonbonded) typifier — force-field agnostic.

PairTypifier ¶

PairTypifier(forcefield, strict=True)

Bases: TypifierBase

Pair (nonbonded) typifier.

typify ¶

typify(elem)

Assign nonbonded parameters to atom.

Adapter¶

adapter ¶

Adapter utilities for converting molecules to graphs for matching.

This module provides functions to convert Atomistic structures into igraph.Graph representations suitable for SMARTS pattern matching.

build_mol_graph ¶

build_mol_graph(structure)

Convert Atomistic structure to igraph.Graph for matching.

Parameters:

Name	Type	Description	Default
`structure`	`Atomistic`	Atomistic structure with atoms and bonds	required

Returns:

Type	Description
`Graph`	Tuple of (graph, vs_to_atomid, atomid_to_vs) where:
`dict[int, int]`	graph: igraph.Graph with vertex/edge attributes
`dict[int, int]`	vs_to_atomid: mapping from vertex index to atom ID
`tuple[Graph, dict[int, int], dict[int, int]]`	atomid_to_vs: mapping from atom ID to vertex index

Vertex attributes set

element: str (e.g., "C", "N", "O")
number: int (atomic number)
is_aromatic: bool
charge: int
degree: int (number of bonds)
hyb: int | None (1=sp, 2=sp2, 3=sp3)
in_ring: bool
cycles: set of tuples (ring membership)

Edge attributes set

order: int | str (1, 2, 3, or ":")
is_aromatic: bool
is_in_ring: bool

Dependency Analyzer¶

dependency_analyzer ¶

Dependency analysis for SMARTS patterns with type references.

DependencyAnalyzer ¶

DependencyAnalyzer(patterns)

Analyzes dependencies between SMARTS patterns and computes matching levels.

Attributes:

Name	Type	Description
`patterns`		Dictionary mapping atom type names to their SMARTSGraph patterns
`dependency_graph`	`dict[str, set[str]]`	Adjacency list of dependencies (type -> depends_on)
`levels`	`dict[str, int]`	Dictionary mapping atom type names to their topological levels
`circular_groups`	`list[set[str]]`	List of sets containing types with circular dependencies

Initialize dependency analyzer.

Parameters:

Name	Type	Description	Default
`patterns`	`dict[str, SMARTSGraph]`	Dictionary of {atom_type_name: SMARTSGraph}	required

get_max_level ¶

get_max_level()

Get the maximum level number.

Returns:

Type	Description
`int`	Maximum level, or -1 if no patterns

get_patterns_by_level ¶

get_patterns_by_level(level)

Get all patterns at a specific level.

Parameters:

Name	Type	Description	Default
`level`	`int`	Topological level number	required

Returns:

Type	Description
`list[SMARTSGraph]`	List of SMARTSGraph patterns at that level

has_circular_dependencies ¶

has_circular_dependencies()

Check if there are any circular dependencies.

Returns:

Type	Description
`bool`	True if circular dependencies exist

Graph¶

graph ¶

Module for SMARTSGraph and SMARTS matching logic.

SMARTSGraph ¶

SMARTSGraph(smarts_string=None, parser=None, name=None, atomtype_name=None, priority=0, target_vertices=None, source='', overrides=None, *args, **kwargs)

Bases: Graph

A graph representation of a SMARTS pattern.

This class supports two modes of construction: 1. From SMARTS string (legacy mode) 2. From predicates (new predicate-based mode)

Attributes¶

atomtype_name : str The atom type this pattern assigns priority : int Priority for conflict resolution (higher wins) target_vertices : list[int] Which pattern vertices should receive the atom type (empty = all) source : str Source identifier for debugging smarts_string : str | None The SMARTS string (if constructed from string) ir : SmartsIR | None The intermediate representation (if constructed from string)

Notes¶

SMARTSGraph inherits from igraph.Graph

Vertex attributes

preds: list[Callable] - list of predicates that must all pass

Edge attributes

preds: list[Callable] - list of predicates that must all pass

Graph attributes

atomtype_name: str
priority: int
target_vertices: list[int]
source: str
specificity_score: int (computed)

priority `property` ¶

priority

Get priority for conflict resolution (higher wins).

calc_signature ¶

calc_signature(graph)

Calculate graph signatures for pattern matching.

extract_dependencies ¶

extract_dependencies()

Extract type references from SMARTS IR.

Finds all has_label primitives that reference atom types (e.g., %opls_154). These are parsed by Lark as AtomPrimitiveIR(type="has_label", value="%opls_154").

Returns:

Type	Description
`set[str]`	Set of referenced atom type names (e.g., {'opls_154', 'opls_135'})

find_matches ¶

find_matches(graph)

Return sets of atoms that match this SMARTS pattern in a topology.

Parameters¶

structure : TopologyGraph The topology that we are trying to atomtype. typemap : dict The target typemap being used/edited

Notes¶

When this function gets used in atomtyper.py, we actively modify the white- and blacklists of the atoms in topology after finding a match. This means that between every successive call of subgraph_isomorphisms_iter(), the topology against which we are matching may have actually changed. Currently, we take advantage of this behavior in some edges cases (e.g. see test_hexa_coordinated in test_smarts.py).

from_igraph `classmethod` ¶

from_igraph(graph, atomtype_name, priority=0, target_vertices=None, source='')

Create SmartsGraph from an existing igraph.Graph.

Parameters:

Name	Type	Description	Default
`graph`	`Graph`	igraph.Graph with vertex/edge predicates	required
`atomtype_name`	`str`	Atom type this pattern assigns	required
`priority`	`int`	Priority for conflict resolution	`0`
`target_vertices`	`list[int] \| None`	Which vertices should be typed (empty = all)	`None`
`source`	`str`	Source identifier	`''`

Returns:

Type	Description
`SMARTSGraph`	SMARTSGraph instance

get_priority ¶

get_priority()

Get priority value (supports both new and legacy modes).

get_specificity_score ¶

get_specificity_score()

Compute specificity score for this pattern.

Scoring heuristic

+0 per element predicate (baseline) +1 per charge/degree/hyb constraint +2 per aromatic/in_ring constraint +3 per bond order predicate +4 per custom predicate

Returns:

Type	Description
`int`	Specificity score (higher = more specific)

override ¶

override(overrides)

Set the priority of this SMART

plot ¶

plot(*args, **kwargs)

Plot the SMARTS graph.

SMARTSMatcher ¶

SMARTSMatcher(G1, G2, node_match_fn, edge_match_fn=None)

Inherits and implements VF2 for a SMARTSGraph.

is_isomorphic `property` ¶

is_isomorphic

Return True if the two graphs are isomorphic.

candidate_pairs_iter ¶

candidate_pairs_iter()

Iterate over candidate pairs of nodes in G1 and G2.

subgraph_isomorphisms ¶

subgraph_isomorphisms()

Iterate over all subgraph isomorphisms between G1 and G2.

Typifier¶

Quick reference¶

Canonical example¶

Key behavior¶

Related¶

Full API¶

Base¶

base ¶

TypifierBase ¶

typify abstractmethod ¶

atomtype_matches ¶

OPLS Typifier¶

opls ¶

OplsAtomTypifier ¶

typify ¶

OplsTypifier ¶

typify ¶

GAFF Typifier¶

gaff ¶

GaffAtomTypifier ¶

GaffAtomisticTypifier ¶

Bond Typifier¶

bond ¶

BondTypifier ¶

typify ¶

Angle Typifier¶

angle ¶

AngleTypifier ¶

typify ¶

Dihedral Typifier¶

dihedral ¶

DihedralTypifier ¶

typify ¶

Pair Typifier¶

pair ¶

PairTypifier ¶

typify ¶

Adapter¶

adapter ¶

build_mol_graph ¶

Dependency Analyzer¶

dependency_analyzer ¶

DependencyAnalyzer ¶

get_max_level ¶

get_patterns_by_level ¶

has_circular_dependencies ¶

Graph¶

graph ¶

SMARTSGraph ¶

Attributes¶

Notes¶

priority property ¶

calc_signature ¶

extract_dependencies ¶

find_matches ¶

Parameters¶

Notes¶

from_igraph classmethod ¶

get_priority ¶

get_specificity_score ¶

override ¶

plot ¶

SMARTSMatcher ¶

is_isomorphic property ¶

candidate_pairs_iter ¶

subgraph_isomorphisms ¶

typify `abstractmethod` ¶

priority `property` ¶

from_igraph `classmethod` ¶

is_isomorphic `property` ¶