molfoundry.DG#

class molfoundry.DG(labelSettings=LabelSettings(LabelType.String, LabelRelation.Isomorphism), graphDatabase=[])#

Parameters:: graphDatabase (List[Graph])

property id: int#

property labelSettings: LabelSettings#

property graphDatabase: List[Graph]#

property createdGraphs: List[Graph]#

property locked: bool#

property hasActiveBuilder: bool#

property numVertices: int#

property vertices: List[Vertex]#

property numEdges: int#

property edges: List[HyperEdge]#

findVertex(g)#

Parameters:: g (Graph)
Return type:: Vertex

findEdge(sources, targets)#

Parameters:

sources (List[Graph | Vertex])
targets (List[Graph | Vertex])

Return type:

HyperEdge

build()#

Return type:: Builder

print() → None#

print(printer: DGPrinter | None = None) → None

print(printer: DGPrinter | None = None, data: DGPrintData | None = None) → None

Emit a static SVG visualization of the derivation graph.

Every DG vertex renders as an oval-framed molecule depiction (produced by the shared GraphSVGDrawer, in the mode / collapse-H setting picked up from printer) with the graph’s name captioned inside the oval. Every hyperedge with a single source and a single target collapses to a direct arrow labeled with e{id}; every multi-educt or multi-product hyperedge gets a small labeled square “junction” node with arrows from the educts into the junction and from the junction to the products.

Per-atom overlay markers (e.g. for atom tracing) come from the graph printer’s GraphPrinter.pushVertexOverlay() resolver — configure it via printer.graphPrinter and it applies to every vertex’s molecule.

Parameters:

printer (DGPrinter | None)
data (DGPrintData | None)

Return type:

None

svg() → str#

svg(printer: DGPrinter | None) → str

svg(printer: DGPrinter | None = None, data: DGPrintData | None = None) → str

Render the derivation graph to an SVG string and return it — the same visualization print produces, without the summary card wrapper.

Per-atom overlay markers (e.g. for atom tracing) come from the graph printer’s GraphPrinter.pushVertexOverlay() resolver.

Parameters:

printer (DGPrinter | None)
data (DGPrintData | None)

Return type:

str

getSBMLString()#

Serialize the derivation graph as SBML (Systems Biology Markup Language) Level 3 Version 2 text and return it.

Each DG vertex becomes a <species> (named by its graph) and each hyperedge becomes an irreversible <reaction> whose reactant / product stoichiometries are the multiplicities of its source / target vertices. All species share one default compartment.

Returns:: The SBML document as a string.
Return type:: str

class Vertex#

isNull()#

Return type:: bool

property id: int#

property dg: DG#

property inDegree: int#

property inEdges: List[HyperEdge]#

property outDegree: int#

property outEdges: List[HyperEdge]#

property graph: Graph#

class HyperEdge#

isNull()#

Return type:: bool

property id: int#

property dg: DG#

property numSources: int#

property sources: List[Vertex]#

property numTargets: int#

property targets: List[Vertex]#

property rules: List[Rule]#

property inverse: HyperEdge#

vertexMaps(limit=1, vertex_filter=None)#

Parameters:

limit (int)
vertex_filter (Callable[[Vertex], bool] | None)

numMatches(rule)#

The number of distinct matches of rule that produce this hyperedge.

That is how many ways the rule applies to these educts to give these products. The derivation keeps only one of each set of matches related by an educt automorphism; this counts all of them, walking only the matched atoms, so it stays cheap where enumerating vertexMaps() would not.

Every match counts: a rule with an automorphism contributes each of its orientations, and matches differing only in which copy of a species plays which role are distinct. Returns 0 when rule does not produce this hyperedge.

Parameters:: rule (Rule)
Return type:: int

equals(other)#

Parameters:: other (HyperEdge)
Return type:: Tuple[bool, bool]

print() → None#

print(printer: GraphPrinter | None = None) → None

Parameters:: printer (GraphPrinter | None)
Return type:: None

svg() → List[str]#

svg(printer: GraphPrinter | None = None) → List[str]

Render this hyperedge’s derivation(s) to SVG and return the list of SVG strings — the same depictions print shows, without the summary card wrappers. A hyperedge can bundle several derivations, so this returns one SVG string per derivation.

Parameters:: printer (GraphPrinter | None)
Return type:: List[str]

class Builder(dg)#

Parameters:: dg (DG)

property dg: DG#

property isActive: bool#

execute(strategy, verbosity=2, ignoreRuleLabelTypes=False)#

Parameters:

strategy (DGStrat) – The strategy to execute
verbosity (int) –
The verbosity defaults to level 2. The levels have the following meaning:
- 0 (or less): no information is printed.
- 2: Repetition strategies print information for each round.
- 4: All strategies print minimal information.
- 6: Derivation predicate strategies and filtering strategies also print their predicates.
- 8: Rule strategies print minimal information about graph binding.
- 10: Rule strategies print more information about graph binding, including failure due to derivation predicates.
- 50: Print information about morphism generation for rule composition.
- 60: Print rule composition information.
ignoreRuleLabelTypes – Whether rules in the strategy should be checked beforehand for whether they have an associated LabelType which matches the one in the underlying derivation graph.

Return type:

ExecuteResult

apply(graphs, r, mode=ApplyMode.UseAll, verbosity=0, *, onlyProper=None)#

Compute the direct derivations of r on graphs and add them.

mode selects which graphs a derivation may use (see ApplyMode):

ApplyMode.UseAll (default): all of graphs must be used in each direct derivation, each listed graph exactly once. A graph listed twice (or two identical graphs) is two copies, and no further copy is added, so a rule with two left components combines two molecules of a kind only when that kind is listed twice.
ApplyMode.UseAny: a derivation may use any of graphs, each listed graph at most once, again with no further copy added.
ApplyMode.UseAnyMultiplicity: a derivation may use any of graphs, each in as many copies as it needs.

MØD’s onlyProper flag is still accepted: true is UseAll, false UseAny, as in MØD. Returns the hyperedges of the derivations. Rule.numMatches() counts their matches without deriving.

A rule with an empty left side has one match, the empty one. It uses no graph, so its derivation has no educts: a hyperedge without sources whose targets are the components the rule creates, derived under UseAll only when graphs is empty. The empty rule derives the hyperedge without sources or targets, the identity on the empty graph. A rule strategy derives none of these, as each of its derivations uses a graph of the active subset.

Parameters:

graphs (List[Graph])
r (Rule)
mode (ApplyMode | bool)
onlyProper (bool | None)

Return type:

List[HyperEdge]

applyMatch(graphs, r, match)#

Derive r at the given match into graphs and add the derivation.

graphs is the concrete state: each listed graph is one copy, so a graph listed twice is two copies. match maps every vertex of the rule’s left side, by rule vertex id, to (graph index, vertex id): the position of its host graph in graphs and the vertex’s id in that graph. The match alone decides which graphs take part; the ones it does not touch are not educts of the derivation. A rule with an empty left side takes the empty match {}, a derivation without educts.

The match is checked as apply() would admit it: it must embed the left side (labels, edges, the dangling condition, adjacency constraints), keep its components apart, satisfy the rule’s other constraints, and pass the checks of the rewrite itself (an edge the rule creates must not exist yet). Raises LogicError, naming the failing check, otherwise.

Returns a MatchApplication: the hyperedge, whose targets are the products, and the atom map of this match, from which the surviving vertices’ correspondence is read:

edge, vertexMap = builder.applyMatch([ethanol], hToN, {0: (0, 6), 1: (0, 5)})
survivors = [(e.source, e.target) for e in vertexMap
             if e.source is not None and e.target is not None]

Parameters:

graphs (List[Graph])
r (Rule)
match (Mapping[int, Tuple[int, int]])

Return type:

MatchApplication

applyPartialMatch(graphs, r, match, mode=None, *, onlyProper=None)#

Derive r at every match extending a partial one, and add the derivations.

match places some rule vertices as in applyMatch() – rule vertex id to (graph index, vertex id) – and leaves the others free. Every match apply() admits for mode that agrees with the placed vertices is derived; matches related by an automorphism of the educts give one derivation, as in apply().

mode reads graphs as apply() does (see ApplyMode) and decides where the free vertices may go. It defaults to ApplyMode.UseAny: each listed graph is one copy, and a derivation uses the ones the match reaches. MØD’s onlyProper flag is accepted as in apply().

Placed vertices keep their copies: placed on the same listed graph they share its copy, placed on two listings of the same graph they take different copies. A free vertex may land in a placed one’s copy or in another.

The placement is checked for shape as in applyMatch() (rule vertices of the left side, valid positions, no vertex taken twice, one graph per left component), raising LogicError otherwise. A placement that no admitted match extends is no error: it derives nothing. {} derives what apply() does, and a complete placement what applyMatch() does. Returns the hyperedges:

# Every H->N on ethanol's oxygen, wherever the hydrogen is.
edges = builder.applyPartialMatch([water, ethanol], hToN, {0: (1, o.id)})

Parameters:

graphs (List[Graph])
r (Rule)
match (Mapping[int, Tuple[int, int]])
mode (ApplyMode | bool | None)
onlyProper (bool | None)

Return type:

List[HyperEdge]

addDerivation(d)#

Parameters:: d (Derivations)
Return type:: HyperEdge

addHyperEdge(e)#

Parameters:: e (HyperEdge)
Return type:: HyperEdge

addVertex(g)#

Parameters:: g (Graph)
Return type:: Vertex

removeVertex(v)#

Remove a vertex and every hyperedge incident to it.

The vertex’s stable id is retired, not reused, so ids held elsewhere stop resolving.

Parameters:: v (Vertex)
Return type:: None

removeHyperEdge(e)#

Remove a single hyperedge, leaving its endpoint vertices in place.

Parameters:: e (HyperEdge)
Return type:: None

class ExecuteResult(state)#

Bases: object

Parameters:: state (GraphState)

subset()#

Return type:: List[Graph]

universe()#

Return type:: List[Graph]