<!– 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.
Added capacity_summary.csv for multi-period cases, combining per-period capacity outputs into a single long- or wide-format file.
Added optional StartYear input in case_settings.json to label periods by calendar year.
Added capex.csv output file to report per-component asset capital costs.
Added repository-local benchmarking tools to compare case loading, case generation, and model generation between upstream/main and the current worktree using reproducible example inputs.
Added ConstrainedFossilLiquidFuels, a refinery asset with fixed jet-fuel and diesel output ratios and configurable fuel-specific emissions.
Added optional auxiliary-fuel inputs to BECCSHydrogen and captured-CO₂ return flows to SyntheticLiquidFuels.
Added unit-commitment support for Electrolyzer hydrogen output, including startup electricity consumption, minimum up/down times, and ramping limits.

Changed

Cached repeated reads of shared CSV inputs within each case or system load, avoiding repeated full-file parsing when assets select different columns from the same file.
@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.
Updated MacroEnergyScaling.jl compatibility to 0.4. Constraint scaling now updates constraints in place, so existing JuMP ConstraintRefs remain valid instead of being invalidated by constraint replacement. This version also allows for objective scaling in the future.
Hoisted repeated time-data lookups during model construction and simplified ramping and minimum up/down-time constraints to avoid temporary expression and index containers.
Weight policy slack to ensure CO2 slack penalty has economic interpretation.

Fixed

Myopic runs with MyopicSettings.ReturnModels = false now actually free each period's model. Each period's references are now released once its results have been written, and the model is emptied. Results are unchanged; scalar capacities remain readable on the returned Case as Float64.
Fix wacc default preventing fallback to DiscountRate. Omitted wacc was silently treated as 0.0 instead of falling back to the case-level DiscountRate.
Duplicate asset IDs within a system are now rejected during system generation, preventing ambiguous myopic capacity carry-over and late wide-output failures.
Fixed asset component traversal and Benders planning updates for assets whose optional edges are absent.

Documentation

Switched documentation math rendering to MathJax3 and pinned Mermaid to 11.16.1 to avoid Mermaid 11.17's RequireJS compatibility regression.
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.

[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