Scenario reference#
The CLI reads one JSON object per scenario. schema_version must be integer 1.
Unknown root or component keys are rejected. Numeric values must be finite numbers,
not strings or booleans. Fractions lie in [0, 1] unless noted otherwise.
Common fields#
Field |
Required/default |
Meaning |
|---|---|---|
|
Required: |
Input format version |
|
Optional |
Descriptive metadata |
|
Required |
|
|
|
Positive interval duration |
|
|
Generator online fraction; uniformly supplied fuel cannot be rescheduled |
|
Required object |
Route-specific feed amounts and properties |
|
Required except biogas |
Route-specific conversion parameters |
|
Required object |
Electrical and recovered-heat conversion |
|
Empty object |
Electrical loads and heat integration |
Feed amounts are totals per interval. For a rate of 50 kg/h over 24 h, enter
mass_kg: 1200 and duration_h: 24. Increasing duration alone holds total feed
constant, reduces average feed rate and increases fixed auxiliary consumption.
Generator and auxiliary fields#
Object/field |
Default |
Unit or constraint |
|---|---|---|
|
Required |
Fraction greater than zero |
|
|
Fraction; electrical + heat efficiency must be ≤ 1 |
|
|
Gross electrical limit; |
|
|
Standing load during the whole interval, including outages |
|
|
Fraction of gross electricity |
|
|
Additional interval electrical load |
|
|
Fraction greater than zero; resistance-heater convention |
|
|
Fraction of recovered heat suitable for process demand |
The default heat usability of 1 assumes all recovered heat has a suitable
temperature level. Set it explicitly for each case; the thermal examples use zero
where high-temperature heat integration has not been established.
Route-specific feedstock and process objects#
Combustion, gasification and pyrolysis#
feedstock:mass_kg,moisture_fraction(wet basis),dry_lhv_mj_per_kg(> 0).process:fuel_energy_recovery,evaporation_heat_kwh_per_kg_water, optionalprocess_heat_kwh_per_kg_dry(default 0).Specify
routeat the root only. All duties are nonnegative. Recovery is a gross fraction before the explicitly declared process heat. See models.md.
Digestion#
feedstock: the same solid-feed fields as thermal routes.Required
process:volatile_solids_fraction_dry,vs_destruction_fraction,methane_yield_nm3_per_kg_vs_destroyed.Optional
process:methane_fraction(0.6, > 0),capture_fraction(0.98),methane_lhv_kwh_per_nm3(9.94, > 0),process_heat_kwh_per_kg_wet(0).
Wastewater#
feedstock:volume_m3,cod_kg_per_m3.Required
process:cod_removal_fraction,methane_yield_nm3_per_kg_cod_removed(maximum 0.35021875 at the specified normal state).Optional
process:methane_fraction(0.6, > 0),capture_fraction(0.98),methane_lhv_kwh_per_nm3(9.94, > 0),process_heat_kwh_per_m3(0).
Biogas#
Required
feedstock:volume_nm3,methane_fraction(> 0).Optional
feedstock:methane_lhv_kwh_per_nm3(9.94, > 0),capture_fraction(1).Optional
process:process_heat_kwh(0).
All gas volumes use dry gas at 0 °C and 101325 Pa. For measured wet gas, use
x2power.utilities.units.normalize_gas_volume with absolute pressure, temperature
and water-vapour partial pressure. This assumes ideal-gas behaviour.
Minimal complete example#
{
"schema_version": 1,
"name": "Synthetic methane generation example",
"route": "biogas",
"duration_h": 1,
"feedstock": {
"volume_nm3": 100,
"methane_fraction": 0.6,
"methane_lhv_kwh_per_nm3": 10
},
"generator": {
"electrical_efficiency": 0.4
}
}
This produces 240 kWh gross and net electricity, with no declared heat demand, auxiliary consumption or capacity limit. These deliberately simple numbers are an arithmetic example, not recommended equipment parameters.
Outputs#
run returns the route, a shared power ledger and route-specific metrics.
gross_electricity_kwh precedes all declared electrical deductions;
net_electricity_kwh deducts auxiliary and electric-heater inputs.
net_power_kw is the interval-average net output, not peak power.
electric_heating_kwh is separate from auxiliary_electricity_kwh.
fuel_energy_available_kwh describes energy entering the downstream generator
boundary after conversion/capture. unused_fuel_energy_kwh is not automatically
stored or flared. balance_residual_kwh checks this boundary only. See
models.md for each metric’s interpretation.
The compare command writes a compact table with scenario, route, duration,
gross/net kWh and mean net kW. Use run for the complete heat and fuel ledger.