Python Quickstart

Install Cobre and run a study in a few steps.

Installation

pip install cobre-python

Requires Python 3.12, 3.13, or 3.14.

Run a Case

import cobre

result = cobre.run.run("path/to/case")

The cobre.run.run() function loads the case, trains an SDDP policy, optionally runs simulation, and writes output files. It returns a dictionary with the following keys:

Key	Type	Description
`converged`	`bool`	Whether training converged
`iterations`	`int`	Number of training iterations completed
`lower_bound`	`float`	Final lower bound
`upper_bound`	`float` or `None`	Final upper bound (None if no simulation)
`gap_percent`	`float` or `None`	Optimality gap percentage (None if unavailable)
`total_time_ms`	`int`	Total wall-clock time in milliseconds
`output_dir`	`str`	Path to the output directory
`simulation`	`dict` or `None`	Simulation summary (if enabled)
`stochastic`	`dict` or `None`	Stochastic preprocessing summary
`hydro_models`	`dict` or `None`	Hydro model summary
`provenance`	`dict`	Build version and environment metadata

print(f"Converged: {result['converged']}")
print(f"Iterations: {result['iterations']}")
print(f"Lower bound: {result['lower_bound']:.2f}")
if result['gap_percent'] is not None:
    print(f"Gap: {result['gap_percent']:.2f}%")
print(f"Output dir: {result['output_dir']}")

Optional Parameters

result = cobre.run.run(
    "path/to/case",
    output_dir="path/to/output",   # default: case_dir/output
    threads=4,                      # default: 1
    skip_simulation=True,           # default: False
)

Read Output with Polars

Cobre writes results as Parquet files, which can be loaded directly with Polars or any Arrow-compatible library:

import polars as pl

# Convergence trajectory
convergence = pl.read_parquet("output/training/convergence.parquet")
print(convergence.head())

# Simulation costs (if simulation was enabled) — Hive-partitioned
costs = pl.read_parquet("output/simulation/costs/")
print(costs.describe())

Arrow Zero-Copy Loading

For larger datasets, use the built-in Arrow loaders that avoid serialization overhead:

# Returns a pyarrow.Table (zero-copy)
convergence_table = cobre.results.load_convergence_arrow("output/")
simulation_tables = cobre.results.load_simulation_arrow("output/")

# Convert to Polars without copying
import polars as pl
df = pl.from_arrow(convergence_table)

Next Steps

See the case directory format for input file specifications.
Explore the examples for ready-to-run cases.
Read the Jupyter quickstart notebook for a complete end-to-end workflow with visualization.

Keyboard shortcuts