Minimum Working YAML

Two minimal, complete YAML examples that run without any Python runner code. Copy one, adjust the physical parameters, and run the commands at the bottom. For the full STONE schema, allowed keys, and Boulder-level semantics, see Boulder’s STONE_SPECIFICATIONS.md.

---

Tube furnace (DesignTubeFurnace)

metadata:
  description: "Tube furnace — minimum working example"

phases:
  gas:
    mechanism: gri30.yaml       # use a mechanism from Cantera's built-in library
                                # or provide a path relative to the YAML file

nodes:
  - id: feed
    Reservoir:
      temperature: 298.15       # [K]
      pressure: 101325          # [Pa]
      composition: "CH4:1"

  - id: tube_furnace
    DesignTubeFurnace:
      inlet:
        from: feed
        mass_flow_rate: 3.33e-4   # [kg/s]
      outlet:
        to: outlet
      diameter: 0.08              # [m]
      total_length: 1.0           # [m]
      T_wall_K: 1273.15           # [K]
      T_ambient_K: 300.0          # [K]
      entry_leg: 0.15             # [m]
      exit_leg: 0.15              # [m]
      entry_zone: 0.10            # [m]
      plateau_zone: 0.50          # [m]
      kappa_grey: 0.5             # [1/m]

  - id: outlet
    Reservoir:
      temperature: 298.15
      pressure: 101325
      composition: "N2:1"

export:
  calc_note: "TF_Calculation_Note.xlsx"
  title: "Tube Furnace Baseline"
  reactor_kind: DesignTubeFurnace
  kpi_fn: "bloc.reactor_models:compute_tube_furnace_kpis"
  figures:
    - tube_furnace

---

SPRING (torch → PSR → PFR chain)

metadata:
  description: "SPRING — minimum working example"

phases:
  gas:
    mechanism: gri30.yaml

groups:
  torch_stage:
    stage_order: 1
    mechanism: gri30.yaml
    solve: advance
    advance_time: 2.0e-3          # [s]

  psr_stage:
    stage_order: 2
    mechanism: gri30.yaml
    # Default solver: advance_to_steady_state (τ from ContinuousMixingReactor.t_res_s → volume)

  pfr_stage:
    stage_order: 3
    mechanism: gri30.yaml
    solve: advance
    advance_time: 1.0             # [s]

nodes:
  - id: feed
    Reservoir:
      temperature: 298.15
      pressure: 101325
      composition: "CH4:0.940, C2H6:0.045, N2:0.015"

  - id: torch
    PlasmaTorchInstantaneousHeating:
      group: torch_stage
      t_res_s: 2.0e-3
      torch_eff: 0.80

  - id: psr
    ContinuousMixingReactor:
      group: psr_stage
      t_res_s: 1.0e-3

  - id: pfr
    RefractoryReactor:
      group: pfr_stage
      length: 3.0                 # [m]
      diameter: 0.08              # [m]

  - id: outlet
    Reservoir:
      temperature: 298.15
      pressure: 101325
      composition: "N2:1"

connections:
  - id: feed_to_torch
    MassFlowController:
      mass_flow_rate: 1.0e-3      # [kg/s]
    source: feed
    target: torch

  - id: torch_to_psr
    MassFlowController:
      mass_flow_rate: 1.0e-3
    source: torch
    target: psr

  - id: psr_to_pfr
    MassFlowController:
      mass_flow_rate: 1.0e-3
    source: psr
    target: pfr

  - id: pfr_to_outlet
    PressureController:
      master: psr_to_pfr
      pressure_coeff: 0
    source: pfr
    target: outlet

export:
  calc_note: "SPRING_Calculation_Note.xlsx"
  title: "SPRING Baseline"
  kpi_fn: "bloc.spring_kpi:compute_spring_kpis"
  figures:
    - pfr_profile
    - network

---

Running the YAML

Run and export a standalone Python script (headless):

bloc THE_FILE.yaml --headless --download output.py

Run from Python (headless, no GUI):

from bloc.simulation_builder import build_simulation_from_yaml
sim = build_simulation_from_yaml("THE_FILE.yaml")

Generate the Calculation Note (all scenarios):

from bloc.calc_note import generate_calculation_note_stone
generate_calculation_note_stone("THE_FILE.yaml", output_dir="Results")

Or using the convenience script if present in the model directory:

python run_yaml.py THE_FILE.yaml
python run_yaml_scenarios.py THE_FILE.yaml   # for sweeps: / scenarios: blocks