Metadata-Version: 2.4
Name: novomodelo-python
Version: 0.18.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering
Summary: High-performance SDDP solver for hydrothermal dispatch — Python bindings for the Novomodelo ecosystem
Keywords: sddp,optimization,power-systems,energy,hydrothermal
Home-Page: https://docs.novomodelo.invalid/
Author: Operador Nacional do Sistema Elétrico - ONS, Câmara de Comercialização de Energia Elétrica - CCEE, Empresa de Pesquisa Energética - EPE
License-Expression: Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/ons-ccee-epe/novomodelo/issues
Project-URL: Documentation, https://docs.novomodelo.invalid/
Project-URL: Homepage, https://docs.novomodelo.invalid/
Project-URL: Repository, https://github.com/ons-ccee-epe/novomodelo

# novomodelo

Python bindings for the [Novomodelo](https://github.com/ons-ccee-epe/novomodelo) power systems solver.

Novomodelo is a high-performance SDDP (Stochastic Dual Dynamic Programming) solver for hydrothermal dispatch, written in Rust. This package provides Python access to case loading, validation, training, simulation, and result inspection.

## Installation

Nothing is published to PyPI under this name. From the root of a clone made
with `git clone --recurse-submodules` (the solvers are vendored as submodules),
build and install the package with a Rust toolchain (1.88+) and Python 3.12+:

```bash
pip install ./crates/novomodelo-python
```

A project can also depend on a tagged release through a git URL, for example
`novomodelo-python @ git+https://github.com/ons-ccee-epe/novomodelo@v0.18.0#subdirectory=crates/novomodelo-python`.

The wheel workflow (`.github/workflows/release-python.yml`) builds for the
platforms below; its wheels are not published to PyPI:

- Linux x86_64 (manylinux_2_34)
- Linux aarch64 (manylinux_2_28)
- Linux musl x86_64 (musllinux_1_2)
- macOS Apple Silicon (aarch64) and Intel (x86_64)
- Windows x86_64
- Python 3.12+

## Quick Start

```python
import novomodelo

# Load and validate a case
system = novomodelo.io.load_case("path/to/case")
print(
    f"System: {system.n_buses} buses, {system.n_hydros} hydros, {system.n_thermals} thermals"
)

# Run training + simulation
result = novomodelo.run.run("path/to/case", output_dir="output/")
print(f"Converged: {result['converged']}, LB: {result['lower_bound']:.2f}")

convergence = novomodelo.results.load_convergence("output/")
print(f"Iterations: {len(convergence)}")

simulation = novomodelo.results.load_simulation("output/")
print(f"Cost records: {len(simulation['costs'])}")

policy = novomodelo.results.load_policy("output/")
print(f"Iterations completed: {policy['metadata']['producer']['completed_iterations']}")
```

The same workflow, driven step by step:

```python
# The Study lifecycle — construct, train, simulate
study = novomodelo.Study("path/to/case", output_dir="output/")
policy = study.train()
summary = study.simulate(policy)
print(f"Scenarios: {summary['n_scenarios']}, Completed: {summary['completed']}")

# Inspect the study before running any phase
print(f"Stages: {study.stochastic['n_stages']}, Seed: {study.stochastic['seed']}")
```

## Modules

- **`novomodelo.io`** — Load and validate case directories
- **`novomodelo.model`** — Data model classes (System, Bus, Line, Thermal, Hydro, etc.)
- **`novomodelo.run`** — Execute SDDP training and simulation
- **`novomodelo.results`** — Load and inspect output artifacts, including convergence
  history, Parquet simulation outputs, and FlatBuffers policy (FCF) checkpoints
- **`novomodelo.schema`** — JSON Schema export for case-directory input types
- **`novomodelo.errors`** — Typed exception hierarchy for case-loading and solver errors

The package also exports `Study`, `Policy`, `write_policy_checkpoint`, and `version_info` at the top level.

## Requirements

- Python >= 3.12
- No runtime dependencies (the Rust solver is statically linked)

## License

Apache-2.0 — see [LICENSE](https://github.com/ons-ccee-epe/novomodelo/blob/main/LICENSE).

## Links

- [Repository](https://github.com/ons-ccee-epe/novomodelo)
- [Documentation](https://docs.novomodelo.invalid/)
- [Bug Tracker](https://github.com/ons-ccee-epe/novomodelo/issues)

