Bloc CLI reference#

bloc is a thin wrapper around Boulder’s CLI that injects Bloc’s runner and plugin defaults.

In practice, you can use the same subcommands and flags as boulder, but with Bloc behavior enabled by default.

Common commands#

Run a STONE YAML:

bloc path/to/scenario.yaml

Run headless and export generated Python:

bloc path/to/scenario.yaml --headless --download output.py

Validate a YAML without building/running the Cantera network:

bloc validate path/to/scenario.yaml

List plugin sources:

bloc plugins list

List all registered reactor kinds:

bloc describe --list

Inspect one kind (schema, categories, constraints, variable maps):

bloc describe TubeFurnace

Running scenario sweeps#

A model YAML may declare extra cases inline via a top-level scenarios: block (a mapping of id -> overlay) and/or a sweep:/sweeps: block (a Cartesian-product parameter sweep) — see STONE_SPECIFICATIONS.md (Section 14) in the Boulder repo for the full schema. Boulder always adds an unmodified copy of the base config as its own BASELINE entry, first in the run set, whenever scenarios: is declared.

From the GUI#

bloc path/to/scenario.yaml

The “Run Simulation” button in the sidebar is a split button: a small caret/chevron next to it opens a menu with Run Simulation / Force Run / Run Sweep (shows the scenario count, e.g. “Run Sweep (3 scenarios)”) / Add Scenario…. Selecting “Run Sweep” only switches the button’s default action — you still click the (now relabeled) button to actually start it. The right-hand Scenario Pane lists every declared scenario and lets you add, edit, or delete overlays without hand-editing the YAML.

To skip hunting for the caret, pass --sweep instead — the GUI opens with the run-set already running:

bloc path/to/scenario.yaml --sweep

Headless (no GUI)#

bloc path/to/scenario.yaml --sweep --headless

Both flags are required for a headless run. --sweep alone (see above) still opens a web server, just with the run-set auto-started; --headless is what skips the server entirely — every scenario runs end-to-end in the terminal, printing scenario N/M progress and writing <config-stem>_scenarios.h5 next to the YAML. --sweep is a generic Boulder CLI flag that delegates to the host-registered BoulderPlugins.sweep_runner — Bloc points this at boulder.sweep_runner (with BoulderPlugins.converter_class so Bloc’s own mechanisms resolve correctly).

From Python (Calculation Note, all scenarios)#

from bloc.reporting.orchestrator_stone import generate_calculation_note_stone

generate_calculation_note_stone("path/to/scenario.yaml", output_dir="Results")

Expands the same inline scenarios:/sweep: block and solves every case, writing one Excel Calculation Note with all scenarios as columns — independent of the GUI/--sweep path above. See Calculation Note — Reporting Contract for the full picture (KPI functions, figures, workbook layout).

Migration helper commands (Boulder)#

Bloc CLI is the runtime entrypoint for STONE execution, validation and schema inspection. For legacy conversion workflows, Boulder also provides dedicated helpers:

  • sim2stone - convert legacy simulation-style inputs to STONE YAML.

  • stone2sim - export STONE YAML back to simulation-style artefacts.

See the Boulder docs for command details and version-specific options: Boulder documentation.

Why use bloc instead of boulder?#

  • Uses BlocRunner as the default runner class.

  • Sets BOULDER_PLUGINS=bloc.boulder_plugins by default (without overriding an existing value).

  • Keeps command parity with Boulder CLI for day-to-day usage.

Notes#

  • The command requires Bloc to be installed in the current environment (pip install -e . for dev).

  • For project development, use the bloc conda environment.