# Build a reaction network

Validate starting species and elementary steps, save sourced proposals and attach calculation evidence.

Build a reaction network by validating your starting mixture and proposed elementary steps first, then attaching simulation, transition-state, and DFT evidence to each step.

## 1. Dry-run your proposed network

Open your project in the [web workspace](https://app.chemistry.tools) or connect an AI agent via the chemistry MCP server.

Before writing anything to the project, validate the full network with `checkReactionNetwork`. If you are using an MCP-connected agent, ask:

> Run `checkReactionNetwork` for my project using these starting species, elementary reaction SMILES, and target species. List any atom/charge balance errors, missing reactants, or unreachable targets.

`checkReactionNetwork` takes:

- **`startingSpecies`** — Reactants, reagents, catalysts, and solvents present at the start.
- **`reactions`** — Proposed elementary steps (one bond-breaking/forming event per step) with SMILES and source rationale.
- **`targets`** — Products or intermediates you expect the network to reach.
- **`projectId`** _(optional)_ — Includes species already saved in your project.

## 2. Fix validation errors before running calculations

`checkReactionNetwork` runs the exact same chemistry rules used when saving proposals and returns a valid topological write order. Fix any reported issues first:

- **Atom and charge balance:** Every reaction must conserve both elemental counts and net charge.
- **Single elementary steps:** Split multi-step shorthand reactions into individual elementary transformations with explicit intermediates.
- **Reachable reactants:** Every reactant in a step must either be in `startingSpecies`, already exist in the project, or be produced by an earlier step.
- **Sourced rationale:** Literature or mechanistic proposals must include their source reference and rationale.

## 3. Save the validated network

Once `checkReactionNetwork` passes with zero errors, save the network atomically with `addReactionNetwork`:

- **Batch write (`addReactionNetwork`):** Saves all starting species and reactions in dependency order in a single transaction. If any item fails validation, nothing is written.
- **Single additions (`addSpeciesProposal` / `addReactionProposal`):** Add one species or elementary step to an existing network.

> **Important:** A saved reaction proposal is a **hypothesis**, not proof that the pathway occurs.

## 4. Attach calculation evidence to each pathway

Once your proposed steps are in the project, run calculations to test which pathways actually operate and compete:

| Evidence type               | What it adds to the network                                        | Guide                                                               |
| --------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------- |
| **Molecular dynamics**      | Observed reaction events and atom mappings from trajectories       | [Run molecular simulations](/science/simulations/)                  |
| **Transition-state search** | Saddle-point geometries verified by Hessian + IRC                  | [Search and verify a transition state](/science/transition-states/) |
| **Single-point DFT**        | Electronic energies on stored reactant, TS, and product geometries | [Evaluate DFT energies](/science/dft/)                              |
| **Kinetic modeling**        | Concentration profiles over time for a chosen rate model           | [Simulate a reaction network](/science/kinetics/)                   |

Keep charge, spin multiplicity, and level of theory consistent whenever you compare competing barriers across the network.