Getting started

Getting started#

This page provides a small overview of how to install MolFoundry in Python and how to run your first example scripts.

Install#

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

The wheel vendors the JavaScript compute engine, so there is nothing else to install — no Node.js, no pythonmonkey.

Build a molecule#

Create a graph from a SMILES string and inspect it. Passing a name is optional; without one, molecules are auto-named g_{0}, g_{1}, …

import molfoundry as mf

water = mf.smiles("O", "water")

print("name:      ", water.name)
print("SMILES:    ", water.smiles)
print("vertices:  ", water.numVertices, " edges:", water.numEdges)
print("is molecule:", water.isMolecule)
print("exact mass:", round(water.exactMass, 4))
print("InChI:     ", water.inchi)
print("InChIKey:  ", water.inchiKey)

name:       water
SMILES:     O
vertices:   3  edges: 2
is molecule: True
exact mass: 18.0106
InChI:      InChI=1S/H2O/h1H2
InChIKey:   XLYOFNOQVPJJNP-UHFFFAOYSA-N

smiles also accepts InChI and molfiles through the sibling constructors inchi() and molfile(), or you can go through the Graph class methods directly.

Look inside the graph#

A molecule is a labeled graph. Count vertex/edge labels and inspect its symmetry (the automorphism group).

co2 = mf.smiles("O=C=O", "carbon dioxide")

print("carbons:      ", co2.vLabelCount("C"))
print("oxygens:      ", co2.vLabelCount("O"))
print("double bonds: ", co2.eLabelCount("="))
print("automorphisms:", co2.aut())

carbons:       1
oxygens:       2
double bonds:  2
automorphisms: [(), (0 1)]

The two oxygens are interchangeable, so the automorphism group is non-trivial — co2.aut() reports the swap.

Serialize#

Every graph round-trips through GML, which is also molfoundry’s native format for hand-written graphs and rules.

print(co2.getGMLString())

graph [
	node [ id 0 label "O" ]
	node [ id 1 label "O" ]
	node [ id 2 label "C" ]
	edge [ source 0 target 2 label "=" ]
	edge [ source 1 target 2 label "=" ]
]

Where to go next#

  • The API reference documents every public class and function.

  • The Examples page shows complete worked examples: translating an enzyme mechanism into electron-flow rules, and multi-phase stochastic simulation.

Note

Because the compute core is a native engine (SpiderMonkey + a C InChI library), these snippets are executed by a real Python interpreter at build time and their outputs are baked into the page. They do not run in the reader’s browser — a browser-WASM runtime such as Pyodide cannot load the native engine. To let readers edit and re-run cells live, wire up Thebe against a hosted kernel (Binder / JupyterHub); see the notes in docs/README.md.