# 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.
