GitHub

<!– This file is generated from CHANGELOG.md by docs/scripts/update_changelog.jl. –>

Changelog

All notable changes to MacroEnergy.jl will be documented in this file.

The format is based on Keep a Changelog, and this project follows Julia package versioning through Project.toml releases.

[Unreleased]

Added

  • Added @add_to_balance for appending raw terms to an existing named balance.
  • Added @add_to_storage_balance as the preferred helper for extending storage law-of-motion balances.
  • Added @inspect_stoichiometric_balance to inspect the pairwise equations generated by @add_stoichiometric_balance.
  • Added focused single-asset solve tests under test/asset_tests to validate migrated asset balances against manual algebraic rewrites where appropriate.
  • Added scaling functionality for input data. New ParameterScaling (default false) and ParameterScalingFactor (default 1e3) parameters have been added to case settings.

Changed

  • @add_balance is now the recommended API for ordinary algebraic balance equations and inequalities, and follows standard algebraic sign conventions for flow(...) terms.
  • @add_balance now validates balance expressions more strictly and rejects unsupported non-flow(...) variable terms.
  • @add_stoichiometric_balance now expands recipe-style balances using a consistent proportional rule around the selected base_term.
  • Asset balance definitions have been migrated away from legacy raw balance_data = Dict(...) patterns toward @add_balance, @add_to_storage_balance, and @add_stoichiometric_balance.
  • Updated MacroEnergySolvers.jl version to 0.2.2.

Documentation

  • Expanded the balance documentation with guidance on choosing between balance macros, stoichiometric coefficient bases, pairwise expansion limits, multi-term algebraic balances, common mistakes, and numerical sensitivity.
  • Updated modeler documentation to include balance APIs in the asset-construction workflow and to recommend a small single-asset regression test for each new asset.
  • Updated debugging guidance around balance_data, get_balance, and @inspect_stoichiometric_balance.
  • Updated asset-specific documentation examples to use the balance macros instead of legacy raw balance dictionaries.

Migration guide

  • When updating an asset, prefer @add_balance for ordinary algebraic equalities and inequalities, prefer @add_to_storage_balance for storage law-of-motion terms, and use @add_stoichiometric_balance only when the relationship is naturally a recipe-style proportional conversion.
  • Legacy raw balance dictionaries should usually be replaced with explicit balance macros. For example:
transform.balance_data = Dict(
    :energy => Dict(
        output_edge.id => coeff,
        input_edge.id => 1.0,
    ),
)

can become:

@add_balance(transform, :energy, flow(output_edge) == coeff * flow(input_edge))

or, when the relationship is best represented as a recipe:

@add_stoichiometric_balance(
    transform,
    :production,
    coeff * flow(input_edge) --> flow(output_edge),
    flow(output_edge),
)
  • Use @add_balance when the relationship is easiest to write as an explicit equation, includes three or more independently varying terms, or is not just a set of pairwise proportional relations.
  • Use @add_stoichiometric_balance when one base_term should anchor several proportional relationships and all coefficients can be written on a common recipe basis.
  • In one @add_stoichiometric_balance expression, all coefficients must share a common basis. For example, if the base term is product output, coefficients should usually be expressed per unit output; if the base term is fuel input, coefficients should usually be expressed per unit fuel.
  • When extending the :storage balance of a storage component, use @add_to_storage_balance(storage, coeff * flow(edge)). In normal usage, write positive magnitudes for both inflows and outflows and let MacroEnergy apply the effective sign through edge direction.
  • During migration, inspect generated pairwise equations with @inspect_stoichiometric_balance(...), inspect stored coefficients with balance_data(component, balance_id), inspect compiled expressions with get_balance(component, balance_id), and validate the asset with a small single-asset solve test.
  • Small differences in large-system results do not automatically indicate a balance bug. Algebraically equivalent formulations can change row scaling and solver tie-breaking in large, near-degenerate systems, so localized single-asset regression tests are the primary evidence that migrated balances remain correct.

[0.2.0] - 2026-05-22

Added

  • Outputs can now be written to a JSON file using the write_to_json method. This method writes to a compressed .json.gz but also supports regular .json outputs. It is not currently built into any of the run tools.
  • Improved JSON serialization coverage of commodities, storage, constraints, dual values, time data, solution algorithms, named tuples, JuMP containers, and special numeric values like Inf, -Inf, and NaN

Changed

  • CSV asset input files can now have their Type and Id columns in any position in the file, instead of needing to be in the first two columns. The Type and Id columns are still required.
  • run_case now returns (case, solution) as opposed to (systems, solution). The case object contains the systems as well as case-level settings.

Migration guide

  • If you are using the run_case function, update your code to handle the new return signature of (case, solution) instead of (systems, solution).

For example, if you previously had:

(system, solution) = run_case(@__DIR__; 
    optimizer=HiGHS.Optimizer,
    optimizer_attributes=("solver" => "ipm", "run_crossover" => "off", "ipm_optimality_tolerance" => 1e-3)
);

You should now use:

(case, solution) = run_case(@__DIR__;
    optimizer=HiGHS.Optimizer,
    optimizer_attributes=("solver" => "ipm", "run_crossover" => "off", "ipm_optimality_tolerance" => 1e-3)
);

If you need to access the systems, you can retrieve them from the case object.

systems = case.systems

[0.1.0] - 2026-04-14

Added

  • Expanded result writing and postprocessing for non-served demand, storage level, curtailment, time weights, discounted and undiscounted cost outputs, and detailed cost breakdowns.
  • Added full time-series reconstruction across Monolithic, Myopic, and Benders workflows through WriteFullTimeseries.
  • Added SyntheticAmmonia, SyntheticMethanol, ThermalAmmonia, ThermalAmmoniaCCS, ThermalMethanol, ThermalMethanolCCS, and OneWayTransmissionLink assets.
  • Added StorageChargeLimitConstraint, long-duration storage feasibility constraints for Benders, and additional storage safety checks.
  • Added Myopic restart support, StopAfterPeriod, optional JuMP direct-model generation, optional string names, updated default HiGHS settings, and economic utilities for present-value and cash-flow calculations.

Changed

  • Redesigned node supply inputs around named supply dictionaries with per-segment price, min, and max values.
  • Split edge types into explicit unidirectional and bidirectional forms.
  • Changed TransmissionLink to model bidirectional transfer; use OneWayTransmissionLink for one-way transfer.
  • Cleaned up user extension loading through the user_additions/ layout.
  • Renamed emissions-tracking assets to UpstreamEmissions and DownstreamEmissions, with compatibility aliases for older names.
  • Expanded documentation and tests for TimeData, timeseries outputs, retrofitting, run workflows, outputs, constraints, assets, transmission links, supply parsing, and user additions.

Removed

  • Removed legacy unified output code in favor of the expanded write_* output suite.

Fixed

  • Improved Benders output parity and cost handling by performing a final operational solve for the selected planning solution.
  • Fixed and improved transmission, storage, dual, cost, and documentation behavior across the release.

Migration guide

  • Update node supply inputs to the named supply dictionary format. Each supply segment should define price, min, and max values. Legacy price_supply and max_supply inputs are still handled, and update_node_supply_inputs(...) can help convert existing cases.
  • Review any cases using automatically generated supply segment names. Segment names now use segment1, segment2, and so on.
  • Review transmission assets. TransmissionLink is now bidirectional by default; use OneWayTransmissionLink when directionality matters.
  • Update any direct use of edge types to the explicit unidirectional and bidirectional edge forms.
  • Update output-processing scripts that relied on the legacy unified output code. Use the expanded write_* output functions instead.
  • Review models that assumed nodes did not include balance constraints by default. Nodes now have BalanceConstraint enabled by default.
  • Prefer the renamed emissions assets UpstreamEmissions and DownstreamEmissions. Compatibility aliases remain for older names, including FossilFuelsUpstream and FuelsEndUse.

[0.0.3] - 2025-11-21

Added

  • Added iron and steel sector assets and documentation.
  • Added heat and steam sector commodities, assets, examples, and documentation.
  • Added aluminum sector default real-world parameters.
  • Added output support for dual values from BalanceConstraint and CO2CapConstraint.
  • Added minimum retired capacity tracking and extended retrofit features to multi-stage models.
  • Added Windows coverage to CI.

Changed

  • Updated installation instructions, citation metadata, asset library docs, modeler debugging docs, and timeseries documentation.

Fixed

  • Fixed several Windows-related path and user-additions issues.
  • Fixed retrofit integer decisions, hydropower reservoir efficiency handling, documentation cross references, and Benders dual scaling behavior.

[0.0.2] - 2025-09-25

Added

  • Added logging options.
  • Added settings output in results.
  • Added automatic Mermaid diagrams for assets.
  • Added asset retrofits for single-stage cases.
  • Added options to free model memory and write myopic outputs during iterations.

Changed

  • Refactored output-writing utilities.

Fixed

  • Fixed subcommodity loading.

[0.0.1] - 2025-08-20

Added

  • Initial registered release of MacroEnergy.jl.

[Unreleased]: https://github.com/macroenergy/MacroEnergy.jl/compare/v0.2.0...HEAD [0.2.0]: https://github.com/macroenergy/MacroEnergy.jl/compare/v0.1.0...v0.2.0 [0.1.0]: https://github.com/macroenergy/MacroEnergy.jl/compare/v0.0.3...v0.1.0 [0.0.3]: https://github.com/macroenergy/MacroEnergy.jl/compare/v0.0.2...v0.0.3 [0.0.2]: https://github.com/macroenergy/MacroEnergy.jl/compare/v0.0.1...v0.0.2 [0.0.1]: https://github.com/macroenergy/MacroEnergy.jl/releases/tag/v0.0.1