API reference#

This reference documents the public interface re-exported from the top-level molfoundry package – everything listed in molfoundry.__all__. It is generated directly from the source and its type hints, so it always matches the installed version.

Building molecules and graphs#

Constructors that turn a textual description into a Graph, plus the graph data structure itself.

`smiles`	Build a `Graph` from a SMILES string.
`inchi`	Build a `Graph` from an InChI string.
`molfile`	Build a `Graph` from a V2000 or V3000 Molfile string.
`graphGMLString`	Build a `Graph` from a GML string.
`graphDFS`	Build a `Graph` from a GraphDFS line-notation string.
`Graph`
`Vertex`
`Edge`
`VertexRange`
`EdgeRange`
`VertexFilter`

Chemical attributes#

Value types used to label and describe atoms, bonds, and graphs.

`GraphType`
`BondType`
`Charge`	Representation of the charge of an atom.
`Isotope`	Representation of the isotope of an atom.
`AtomId`	Identifies a chemical element and exposes its data from the shared `Atom` table.
`LabelType`
`LabelRelation`
`LabelSettings`
`Conformer`

Rules and rule composition#

Transformation rules and the algebra for combining them.

`ruleGMLString`	Build a `Rule` from a GML string.
`ruleGML`	Build a `Rule` from a GML file.
`ruleDFS`	Build a `Rule` from a RuleDFS line-notation string (`L >> R`).
`ruleMolFoundry`	Build a `Rule` from a MolFoundry online database ID.
`Rule`
`ApplyMode`	Which graphs a rule application may use, given the list of graphs it is applied to.
`RCEvaluator`	Evaluates rule-composition expressions.
`RCExp`	A rule-composition expression.
`rcCommon`
`rcParallel`
`rcSub`
`rcSuper`
`IncidenceConstraint`	Every vertex with a label in `vertexLabels` satisfies `condition`.
`IncidenceCount`	The edges at a vertex number `op` `count`: a leaf of a condition.
`AllOf`	Every child condition holds (true for no children).
`AnyOf`	At least one child condition holds (false for no children).
`Not`	The child condition does not hold.
`CompositionGraph`	One graph of a rule-composition overlap, as seen by a predicate.
`CompositionVertex`	A vertex of a `CompositionGraph`.
`CompositionEdge`	An edge of a `CompositionGraph`.

Rule spans#

Read-only views of a rule’s vertices and edges, from Rule.vertices and Rule.edges. Instead of three separate graphs L, K and R, a rule exposes its span: each element knows how the rule treats it (its Membership) and carries its image on the left side (as matched) and on the right side (as produced), or None where the rule does not have it.

`RuleVertex`	One vertex of a rule's span, identified by its rule node `id`.
`RuleEdge`	One edge of a rule's span, joining two `RuleVertex`.
`RuleVertexSide`	A rule vertex as it appears on one side (left or right) of the rewrite.
`RuleEdgeSide`	A rule edge as it appears on one side (left or right) of the rewrite.
`Membership`	How a rule vertex or edge behaves across the rewrite.

Rule constraints and conditions#

Read-only views of where a rule may match: Rule.matchConstraintsAdjacency, matchConstraintsLabelAny, matchConstraintsShortestPath, matchConstraintsNoEdge and the nested application condition Rule.matchCondition. Vertices are named by rule node id, as in GML. The same classes state the constraints and condition of an identity rule built with Rule.identity. Constraint is the type of any one match constraint, and Condition the type of any node of a condition tree.

`ConstraintOp`	The comparison of an adjacency or shortest-path constraint.
`AdjacencyConstraint`	Vertex `id` has `op` `count` neighbors (GML `constrainAdj`).
`LabelAnyConstraint`	The label (term variable) `label` takes one of `labels` (GML `constrainLabelAny`).
`ShortestPathConstraint`	The shortest path from `source` to `target` has `op` `length` edges (GML `constrainShortestPath`).
`NoEdgeConstraint`	No edge joins `source` and `target` (GML `constrainNoEdge`).
`ConditionTrue`	Always satisfied (`and [ ]` in GML).
`ConditionExists`	The match extends to a larger pattern (GML `exists`) on which `condition` holds.
`ConditionNot`	`condition` does not hold (GML `not`).
`ConditionAnd`	All `operands` hold (GML `and`); true when there are none.
`ConditionOr`	At least one of `operands` holds (GML `or`); false when there are none.
`ConditionVertex`	A vertex a `ConditionExists` adds to the pattern.
`ConditionEdge`	An edge a `ConditionExists` adds between two vertex ids -- rule vertices or ones added by this or an enclosing `exists`.
`Constraint`
`Condition`

Derivation graphs#

Reaction networks built by applying rules, and the objects that describe how each derivation maps atoms.

`DG`
`Derivation`
`Derivations`
`DGVertexMapper`	Enumerates the atom-atom maps of a hyperedge.
`VertexMap`	An atom-atom map of a hyperedge, as a sequence of `VertexMapEntry`.
`VertexMapEntry`	One atom of an atom-atom map.
`MatchApplication`	The result of `DG.Builder.applyMatch()`.
`AutGroup`
`Aut`

Drawing#

Printers and the settings that control how graphs, rules, derivations and derivation graphs are drawn. GraphPrinter styles molecules and rules; DGPrinter styles a whole derivation graph and embeds a GraphPrinter for its molecules. Drawing graphs and rules shows every setting with its result.

`GraphPrinter`
`DrawMode`	The depiction style for a molecule / graph.
`DrawStyle`	The rendering style for a depiction — how strokes and glyphs are drawn.
`GraphLayout`	Which layout engine positions atoms/vertices for a depiction.
`DarkMode`	How an SVG resolves its light/dark theme.
`VertexOverlay`	A marker drawn on top of a graph vertex — a colored shape carrying a short label.
`OverlayShape`	The marker shape a `VertexOverlay` draws on a vertex.
`DGPrinter`	Configures how a derivation graph is rendered by `DG.print()`: which vertices and hyperedges are visible, their captions/labels and colors, and how hyperedges and their rules are labeled.
`DGPrintData`	Controls how a locked derivation graph is laid out for printing.
`Layout`	Which algorithm positions a derivation graph.

Strategies#

The strategy DSL that drives network expansion.

`DGStrat`
`GraphState`
`addUniverse`
`addSubset`
`leftPredicate`
`rightPredicate`
`repeat`
`execute`
`filterUniverse`
`filterSubset`
`revive`

Pathways and integer flow#

Integer hyperflow models over a derivation graph: how often each reaction fires to turn the declared inflow into the declared outflow. FlowModel solves with Gurobi and FlowModelSMT with z3; both return FlowSolution objects, whose certificates give a concrete firing order.

`FlowModel`	A Gurobi integer-flow model over a derivation graph.
`FlowModelSMT`	An SMT (z3) integer-flow model over a derivation graph.
`FlowSolution`	A solved integer hyperflow over a derivation graph: how many times each reaction fires, plus the inflow / outflow on each boundary species.
`FlowSolutionCertificate`	A witness that a `FlowSolution` is realizable: one concrete order in which the reactions fire so that, starting from the inflow marking, no reaction consumes a species before enough of it exists.
`ObjectiveSense`	Whether a flow model's objective is minimized or maximized.

Stochastic simulation#

Rule-based Gillespie simulation with on-demand network expansion.

`Stochsim`	Rule-based Gillespie stochastic simulation with on-demand network expansion.
`MultiPhaseStochsim`	Exact multiphase (multi-compartment) stochastic simulation.
`load_trajectory`	Load a structured `.traj.json` trajectory artifact for downstream analysis.
`Trajectory`	A loaded trajectory artifact, ready for downstream analysis.
`Species`	Per-species metadata from the trajectory artifact (one DG vertex).

Post-processing and global state#

Summary output and the implicit global input collections.

`enable_post`
`disable_post`
`postSection`
`postChapter`
`inputRules`	Built-in mutable sequence.
`inputGraphs`	Built-in mutable sequence.

Script inclusion#

Textual inclusion of one script into another. include() executes a file in the caller’s namespace (its definitions leak into the includer, unlike import) while maintaining a directory-prefix stack so that relative filenames inside the included file resolve relative to it.

`include`	Execute another MolFoundry script in the caller's namespace.
`prefixFilename`	Convert a script-relative path to a working-directory-relative one.
`pushFilePrefix`	Push a prefix consulted by `prefixFilename()`.
`popFilePrefix`	Pop the most recently pushed prefix.
`CWDPath`	Wrap a filename to disable `prefixFilename()` prefixing.

Exceptions#

LogicError

Subpackages#

molfoundry.atomtracing