MolFoundry by Examples

A hands-on tour of MolFoundry for chemists. MolFoundry treats molecules as labeled graphs and reactions as graph-rewrite rules: a set of molecules together with a set of rules — a grammar — expands into a derivation graph, the reaction network of everything reachable from the starting compounds. From there you can draw the network, search it for pathways, and simulate it.

• Molecules
  • Molecules from SMILES
  • Molecules in GML
  • Complex group labels
• Reactions
  • Writing a rule in GML
  • The DFS line notation
  • Terms: label variables
  • Rule composition
• Reaction networks
  • From a grammar to a derivation graph
  • Oro’s adenine synthesis
  • Pathways and integer flow
  • Depicting derivation graphs
• Working with molecular graphs
  • The adjacency list
  • Removing hydrogens
  • The Wiener index
  • The automorphism group
  • Simple cycles
• Stochastic simulation
  • Atrazine degradation
• Input and output

Running the examples

MolFoundry’s rewriting engine runs in-process behind a small, chemist-friendly Python API. Install the package once:

pip install --extra-index-url https://py.molfoundry.de/dl/ molfoundry

There are two equivalent ways to run a script. As an ordinary Python program:

python 01_visualizing_molecules.py

or through the bundled molfoundry command, which preloads the whole API and turns summary generation on — the same ergonomics as running a script through a dedicated interpreter wrapper:

molfoundry -f 01_visualizing_molecules.py     # run a script file
molfoundry -e 'smiles("O").print()'           # run a one-off snippet
molfoundry -f rules.py -f build.py            # -f / -e may be repeated and interleaved
molfoundry -i -f setup.py                     # drop into an interactive session afterwards
molfoundry --nopost -f quick.py               # skip writing the HTML summary

(The same runner is reachable as python -m molfoundry.cli when the console script is not on your PATH.)

The HTML summary

Anything you draw with .print() is collected into a self-contained summary/summary.html report, written next to the script when the process exits. Turn it on with enable_post():

from molfoundry import smiles, enable_post
enable_post()
smiles("CC(=O)C(=O)O", "pyruvate").print()   # a depiction is appended to summary.html

Open summary/summary.html in a browser to see the rendered molecules, rules and derivation graphs. In this guide the same depictions are rendered inline as SVG.

Where to go next

• The file-format guides cover SMILES, GML, InChI, Molfile and RMG input in depth.

• The graph-rewriting guide develops the double-pushout formalism and nested application conditions behind the rules used here.

• The API reference documents every class and function.