Macro

Welcome to the Macro documentation!

This documentation is a work-in-progress, so please forgive our appearance as we add material.

All feedback is welcome and please report and errors or omissions through the MacroEnergy.jl issues page.

What is Macro?

Macro is a bottom-up, multi-sectoral infrastructure optimization model for macro-energy systems. It co-optimizes the design and operation of user-defined models of multi-sector energy systems and networks. Macro allows users to explore the impact of energy policies, technology costs and performance, demand patterns, and other factors on an energy system as a whole and as separate sectors.

The main features of Macro include:

Graph-based representation of the energy system, facilitating clear representation and analysis of energy and mass flows between sectors.
"Plug and play" flexibility for integrating new technologies and sectors, including electricity, hydrogen, heat, and transport.
High spatial and temporal resolution to accurately capture sector dynamics.
Designed for distributed computing to enable large-scale optimizations.
Tailored Benders decomposition framework for optimization.
Open-source built using Julia and JuMP.

Structure of the documentation

The documentation contains five main sections:

Getting Started: How to install Macro and run your first cases
Tutorials: Long-form guides with worked examples, intended to help you learn how to use Macro
Guides: Short guides which walk you through how to achieve specific tasks, intended to be a day-to-day reference when working with Macro
Manual: A detailed description of Macro's components and features
Reference: A function reference for Macro's API

Recent changes

<!– BEGIN GENERATED RECENT CHANGES –>

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

For the full release history, see the changelog. <!– END GENERATED RECENT CHANGES –>

Macro development strategy

Macro is a very flexible tool for modelling energy systems. However, that flexibility also means the core architecture and functions are complex and difficult to use correctly.

To make Macro as useful and accessible to the widest audience possible we designed and developed it with three layers of abstractions in mind, each serving a different user profile:

Macro architecture

Due to these abstractions, users and modelers will be able to achieve their goals without needing to understand every aspect of Macro. The guides section of the documentation has guides for users, modelers, and developers.