Optimize energy portfolios under uncertainty.

Documentation · User Guide · Examples · 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.
• 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.
• 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 or Calliope.

Installation

pip install odys

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

pip install "odys[gurobi]"

See the solver docs for choosing a solver and passing options.

Quick example

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

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 for the full workflow, or check the examples for complete worked scenarios.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT