BCNexus_v2.0.0 — 2026年07月19日

Modular workflow, full CLEW plotting suite, and a self-contained scenario report.
Backwards compatible: RunModel.run() and the existing notebook path are unchanged.
See CHANGELOG.md for detail.

Calibration Note

• A guard added to sets_n_ratios.py now skips agricultural land-use modes whose
  cluster-mean crop yield falls below 1e-4 after calibration. The change removes
  OutputActivityRatio coefficients at the 1e-8 to 1e-7 scale from the LP matrix. These
  coefficients contributed to a 14 order of magnitude coefficient range that caused the
  Gurobi barrier method to stall with sub-optimal termination. The change alters model
  structure only for cluster and crop combinations with negligible production potential.

check yield_guard_change_note.md for more details

Added

• Stage-level pipeline (bcnexus/stages.py) + Snakemake/DVC scaffold (workflow_v3/) —
  resumable, parallel multi-scenario runs.
• 20+ new plots across all four CLEW dimensions, including a new plot_Water.py
  module and a year-slider nexus Sankey.
• Shared colour palette (bcnexus/vis/palette.py) — one colour per legend entry
  across every figure and scenario.
• Combined tabbed HTML report (vis/report.py + template): Inputs and Outputs tabs with
  sticky C/L/E/W sub-tabs, scenario description, layout/font/dark-mode controls, works
  offline, and optional panels for run, solver and constraint diagnostics.
• Master report index (bcnexus/vis/index.py → report/BCNexus_report_v1.html): a
  landing page plus cascading dropdowns over scenario, timeslices, storage algorithm,
  solver and run date, built by parsing the report filenames. Rebuild with make index;
  make results and make workflow do it automatically.
• Reference energy system written as its own full-viewport page per scenario
  (CLEW_model_map_<scenario>_<date>.html).
• make interface for the whole workflow (make run | solve | workflow | index,
  make help), with a make.bat shim for Windows. Existing environment and legacy
  targets are unchanged.
• AGENTS.md — contract for AI agents and new contributors: layer ownership, the
  six-stage pipeline, the plot/palette/template separation, and the rules that keep a
  contribution safe (no bulk deletes, no invented data, prescribed inputs are not results).
• Notebook UI: multi-scenario selection, solver/compiler/threads/storage controls,
  and an interactive temporal-resolution guide.

Changed

• run() split into six composable stages; output paths now deterministic
  (run_dir()), timestamp runtag removed from result folders.
  ⚠️ Update any script globbing *ts_csvs_<solver>_<runtag>.
• datapackage.get_dataframe() → get_df() (alias kept).
• get_plots() writes the combined report by default (save_individual=False).
• Per-run reports are now scoped to results: GitHub, About-the-model and the Delta E+
  mark moved to the master index. Reports default to light, the index to dark.

Fixed

• Hardcoded 24-timeslice label in the generation-timeseries plot.
• Energy/Climate colour mismatch (code-keyed colour maps vs label legends).
• Land-use change plot double-counted area (cover and crop layers now separate);
  intermediate/low-input GAEZ regimes no longer dropped.
• Nexus Sankey under-reported flows (DEMTRA/DEMPWR missing from the sector map);
  now reconciles exactly with the result CSVs.
• Run diagnostics missing from the report (runtime log written after the plotter ran).
• Duplicate rows on rebuild; latent str / Path error in the runtime logger.

Pending

• include_livestock=True outputs need review.
• Irrigation water coefficients and industrial-biomass CO2 accounting need review.