macroenergy 0.1.0

Python wrapper for `MacroEnergy.jl`, a Julia multi-sector capacity expansion modelling framework

macroenergy

Python wrapper for MacroEnergy.jl.

Installation

From PyPI:

pip install macroenergy

Then run setup once to install/compile the Julia package:

uv run macroenergy-setup

If not using uv, run:

macroenergy-setup

Import paths after install

After pip install macroenergy, prefer importing directly from the top-level namespace:

from macroenergy import run_case, setup_macroenergy_jl, list_examples

Internal implementation lives in setup, examples, and run_tools; macroenergy is the public flat API facade.

Package structure

Public API is exposed at macroenergy.* for convenience. Internal modules are organized as:

• setup
• examples
• run_tools

Julia package setup

Setup helper functions:

• install_macroenergy_jl(...)
• compile_macroenergy_jl(...)
• setup_macroenergy_jl(...)

Example:

from macroenergy import setup_macroenergy_jl

setup_macroenergy_jl(
    url="https://github.com/macroenergy/MacroEnergy.jl",
    rev="main",
)

CLI:

uv run macroenergy-setup
uv run macroenergy-setup --install-only
uv run macroenergy-setup --compile-only
uv run macroenergy-setup --url https://github.com/macroenergy/MacroEnergy.jl --rev main

MacroEnergy examples

Example helper functions (mapped to MacroEnergy.jl):

• authenticate_github(token)
• list_examples(auth=...)
• download_example(example_name, target_dir=".", auth=...)
• download_examples(target_dir=".", pause_seconds=1.0, auth=...)
• example_readme(example_name, auth=...)
• example_contents(example_name, auth=...)

Example:

from macroenergy import download_example, list_examples

examples = list_examples()
download_example(examples[0], target_dir=".")

CLI examples:

uv run macroenergy-examples list
uv run macroenergy-examples download MyExample --target-dir .
uv run macroenergy-examples readme MyExample
uv run macroenergy-examples contents MyExample
uv run macroenergy-examples download-all --target-dir . --pause-seconds 1.0

Testing

• Unit tests: uv run pytest
• Integration tests (includes explicit setup test first): uv run pytest -m integration

Integration tests are marked with @pytest.mark.integration and are excluded by default via pytest config.

Running cases

Python wrapper:

from macroenergy import run_case

systems, solution = run_case("/path/to/case")

The wrapper is a passthrough to MacroEnergy.run_case, so supported keyword arguments follow the Julia function (for example lazy_load, log_to_console, log_to_file, log_file_path, log_level, optimizer-related keywords, etc.).

CLI:

uv run macroenergy-run-case /path/to/case
uv run macroenergy-run-case /path/to/case --no-lazy-load --no-log-to-console
uv run macroenergy-run-case /path/to/case --log-level Info

Optional setup + run in one command:

uv run macroenergy-run-case /path/to/case --setup-first --url https://github.com/macroenergy/MacroEnergy.jl --rev main

Compatibility note

juliacall may be unstable with some Python/runtime combinations (for example, occasional VS Code crashes during interpreter shutdown on newer Python versions). If you see native crashes, prefer a stable Python version such as 3.12/3.13 for development and CI, and keep Julia/juliacall versions pinned in your environment.