Plotting and a reproducible worked example#
Plotting is an optional layer over the same simulation results used by the CLI and Python API. It does not change the conversion equations or apply hidden corrections. Install from the repository with:
python -m pip install -e '.[plots]'
Core simulations still run without Matplotlib. The plotting functions use an
explicit non-interactive canvas, work without a display server, and return a
Matplotlib Figure for further customization. No pyplot global figure manager
or GUI backend is initialized.
One scenario from the CLI#
x2power plot use_cases/scenarios/biomass_gasification.json -o results/energy_balance.svg
The file extension selects PNG, SVG or PDF. Missing parent directories are created. An unsupported extension or missing plotting dependency returns a clear CLI error.
Python API#
from x2power.scenario import run_scenario
from x2power.utilities.io import load_scenario
from x2power.utilities.plotting import plot_energy_balance, save_figure
config = load_scenario("use_cases/scenarios/biomass_gasification.json")
result = run_scenario(config)
figure = plot_energy_balance(result, title="Synthetic gasification example")
save_figure(figure, "results/energy_balance.png", dpi=180)
Function |
Input |
Interpretation |
|---|---|---|
|
One |
Signed electrical deductions and thermal heat allocation |
|
Rows returned by |
Gross/net interval electricity versus one numeric input |
|
Sequence returned by |
Interval-mean power against actual elapsed hours |
|
Sequence of sampled net kWh |
Histogram counts and empirical p05/p50/p95 values |
|
Figure and output path |
PNG/SVG/PDF export with optional DPI |
Worked example#
python use_cases/visual_report.py --output-dir results/visual_report
The script uses three existing synthetic configurations and produces four figures:
Electricity and process heat. The gasification case starts with gross generation, deducts auxiliaries and electric-heater consumption, and ends at net electricity. Deductions have negative signs; negative net output is preserved. The heat panel distinguishes recovered heat used, recovered heat not used and heat supplied by the electric heater. Electrical heater input and delivered thermal heat differ when heater efficiency is below one.
Moisture sensitivity. Wet feed remains fixed at 4000 kg over 24 h. Moisture increases from 0 to 0.9 in steps of 0.05. Less dry material means less chemical energy, while more water increases evaporation duty. The net curve can cross zero even while gross generation remains positive. These are steady calculations with fixed recovery/efficiency parameters, not a stability prediction for a reactor.
Operating profile. Biogas flow changes over intervals of 6, 8, 2 and 8 hours. A generator outage occupies hours 14–16. The plot uses the true interval widths; electrical power multiplied by each duration recovers that interval’s energy. Feed processing and standing loads continue during the outage, producing negative net output and unused fuel. There is no assumed gas storage.
Uncertainty sampling. Food-waste digestion is evaluated 1000 times with seed 42. VS destruction, methane yield and generator efficiency are sampled independently from the script’s uniform bounds. Quantiles describe those assumed distributions, not measured confidence in equipment performance.
Output files and reproducibility#
Output |
Contents |
|---|---|
|
Electrical waterfall and heat allocation |
|
Gross and net electricity across moisture values |
|
Electrical and thermal powers over elapsed time |
|
Sample distribution and empirical quantiles |
|
Input fraction, gross/net kWh and mean net kW |
|
Start/end hours and mean electrical/thermal powers |
|
Input configurations, settings, simulator version, full results and all draws |
The example can run from any working directory after package installation. It resolves input files relative to the script and writes to the requested output directory. Rerunning with the same code and inputs reproduces the numerical JSON. Rendered pixels may vary with Matplotlib, fonts and platform versions. SVG element identifiers are stable and generated timestamps are suppressed on SVG/PDF export.
The figures in this documentation are generated by the same script; they are not
manually drawn. To refresh them, run the example and copy only its
moisture_sensitivity.svg and operating_profile.svg into docs/figures/.
Keep the full generated datasets in results/, which is excluded from version control.
See model equations and limitations and validation guidance for the physical assumptions. The rendering implementation follows the public Matplotlib Figure API and non-interactive canvas example.