Writing Results to Files

Currently, Macro supports the following types of outputs:

• Capacity Results: final capacity, new capacity and retired capacity for each technology.
• Costs: fixed, variable and total system costs.
• Flow Results: flow for each commodity through each edge in the system.
• Combined Results: all results (capacity, costs, flows, non-served demand, storage level) in a single file.

For detailed information about output formats and layouts, please refer to the Output Format and Output Files Layout sections below.

Capacity Results

To export system-level capacity results to a file, users can use the write_capacity function:

write_capacity("capacity.csv", system)

This function exports capacity results for all commodities and asset types defined in your case inputs.

You can filter the results by commodity, asset type, or both using the commodity and asset_type parameters:

# Filter results by commodity
write_capacity("capacity.csv", system, commodity="Electricity")
# Filter results by asset type
write_capacity("capacity.csv", system, asset_type="ThermalPower")
# Filter results by commodity and asset type
write_capacity("capacity.csv", system, commodity="Electricity", asset_type=["VRE", "Battery"])

The * wildcard character enables pattern matching for asset types. For example, the following command exports results for all asset types beginning with ThermalPower (e.g., ThermalPower, ThermalPowerCCS):

# Filter using wildcard matching for asset types
write_capacity("capacity.csv", system, commodity="Electricity", asset_type="ThermalPower*")

Similarly, you can use wildcard matching for commodities:

# Filter using wildcard matching for commodities
write_capacity("capacity.csv", system, commodity="CO2*")

Costs

Export system-wide cost results using the write_costs function:

write_costs("costs.csv", system, model)

Note that the write_costs function requires both the system and model arguments, unlike the write_capacity function.

Flow Results

Export system-level flow results using the write_flow function:

write_flow("flows.csv", system)

Filter results by commodity, asset type, or both using the commodity and asset_type parameters:

# Filter by commodity
write_flow("flows.csv", system, commodity="Electricity")

# Filter by asset type using parameter-free matching
write_flow("flows.csv", system, asset_type="ThermalPower")

# Filter by asset type using wildcard matching
write_flow("flows.csv", system, asset_type="ThermalPower*")

Combined Results

Export all results at once using the write_results function:

write_results(file_path, system, model, settings, ext=".csv.gz") # Creates multiple .csv.gz files
write_results(file_path, system, model, settings, ext=".parquet") # Creates multiple .parquet files

Writing Case Settings

To export case and system settings to a JSON file, use the write_settings function:

write_settings(case, "output/settings.json")

This function automatically writes:

• Case-level settings
• System-level settings for all systems in the case

The settings file is useful for:

• Documentation and reproducibility
• Sharing configuration with other users
• Debugging and troubleshooting

Output Format

Macro supports multiple output formats to suit different needs:

• CSV: Comma-separated values
  • Ideal for small datasets and human-readable output
  • Directly compatible with spreadsheet software
  • Less efficient for large datasets
• CSV.GZ: Compressed CSV
  • Balances readability and file size
  • Reduces storage requirements while maintaining CSV format
  • Requires decompression for reading
• Parquet: Column-based data store
  • Optimal for large datasets
  • Superior compression and faster read/write operations
  • Requires specialized tools for reading

The output format is determined by the file extension. For example, to export results in Parquet format:

write_results("results.parquet", system, model, settings)

Output Files Layout

By default, all results are written in long format for optimal storage efficiency and performance, particularly for large systems. The wide format is also available for easier reading and visualization.

Configure the output layout using the OutputLayout setting in your Macro settings JSON file:

{
  "OutputLayout": "wide"
}

or

{
  "OutputLayout": {
    "Capacity": "wide",
    "Costs": "long",
    "Flow": "long"
  }
}

Available options:

• "OutputLayout": "long" (applies to all outputs)
• "OutputLayout": "wide" (applies to all outputs)
• "OutputLayout": {"Capacity": "wide", "Costs": "long", "Flow": "long"} (individual layout settings)

Output Files Location

Macro provides two settings to control output file locations:

• OutputDir: Specifies the output directory name
• OverwriteResults: Controls whether to overwrite existing files

For example:

{
  "OutputDir": "results",
  "OverwriteResults": true
}

Users can obtain the output directory path programmatically using the create_output_path function:

output_path = create_output_path(system)

and then pass this path to the write functions:

write_capacity(joinpath(output_path, "capacity.csv"), system)

By default, the create_output_path function creates a results directory in the same location as your input data (i.e., the directory containing system_data.json). For more information about the input folder structure, refer to the Creating a new System guide.

If OverwriteResults is true, existing files will be overwritten. Otherwise, the function appends a number to the directory name to prevent overwriting.

Users can specify a custom base path for the output directory:

output_path = create_output_path(system, "path/to/output")
write_capacity(joinpath(output_path, "capacity.csv"), system) # Creates /path/to/output/results/capacity.csv

In this case, the function creates a directory named according to the OutputDir setting (e.g., results) within your specified path (e.g., path/to/output/results).