Metadata-Version: 2.4
Name: macroenergy
Version: 0.1.0
Summary: Python wrapper for `MacroEnergy.jl`, a Julia multi-sector capacity expansion modelling framework
Project-URL: Documentation, https://macroenergy.github.io/MacroEnergy.jl/stable/
Project-URL: Repository, https://github.com/macroenergy/MacroEnergy.py
Project-URL: Issues, https://github.com/macroenergy/MacroEnergy.py/issues
Author: Ruaridh Macdonald
License: MIT License
        
        Copyright (c) 2026 Ruaridh Macdonald
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.12
Requires-Dist: juliacall>=0.9.31
Description-Content-Type: text/markdown

# macroenergy

Python wrapper for `MacroEnergy.jl`.

## Installation

From PyPI:

```bash
pip install macroenergy
```

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

```bash
uv run macroenergy-setup
```

If not using `uv`, run:

```bash
macroenergy-setup
```

### Import paths after install

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

```python
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:

```python
from macroenergy import setup_macroenergy_jl

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

CLI:

```bash
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:

```python
from macroenergy import download_example, list_examples

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

CLI examples:

```bash
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:

```python
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:

```bash
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:

```bash
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.
