# Getting started

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

## Install

```{code-block} bash
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}`, …

```{code-cell} python
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)
```

`smiles` also accepts InChI and molfiles through the sibling constructors
{func}`~molfoundry.inchi` and {func}`~molfoundry.molfile`, or you can go through
the {class}`~molfoundry.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).

```{code-cell} python
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())
```

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.

```{code-cell} python
print(co2.getGMLString())
```

## Where to go next

- The {doc}`api/index` documents every public class and function.
- The {doc}`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`.
:::