Metadata-Version: 2.4
Name: boulder
Version: 0.6.3
Summary: A visual interface for Cantera reactor networks
License: MIT License
        
        Copyright (c) 2025 Spark Cleantech SAS
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cantera>=3.0.0
Requires-Dist: h5py>=3.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: types-PyYAML>=6.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.27.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pint>=0.20
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Dynamic: license-file

# Cantera ReactorNet Visualizer

![logo](docs/boulder_logo_small.png)

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](AGENTS.md)** — setup, verification commands, coding and testing conventions for contributors and agents.
- **[ARCHITECTURE.md](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)

![screenshot](docs/mix_streams_example.png)

## 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:

```bash
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](https://github.com/parks4/boulder/releases)) to get the
> interface without building it yourself.

### As a developer (from source)

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

```bash
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:

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

Optional flags:

```bash
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:

```bash
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:

```bash
# 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

```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:

```yaml
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`](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`
1. Install this package in editable mode: `pip install -e .`
1. (optional) Sync with the latest [template](https://github.com/spark-cleantech/package-template) : `make template-update`
1. (optional) Run quality assurance checks (code linting): `make qa`
1. (optional) Run tests: `make unit-tests`
1. (optional) Run the static type checker: `make type-check`
1. (optional) Build the documentation (see [Sphinx tutorial](https://www.sphinx-doc.org/en/master/tutorial/)): `make docs-build`

If using Windows, `make` is not available by default. Either install it
([for instance with Chocolatey](https://stackoverflow.com/questions/32127524/how-to-install-and-use-make-in-windows)),
or open the [Makefile](./Makefile) and execute the lines therein manually.

## License

Boulder is released under the [MIT License](LICENSE).

Copyright (c) 2025 Spark Cleantech SAS
