boulder 0.6.1

A visual interface for Cantera reactor networks

Cantera ReactorNet Visualizer

A web-based tool for visually constructing and simulating Cantera ReactorNet systems.

Architecture: FastAPI (Python backend) + React (TypeScript frontend) with Vite, Tailwind CSS, Zustand, and TanStack Query.

Documentation

• AGENTS.md — setup, verification commands, coding and testing conventions for contributors and agents.
• ARCHITECTURE.md — system design, API, frontend, staged solve, and plugin extension points.
• Sphinx — build with make docs-build; published from docs/ (see Contributing below).

Features

• Interactive graph editor for creating reactor networks (Cytoscape.js)
• Support for various reactor types (IdealGasReactor, Reservoir)
• Support for flow devices (MassFlowController, Valve, Wall)
• Real-time property editing with unit conversion (K/°C)
• Simulation with SSE streaming and live-updating Plotly charts
• Results tabs: Temperature/Pressure plots, Sankey, Thermo reports, Summary
• Monaco YAML editor with syntax highlighting
• Extensible plugin system (JSON-based API)
• Light/dark theme with OS preference detection
• YAML configuration files with 🪨 STONE standard (elegant format)

Installation

As a user (recommended)

Released wheels ship with the React frontend prebuilt, so no Node/npm is required — just install into any Python (e.g. conda) environment:

pip install boulder            # from PyPI

Note: installing straight from a source checkout (pip install git+https://github.com/parks4/boulder.git@main) does not include the GUI: the frontend is only built and bundled when a release wheel is produced. Use the PyPI release (or a wheel from the Releases page) to get the interface without building it yourself.

As a developer (from source)

Clone the repository, create an isolated environment, and build the frontend:

git clone https://github.com/parks4/boulder.git
cd boulder
conda env create -n boulder -f environment.yml
conda activate boulder
pip install -e .         # install in editable mode

# Build the React frontend (emits into boulder/_frontend)
cd frontend
npm install
npm run build
cd ..

Usage

From the CLI

After installation, use the boulder command:

boulder                 # starts the FastAPI server & opens the interface
boulder some_file.yaml  # starts with a YAML preloaded

Optional flags:

boulder --host 0.0.0.0 --port 8050 --debug  # customize host/port, enable auto-reload
boulder some_file.yaml --no-open             # do not auto-open the browser
boulder config.yaml --headless --download output.py  # headless code generation
boulder --dev                                # run in development mode with Vite dev server

Development Mode

You can start both the backend and frontend development server with a single command:

boulder --dev

This will:

• Start the FastAPI backend on port 8050
• Automatically start the Vite dev server (frontend) with hot-reload
• Install frontend dependencies if needed (npm install)

Alternatively, run them separately in two terminals:

# Terminal 1: Backend API
uvicorn boulder.api.main:app --reload --port 8000

# Terminal 2: Frontend dev server (auto-proxies /api to port 8000)
cd frontend
npm run dev

Open http://localhost:5173 in your browser.

From Python

import uvicorn
uvicorn.run("boulder.api.main:app", host="127.0.0.1", port=8000)

Notes:

• Default address is http://127.0.0.1:8050.
• The API documentation is available at http://127.0.0.1:8050/docs (Swagger UI).

Once running, use the interface to:

• Upload existing configurations
• Create new reactor networks
• Edit properties
• Run simulations
• View results

YAML Configuration with 🪨 STONE Standard

Boulder uses YAML format with 🪨 STONE standard (Structured Type-Oriented Network Expressions) - an elegant configuration format where component types become keys containing their properties:

metadata:
  name: "Reactor Configuration"
  version: "1.0"

simulation:
  mechanism: "gri30.yaml"
  time_step: 0.001
  max_time: 10.0

nodes:
  - id: reactor1
    IdealGasReactor:
      temperature: 1000      # K
      pressure: 101325       # Pa
      composition: "CH4:1,O2:2,N2:7.52"

connections:
  - id: mfc1
    MassFlowController:
      mass_flow_rate: 0.1    # kg/s
    source: res1
    target: reactor1

See configs/README.md for comprehensive YAML with 🪨 STONE standard documentation and examples.

Supported Components

Reactors

• IdealGasReactor
• Reservoir

Flow Devices

• MassFlowController
• Valve

Contributing / Developers

Feel free to submit issues and enhancement requests! Before pushing to GitHub, run the following commands:

1. Update conda environment: make conda-env-update
2. Install this package in editable mode: pip install -e .
3. (optional) Sync with the latest template : make template-update
4. (optional) Run quality assurance checks (code linting): make qa
5. (optional) Run tests: make unit-tests
6. (optional) Run the static type checker: make type-check
7. (optional) Build the documentation (see Sphinx tutorial): make docs-build

If using Windows, make is not available by default. Either install it (for instance with Chocolatey), or open the Makefile and execute the lines therein manually.

License

Boulder is released under the MIT License.

Copyright (c) 2025 Spark Cleantech SAS