Outputs

Contents

Overview | Directory Structure | Settings | Output Files | MacroEnergy API | See Also

Overview

After solving a Macro model, results are automatically written to disk by write_outputs. The output files are CSV-format tabular data that describe the optimal capacity decisions, operational dispatch, and costs of every asset in the system.

Outputs are organized into one results directory per modeled period. Within each directory, each output type is stored in its own file. The files use a consistent long format by default (one row per observation, with metadata columns identifying the asset and time step), which makes them easy to filter and join using standard data tools. A wide format is also available via the OutputLayout setting, which allows pivoting of time steps or variables into columns for easier human readability.

All write functions are called automatically when you run run_case (or solve_case when using Myopic as solution algorithm). You can also call each function individually to re-export a specific output after modifying a solved system.

Output Directory Structure

Single-Period Models

For a single-period model, results are written inside a two-level directory structure. An outer directory is created from the OutputDir setting (default results with a numeric suffix), and an inner results/ directory is created inside it for the actual output files:

my_case/
├── case_settings.json
├── settings/
│   └── macro_settings.json
├── system/
│   └── ...
├── results_001/              ← outer directory (non-overwrite default)
│   ├── settings.json         ← case-level settings snapshot
|   ├── my_case.log           ← copied here after the run
│   └── results/              ← all output files written here
│       ├── capacity.csv
│       ├── costs.csv
│       ├── flows.csv
│       └── ...

When OverwriteResults = true, the outer directory name is exactly OutputDir (default results) with no suffix:

my_case/
├── results/                  ← outer directory (overwrite mode)
│   ├── settings.json
│   ├── my_case.log
│   └── results/              ← output files
│       ├── capacity.csv
│       └── ...

Multi-Period Models

For multi-period (planning) models, the same outer directory is created, and each planning period gets its own results_period_N/ subdirectory inside it:

my_case/
├── case_settings.json
├── my_case.log               ← written here during the run
└── results_001/                  ← outer directory
    ├── settings.json             ← case-level settings snapshot
    ├── my_case.log               ← copied here after the run
    ├── results_period_1/         ← period 1 outputs
    │   ├── capacity.csv
    │   └── ...
    └── results_period_2/         ← period 2 outputs
        ├── capacity.csv
        └── ...

Overwrite Behavior

By default (OverwriteResults = false), Macro will not overwrite an existing outer results directory. Instead, it appends an incremental numeric suffix: results_001, results_002, etc. This is controlled by the OverwriteResults and OutputDir settings in macro_settings.json.

Output Settings

The following settings in macro_settings.json control the behavior of the output files.

Layout and Format

Per-File Layout Control

Instead of a single string, OutputLayout can be a JSON object to control layout independently for each output type:

"OutputLayout": {
    "Capacity":        "wide",
    "Costs":           "long",
    "Flow":            "long",
    "StorageLevel":    "long",
    "Curtailment":     "long",
    "NonServedDemand": "long"
}

Supported keys: Capacity, Costs, Flow, StorageLevel, Curtailment, NonServedDemand.

Full Time Series Setting

Output Files

The table below lists all output files produced by Macro. Click the file name to go to the detailed page for that output.

MacroEnergy API

Writing Outputs

The following functions write output files. They are called automatically by run_case/solve_case but can also be invoked individually.

Extracting Results as DataFrames

The following functions return output data as Julia DataFrame objects without writing to disk. They are useful for post-processing within a Julia session.

Filtering Results

write_capacity and write_flow (and their corresponding get_optimal_* functions) accept optional filters:

• commodity: filter to one or more commodity types (e.g., commodity="Electricity")
• asset_type: filter to one or more asset types (e.g., asset_type="ThermalPower")

Two pattern-matching modes are supported:

1. Parameter-free matching — "ThermalPower" matches ThermalPower{NaturalGas}, ThermalPower{Uranium}, etc.
2. Wildcard matching — "ThermalPower*" additionally matches ThermalPowerCCS{NaturalGas}, etc.

# Write only electricity flows for thermal power plants
write_flow("flows_elec_thermal.csv", system, commodity="Electricity", asset_type="ThermalPower")

See Also

• Time Data — explanation of representative periods, subperiod weights, and TDR
• Financial Assumptions — how investment costs are annualized
• Multi-Period Accounting — discounting and cost accounting across periods
• Writing Results (User Guide) — step-by-step guide to customizing output
• Writing Output Data (Reference) — full API reference for all write functions