boulder 0.6.1__tar.gz

boulder-0.6.1/.cruft.json

@@ -0,0 +1,17 @@
+{
+  "template": "https://github.com/spark-cleantech/package-template",
+  "commit": "02767a57f4444fc8413d0e3265a5a0f92d586794",
+  "checkout": null,
+  "context": {
+    "cookiecutter": {
+      "project_name": "boulder",
+      "repo_name": "boulder",
+      "project_author": "Erwan Pannier",
+      "project_short_description": "Cantera Reactor Net Simulations",
+      "copyright_year": "2025",
+      "mypy_strict": false,
+      "_template": "https://github.com/spark-cleantech/package-template"
+    }
+  },
+  "directory": null
+}

boulder-0.6.1/.cursor/skills/boulder-gui/SKILL.md

@@ -0,0 +1,162 @@
+______________________________________________________________________
+
+## name: boulder-gui description: >- Start, drive, and verify the Boulder web GUI (FastAPI + React/Cytoscape) for STONE YAML simulations. Use when the user asks to run a simulation in the browser, test the UI, click nodes, read Thermo/Summary tabs, preload a YAML, or automate E2E checks against localhost:8050. Covers server startup, config loading, graph interaction, results tabs, and API fallbacks when browser canvas clicks fail.
+
+# Boulder GUI
+
+Guide for agents verifying STONE simulations through the web UI or its HTTP API.
+
+## When to use what
+
+| Goal | Prefer |
+|------|--------|
+| Assert outlet T, stream points, staged solve | **HTTP API** (reproducible, no canvas coords) |
+| Visual layout, UX, tab wiring | **Browser MCP** |
+| Custom reactor kinds via plugins | `BOULDER_PLUGINS` + registered plugin package |
+
+Always rebuild frontend after UI changes: `cd frontend && npm run build`.
+
+## Start the server
+
+Default URL: `http://127.0.0.1:8050`. Health: `GET /api/health`.
+
+```bash
+conda activate boulder
+cd frontend && npm run build && cd ..
+boulder path/to/config.yaml --no-open
+# or: boulder --no-open   # empty / default config
+```
+
+Optional plugins (entry points or `BOULDER_PLUGINS` env var) load at startup.
+
+After changing the YAML on disk, **restart the server** — preloaded config is read once at startup.
+
+## UI layout
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Header: [filename.yaml]  Light/Dark                         │
+├──────────────┬──────────────────────────────────────────────┤
+│ Edit Network │         Reactor graph (Cytoscape canvas)       │
+│ Simulate     │         Click nodes/edges to select            │
+│ Properties   │                                              │
+├──────────────┴──────────────────────────────────────────────┤
+│ Results: Plots | Sankey | Thermo | Summary | Convergence    │
+│          (+ plugin tabs e.g. Network)                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+- **Header filename button** — opens YAML editor (Save/Cancel).
+- **Upload Config** — load `.yaml` / `.yml` / `.py` from disk.
+- **Run Simulation (Ctrl+Enter)** — disabled when config has no nodes or a run is in progress.
+- **Properties panel** (left) — selected node/edge fields; stream points and terminal sinks show computed Material Stream (read-only after solve).
+- **Graph** — nodes are circles (reactors) or octagons (reservoirs/sinks); edges are flow devices.
+
+## Standard agent workflow (browser)
+
+Copy and track:
+
+```
+GUI check:
+- [ ] Server up (/api/health)
+- [ ] Preloaded config matches expected YAML (/api/configs/preloaded)
+- [ ] Page shows correct filename (not untitled.yaml)
+- [ ] Run Simulation → completes (Download Python button appears)
+- [ ] Select target node → Thermo tab shows expected T/P/composition
+```
+
+1. Navigate to `http://127.0.0.1:8050/` (hard refresh if assets 404 or MIME errors after a frontend rebuild).
+1. Confirm header shows the expected `*.yaml` name. If it shows `untitled.yaml`, wait for preload toast or reload; click filename to verify YAML content.
+1. Click **Run Simulation** (or wait until enabled).
+1. Wait for **Download Python** and result tabs — not "Running...".
+1. Open **Thermo** tab.
+1. **Select a node** on the graph (see canvas clicks below).
+1. Read `reactor_report` / thermo text in the tab; cross-check via API if critical.
+
+### Graph selection (browser automation)
+
+- The graph is a **Cytoscape `<canvas>`** — node ids are **not** exposed to `browser_search`.
+- **Single click** on a node → selects it (Properties + Thermo).
+- **Double click** on a node within ~300 ms → also switches to **Thermo** tab.
+- **Single click** on a **MassFlowController** edge → selects it and opens **Thermo** (shows source reactor T/P/X and mdot).
+
+**Reliable click pattern (cursor-ide-browser):**
+
+1. `browser_snapshot` with `take_screenshot_afterwards: true`.
+1. Immediately `browser_mouse_click_xy` using **screenshot coordinates** on the node center.
+1. Target must be `<canvas>`, not `#graph-container` or the sidebar grid.
+1. If click fails, take a **fresh** screenshot before retrying (cache invalidates).
+
+Clicks are fragile at narrow viewports — resize browser wider if needed. When automation cannot select a node, use the **API verification** below; do not loop on coordinates.
+
+## Results tabs
+
+| Tab | Needs selection? | Content |
+|-----|------------------|---------|
+| **Plots** | No | Time series after transient runs |
+| **Sankey** | No | Species / energy flows (plugin may customize) |
+| **Thermo** | **Yes** — node or MFC | `reactor_report`, full Cantera `thermo_report` |
+| **Summary** | No | Elapsed time, text summary |
+| **Convergence** | No | Staged-solve progress (redirects residence profiles to Plots when applicable) |
+| **Network** | Plugin | Live reactor network view |
+
+Terminal **OutletSink** nodes: post-solve thermo comes from `_refresh_terminal_sinks` (legacy path). **Inter-stage stream-point** diamonds (`{source}_outlet`) are refreshed during staged solve — preferred for multi-stage models.
+
+## API verification (preferred for agents)
+
+Same server session as the browser. See [reference.md](reference.md) for full scripts.
+
+Quick checks:
+
+```python
+import json, urllib.request
+
+base = "http://127.0.0.1:8050"
+pre = json.loads(urllib.request.urlopen(f"{base}/api/configs/preloaded").read())
+assert pre["preloaded"]
+```
+
+Start simulation → poll results:
+
+```python
+import time
+req = urllib.request.Request(
+    f"{base}/api/simulations",
+    data=json.dumps({"config": pre["config"]}).encode(),
+    headers={"Content-Type": "application/json"},
+    method="POST",
+)
+sim_id = json.loads(urllib.request.urlopen(req).read())["simulation_id"]
+for _ in range(120):
+    st = json.loads(urllib.request.urlopen(
+        f"{base}/api/simulations/{sim_id}/results").read())
+    if st.get("is_complete") or st.get("status") == "error":
+        break
+    time.sleep(0.5)
+
+reports = st["reactor_reports"]
+T_K = reports["outlet"]["T"]
+assert T_K > 300, f"outlet stuck at placeholder T: {T_K} K"
+```
+
+Assert invariants on `updated_nodes` / `updated_connections` when testing staged networks (stream points present, no duplicate interface edges).
+
+## Common failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `untitled.yaml`, Run disabled | No preload; empty default | Start with YAML arg or Upload Config |
+| Outlet 25 °C / N2 | Terminal `Reservoir` placeholder, or stale preload | Use `OutletSink: {}`; restart server |
+| `Unsupported reactor type` | Kind not in core Boulder; plugin not loaded | Set `BOULDER_PLUGINS`; restart server |
+| JS chunk MIME `text/html` | Stale frontend hash or SPA catch-all | `npm run build`, restart server, hard refresh |
+| Thermo says "Select a node…" | Nothing selected, or canvas click missed | Retry canvas click or use API |
+| Properties Material Stream empty | `terminal_sink` not in `updated_nodes` yet | Thermo tab / API `reactor_reports` still authoritative |
+
+## Dev mode (human)
+
+`boulder --dev` — Vite on `:5173` proxies `/api` to backend. Agents testing production-like behavior should use built `frontend/dist` (default server).
+
+## Further reading
+
+- [reference.md](reference.md) — SSE stream, upload endpoint, browser checklist
+- Repo [AGENTS.md](../../../AGENTS.md) — conda env, `make qa`, targeted tests

boulder-0.6.1/.cursor/skills/boulder-gui/reference.md

@@ -0,0 +1,89 @@
+# Boulder GUI — API & automation reference
+
+Base URL assumed: `http://127.0.0.1:8050`.
+
+## Endpoints
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/api/health` | Liveness |
+| GET | `/api/configs/preloaded` | Config loaded at server start (`preloaded`, `config`, `yaml`, `filename`) |
+| GET | `/api/configs/default` | Built-in empty template |
+| POST | `/api/configs/upload` | Multipart YAML/YML/PY upload |
+| POST | `/api/configs/validate` | Validate normalized config JSON |
+| POST | `/api/simulations` | Body: `{"config": {...}}` → `{simulation_id}` |
+| GET | `/api/simulations/{id}/stream` | SSE progress (`complete`, `error`, partial updates) |
+| GET | `/api/simulations/{id}/results` | Full results when done; `status: running` while active |
+
+## SSE stream (browser-equivalent completion)
+
+```python
+import urllib.request, json
+
+sim_id = "..."  # from POST /api/simulations
+with urllib.request.urlopen(
+        f"http://127.0.0.1:8050/api/simulations/{sim_id}/stream") as r:
+    event = None
+    while True:
+        line = r.readline().decode().strip()
+        if not line:
+            continue
+        if line.startswith("event:"):
+            event = line[6:].strip()
+        elif line.startswith("data:") and event in ("complete", "error"):
+            payload = json.loads(line[5:])
+            print(event, payload.get("error_message"))
+            break
+```
+
+On `complete`, payload includes `reactor_reports`, `updated_nodes`, `updated_connections`, `sankey_*`, `summary`, `elapsed_time`.
+
+## Results shape (thermo checks)
+
+```python
+reports = payload["reactor_reports"]  # dict[node_id → report]
+report = reports["outlet"]
+report["T"]       # K
+report["P"]       # Pa
+report["X"]       # mole fractions dict
+report["reactor_report"]   # human-readable multi-line str
+report["thermo_report"]    # Cantera phase report str
+```
+
+Reservoir / OutletSink entries use the reservoir branch of `_generate_reactor_reports` (fixed-state wording in `reactor_report` even when T reflects solved outlet).
+
+## Preloaded vs client config
+
+The UI sends the **in-memory normalized config** from Zustand (`useConfigStore`) to `POST /api/simulations`, not a re-read of disk. After server restart, the browser reload pulls fresh preload via `GET /api/configs/preloaded` on mount (`AppShell.tsx`).
+
+If the header filename is wrong, the client may still hold an old config — reload the page.
+
+## Browser MCP tool sequence
+
+```
+browser_navigate → http://127.0.0.1:8050/
+browser_snapshot (take_screenshot_afterwards: true)
+browser_click → Run Simulation button ref
+# wait until "Download Python" appears in snapshot
+browser_click → Thermo tab
+browser_snapshot (take_screenshot_afterwards: true)
+browser_mouse_click_xy → screenshot coords on target node (target: canvas)
+browser_snapshot → read Thermo panel text in screenshot / search if rendered
+```
+
+Unlock browser when finished: `browser_lock` action `unlock`.
+
+## Plugins
+
+Custom reactor kinds register via `boulder.plugins` entry points or the `BOULDER_PLUGINS` environment variable (dotted module path). The CLI may also pass `--runner PKG.MOD:CLASS` for a custom load/normalize pipeline.
+
+Symptom: `Unsupported reactor type: 'MyKind'` → plugin package not loaded or builder not registered.
+
+## Frontend rebuild
+
+```bash
+conda activate boulder
+cd frontend && npm run build
+```
+
+Restart uvicorn after backend or static asset changes.

boulder-0.6.1/.cursorignore

@@ -0,0 +1,8 @@
+#configs/  # Add directories or file patterns to ignore during indexing (e.g. foo/ or *.csv)
+*.yaml
+!configs/default.yaml       # except from this one
+!configs/mix_react_streams.yaml
+!configs/grouped_nodes.yaml
+!examples/mix1.yaml
+*.csv
+*.json

boulder-0.6.1/.cursorrules

@@ -0,0 +1,21 @@
+These are the Lead developer instructions.
+
+Follow the development guidelines :
+
+CODING
+- Keep line length under 110 characters
+- Don't wrap code in try except blocks unless you're catching a specific exception.
+- Better raise a clear error message than hide the problems/fix in the back of the user.
+
+TESTING
+- Use test-driven development
+- Fix library code, not tests
+- Run tests in 'boulder' conda env. It contains `node`.
+- Frontend build runs from `frontend` with `npm run build`. Always rebuild the frontend after changes.
+- After successful tests, use `make qa` for code quality.
+- Do not implement mock tests, only real tests.
+- Explicit describe in the test docstrings what is asserted in the test.
+- For E2E tests also, explicitely state in the docstrings what is assessed.
+
+VERSIONING
+- Never perform git commits

boulder-0.6.1/.github/workflows/on-push.yml

@@ -0,0 +1,193 @@
+name: on-push
+
+on:
+  push:
+    branches:
+    - main
+    tags:
+    - '*'
+  pull_request:
+    branches:
+    - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash -l {0}
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: 3.x
+    - uses: pre-commit/action@v3.0.1
+
+  combine-environments:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: 3.x
+    - name: Install conda-merge
+      run: |
+        python -m pip install conda-merge
+    - name: Combine environments
+      run: |
+        for SUFFIX in ci integration; do
+        conda-merge ci/environment-$SUFFIX.yml environment.yml > ci/combined-environment-$SUFFIX.yml || exit
+        done
+    - uses: actions/upload-artifact@v4
+      with:
+        name: combined-environments
+        path: ci/combined-environment-*.yml
+
+  unit-tests:
+    name: unit-tests
+    needs: combine-environments
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11']
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/download-artifact@v4
+      with:
+        name: combined-environments
+        path: ci
+    - name: Get current date
+      id: date
+      run: echo "date=$(date +%Y-%m-%d)" >> "${GITHUB_OUTPUT}"
+    - uses: mamba-org/setup-micromamba@v2
+      with:
+        environment-file: ci/combined-environment-ci.yml
+        environment-name: DEVELOP
+        cache-environment: true
+        cache-environment-key: environment-${{ steps.date.outputs.date }}
+        cache-downloads-key: downloads-${{ steps.date.outputs.date }}
+        create-args: >-
+          python=${{ matrix.python-version }}
+    - name: Install package
+      run: |
+        python -m pip install --no-deps -e .
+    - name: Run tests
+      run: |
+        make unit-tests COV_REPORT=xml
+
+  type-check:
+    needs: [combine-environments, unit-tests]
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/download-artifact@v4
+      with:
+        name: combined-environments
+        path: ci
+    - name: Get current date
+      id: date
+      run: echo "date=$(date +%Y-%m-%d)" >> "${GITHUB_OUTPUT}"
+    - uses: mamba-org/setup-micromamba@v2
+      with:
+        environment-file: ci/combined-environment-ci.yml
+        environment-name: DEVELOP
+        cache-environment: true
+        cache-environment-key: environment-${{ steps.date.outputs.date }}
+        cache-downloads-key: downloads-${{ steps.date.outputs.date }}
+        create-args: >-
+          python=3.11
+    - name: Install package
+      run: |
+        python -m pip install --no-deps -e .
+    - name: Run code quality checks
+      run: |
+        make type-check
+
+  frontend-tests:
+    name: frontend-tests
+    needs: [unit-tests]
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: 'npm'
+        cache-dependency-path: frontend/package-lock.json
+    - name: Install frontend dependencies
+      working-directory: frontend
+      run: npm ci
+    - name: Run frontend unit tests
+      working-directory: frontend
+      run: npm run test:unit
+    - name: Type check frontend
+      working-directory: frontend
+      run: npm run type-check
+    - name: Build frontend
+      working-directory: frontend
+      run: npm run build
+
+  docs-build:
+    needs: [combine-environments, unit-tests]
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/download-artifact@v4
+      with:
+        name: combined-environments
+        path: ci
+    - name: Get current date
+      id: date
+      run: echo "date=$(date +%Y-%m-%d)" >> "${GITHUB_OUTPUT}"
+    - uses: mamba-org/setup-micromamba@v2
+      with:
+        environment-file: ci/combined-environment-ci.yml
+        environment-name: DEVELOP
+        cache-environment: true
+        cache-environment-key: environment-${{ steps.date.outputs.date }}
+        cache-downloads-key: downloads-${{ steps.date.outputs.date }}
+        create-args: >-
+          python=3.11
+    - name: Install package
+      run: |
+        python -m pip install --no-deps -e .
+    - name: Build documentation
+      run: |
+        make docs-build
+        # create docs in html/
+      # From https://github.com/marketplace/actions/sphinx-build
+    - uses: actions/upload-pages-artifact@v3
+      with:
+        path: docs/_build/html/
+
+  # Deployment job.
+  deploy:
+    needs: docs-build
+
+    # Deploy only when the main branch is pushed.
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment.
+    permissions:
+      contents: read
+      pages: write # To deploy to Pages.
+      id-token: write # To verify the deployment originates from an appropriate source.
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

boulder-0.6.1/.github/workflows/release.yml

@@ -0,0 +1,88 @@
+name: Build and Publish on Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build wheel + sdist (with bundled frontend)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write    # upload artifacts to the GitHub release
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0    # Fetch all history for setuptools_scm to work
+
+    - name: Set up Node
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: 'npm'
+        cache-dependency-path: frontend/package-lock.json
+
+    - name: Build frontend
+      working-directory: frontend
+      run: |
+        npm ci
+        npm run build    # emits into boulder/_frontend (see vite.config.ts)
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build setuptools setuptools_scm wheel
+
+    - name: Build wheel and source distribution
+      run: python -m build
+
+    - name: Verify frontend is bundled in the wheel
+      run: |
+        python -m zipfile -l dist/*.whl | grep -q "boulder/_frontend/index.html" \
+          && echo "OK: frontend bundled in wheel" \
+          || (echo "ERROR: frontend missing from wheel" && exit 1)
+
+    - name: Display build artifacts
+      run: ls -lh dist/
+
+    - name: Upload artifacts to the GitHub release
+      uses: softprops/action-gh-release@v2
+      with:
+        files: |
+          dist/*.whl
+          dist/*.tar.gz
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Store distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/boulder/
+    permissions:
+      id-token: write    # mandatory for PyPI Trusted Publishing (OIDC)
+
+    steps:
+    - name: Download distribution packages
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+    - name: Publish distribution to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1