Metadata-Version: 2.4
Name: odys
Version: 0.3.0
Summary: Stochastic optimization of energy asset portfolios across electricity markets.
Keywords: battery,dispatch,energy,milp,optimization,portfolio,stochastic,uncertainty
Author: Ramiro Criach
Author-email: Ramiro Criach <ramirocriach@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: highspy>=1.14.0
Requires-Dist: linopy>=0.10
Requires-Dist: numpy>=2.4.1
Requires-Dist: pandas>=2.3.3
Requires-Dist: pydantic>=2.12.5
Requires-Dist: xarray>=2025.12.0
Requires-Dist: cplex>=22.1.2.1 ; extra == 'cplex'
Requires-Dist: gurobipy>=13.0.1 ; extra == 'gurobi'
Requires-Dist: pyscipopt>=6.1.0 ; extra == 'scip'
Requires-Python: >=3.11, <4.0
Project-URL: Changelog, https://github.com/ramirocrc/odys/blob/main/CHANGELOG.md
Project-URL: Documentation, https://ramirocrc.github.io/odys/
Project-URL: Homepage, https://ramirocrc.github.io/odys/
Project-URL: Issues, https://github.com/ramirocrc/odys/issues
Project-URL: Repository, https://github.com/ramirocrc/odys
Provides-Extra: cplex
Provides-Extra: gurobi
Provides-Extra: scip
Description-Content-Type: text/markdown

<h1>
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ramirocrc/odys/main/docs/assets/brand/odys-wordmark-on-dark.svg">
    <img alt="Odys" src="https://raw.githubusercontent.com/ramirocrc/odys/main/docs/assets/brand/odys-wordmark-on-light.svg" height="56">
  </picture>
</h1>

[![CI](https://img.shields.io/github/actions/workflow/status/ramirocrc/odys/main.yml?branch=main)](https://github.com/ramirocrc/odys/actions/workflows/main.yml?query=branch%3Amain)
[![Coverage](https://codecov.io/gh/ramirocrc/odys/branch/main/graph/badge.svg)](https://codecov.io/gh/ramirocrc/odys)
[![Python versions](https://img.shields.io/pypi/pyversions/odys?color=green)](https://pypi.org/project/odys/)
[![PyPI](https://img.shields.io/pypi/v/odys)](https://pypi.org/project/odys/)
[![License](https://img.shields.io/github/license/ramirocrc/odys)](https://github.com/ramirocrc/odys/blob/main/LICENSE)

Optimize energy portfolios under uncertainty.

**[Documentation](https://ramirocrc.github.io/odys/)** · **[User Guide](https://ramirocrc.github.io/odys/user_guide/model/first_model/)** · **[Examples](https://ramirocrc.github.io/odys/examples/)** · **[Formulation](https://ramirocrc.github.io/odys/formulation/)**

Odys is a free, open-source Python framework for the short-term operation of energy asset portfolios across electricity markets. Generators, storage, electric vehicles, chargers and loads are scheduled against one or more markets, with uncertainty represented by probability-weighted scenarios.

Features:
- **Stochastic optimization**: maximize expected profit over a set of scenarios, with optional stage-fixed (non-anticipative) market positions and a CVaR risk term.
- **Solver choice**: HiGHS by default; Gurobi, CPLEX and SCIP as optional extras. Models are built with [linopy](https://github.com/PyPSA/linopy).
- **Validated inputs**: assets, profiles and scenarios are Pydantic models, checked before the model is built.
- **Results as pandas**: dispatch comes back as Series and DataFrames.
- **Documented formulation**: every variable, constraint and objective term is [written out](https://ramirocrc.github.io/odys/formulation/).
- **Typed and tested**: fully typed public API, tested on Python 3.11 to 3.14.

Scope: Odys models a portfolio on a single bus over a short horizon. It does not model networks, power flow or capacity expansion; for those, see [PyPSA](https://pypsa.org/) or [Calliope](https://calliope.readthedocs.io/).

## Installation

```console
pip install odys
```

Requires Python 3.11+. HiGHS is included. Gurobi, CPLEX and SCIP are optional extras:

```console
pip install "odys[gurobi]"
```

See the [solver docs](https://ramirocrc.github.io/odys/user_guide/solving/solvers/) for choosing a solver and passing options.

## Quick example

Define your assets, describe the scenario, and call `.optimize()`:

```python
from datetime import timedelta

from odys import AssetPortfolio, EnergySystem, FixedLoad, Generator, LoadProfile, Scenario

generator = Generator(name="gen", nominal_power=100.0, variable_cost=50.0)
load = FixedLoad(name="demand")

portfolio = AssetPortfolio([generator, load])

energy_system = EnergySystem(
    portfolio=portfolio,
    scenarios=Scenario(profiles=(LoadProfile(load=load, values=[60, 90, 40, 70]),)),
    timestep=timedelta(hours=1),
    number_of_steps=4,
)

result = energy_system.optimize()
print(result.generators.power)
```

```
time  generator
0     gen          60.0
1     gen          90.0
2     gen          40.0
3     gen          70.0
Name: power, dtype: float64
```

See the [documentation](https://ramirocrc.github.io/odys/) for the full workflow, or check the [examples](https://ramirocrc.github.io/odys/examples/) for complete worked scenarios.

## Contributing

See [CONTRIBUTING.md](https://github.com/ramirocrc/odys/blob/main/CONTRIBUTING.md) for development setup and guidelines.

## License

[MIT](https://github.com/ramirocrc/odys/blob/main/LICENSE)
