Skip to content

Running the forward mode: project-run --mode forward

The capstone of the equipment-realism milestone (increment 4b): the closed-loop forward mode (heating + ventilation + CO2 actuators, increments 1-3) is runnable from the CLI, driven by a declarative forward_control block (increment 4a) on the project.

Usage

greenflux project-run projects/greenlight_hps_bleiswijk/project.json --mode forward

--mode is replay (default, measured forcing) or forward (closed-loop actuators). In forward mode the actuator-override CLI flags (--heating-power, --roof-opening, --co2-injection, …) are ignored — heating, ventilation and CO2 are computed by the actuators. --solver defaults to ivp (ventilation cooling is stiff). The project must declare a forward_control block, or the run fails loudly.

What it does

  1. Resolves the case's weather forcing (outside temperature/RH/wind/radiation) — no measured-control overlay, so the actuators are not double-driven.
  2. Builds the unit with the calibration profile and sets the fan flow from forward_control.ventilation.
  3. Resolves project.forward_control into the heating / ventilation / CO2 actuators and their setpoint schedules.
  4. Runs simulate_forward over the case window.
  5. Writes the standard project outputs, reusing the replay writers: timeseries.csv (state + recovered fluxes, via a re-step adapter), summary.json (including the full forward_consumption_ledger), and resources/resource_statistics.* built directly from the ledger (delivered heat, fan electricity, CO2 dosed).

Declaring forward_control

A project-level block (both GreenLight projects ship one). Heating is mandatory; ventilation and CO2 are optional. Setpoints are constant (a value) or day_night (day_value/night_value), in °C (temperature), % (humidity), or ppm (CO2). The CO2 source comes from equipment.co2.

"forward_control": {
  "heating": {"rated_capacity_w_m2": 200.0, "efficiency": 0.9,
              "proportional_gain": 75.0, "integral_gain": 0.2},
  "heating_setpoint": {"mode": "day_night", "day_value": 18.0, "night_value": 17.0},
  "ventilation": {"temperature_proportional_gain": 1.0, "temperature_integral_gain": 0.02,
                  "humidity_proportional_gain": 0.1, "forced_ventilation_flow_m3_s": 5.0,
                  "fan_specific_power_w_per_m3_s": 600.0},
  "ventilation_setpoint": {"mode": "constant", "value": 24.0},
  "humidity_setpoint": {"mode": "constant", "value": 85.0},
  "co2": {"proportional_gain": 0.02, "ventilation_dose_reduction": 1.0},
  "co2_setpoint": {"mode": "day_night", "day_value": 800.0, "night_value": 420.0}
}

The block is optional — projects without it (and the whole replay path) are byte-for-byte unchanged.

Consumption outputs

summary.json carries forward_consumption_ledger with the grounded, actuator-driven totals: heat_delivered_kwh_m2, fuel_gas_kwh_m2, fan_electricity_kwh_m2, co2_dosed_kg_m2, co2_source_fuel_kwh_m2, plus utilization/saturation hours. The resource_statistics report mirrors the delivered-heat / electricity / CO2 totals. This is the "usable models with realistic consumptions" deliverable — driven by capacity-limited, efficiency-accounted actuators rather than replayed measured signals.

Actuator internals: docs/forward_heating_mode.md, docs/forward_ventilation_mode.md, docs/forward_co2_mode.md.