Skip to main content

cobre-bridge

cobre-bridge converts hydrothermal dispatch cases written for the Brazilian planning models NEWAVE (long term) and DECOMP (short term) into the input format of Cobre, an open-source SDDP solver, and compares the two models' results once both have been run.

It is a command-line tool. A session typically goes:

  1. check that a source case is complete enough to convert;
  2. convert it into a Cobre case directory;
  3. solve that directory with the cobre solver;
  4. compare the source model's published results against Cobre's simulation;
  5. open an interactive dashboard of the Cobre run.

Installation

uv tool install cobre-bridge    # isolated, on-PATH CLI (recommended)
pipx install cobre-bridge       # alternative
pip install cobre-bridge        # into the current environment

Requires Python 3.12 or newer. The install pulls in cobre-python, Cobre's Python bindings, so convert --validate, compare, and the DECOMP boundary cost-to-go import work without further setup. cobre-python ships prebuilt wheels for common platforms; if pip reports that none matches yours, see the cobre repository for build options.

The cobre solver itself is a separate install (cargo install cobre-cli; see the cobre README). cobre-bridge does not need it to convert or compare. You need it to solve the converted case between those two steps.

Versions

A cobre-bridge release X.Y.Z targets cobre X.Y.Z: the converted case follows that cobre release's input contract, and the cobre-python dependency floor is the oldest cobre the output loads on. A packaging test keeps the two in lockstep. convert --validate skips its validation step, with a note, when the installed cobre-python is older than that floor. A DECOMP boundary imported by convert decomp is stricter: cobre loads it only in the exact version of the cobre-python that wrote it (see the DECOMP track page).

Quick start

# 1. Preflight the source case. Exit 0 = ready, 1 = ready with warnings, 2 = will not convert.
cobre-bridge check newave /path/to/newave_case

# 2. Convert into a new Cobre case directory (--force overwrites a non-empty one).
cobre-bridge convert newave /path/to/newave_case ./my_case

# 3. Solve with cobre. By default the solver writes its results to ./my_case/output/.
cobre run ./my_case

# 4. Compare NEWAVE's published results with Cobre's simulation. Always exits 0.
cobre-bridge compare newave /path/to/newave_case ./my_case/output --format html

# 5. Browse the Cobre run.
cobre-bridge dashboard ./my_case --open

Replace newave with decomp for a DECOMP deck; the flow is the same. The DECOMP track imports the deck's boundary cost-to-go function by default, which adds one rule for running the case; see the DECOMP track page.

Commands

Command What it does
convert newave SRC DST Convert a NEWAVE case directory into a Cobre case directory.
convert decomp SRC DST Convert a DECOMP deck revision into a Cobre case directory.
check newave SRC / check decomp SRC Validate the source inputs without writing anything; report missing inputs and what the conversion would leave out.
compare newave NEWAVE_DIR COBRE_OUTPUT_DIR Compare NEWAVE's published results (MEDIAS-*.CSV, pmo.dat) against a Cobre simulation output directory.
compare decomp DECOMP_DIR COBRE_OUTPUT_DIR Compare a DECOMP run's operation tables (dec_oper_*.csv) against a Cobre simulation output directory.
dashboard CASE_DIR Build an interactive HTML dashboard from a solved Cobre case (reads CASE_DIR/output/).

Every command accepts --json, -v/-vv, --log-file PATH, --no-color, and --quiet. convert adds --validate, --force, --dry-run, and --diagnostics-json PATH; convert decomp also has --no-fcf. compare adds --tolerance, --format, and --out-dir. dashboard adds --output and --open. The generated reference with every option's help text is docs/cli.md. Shell completion: cobre-bridge --install-completion.

What convert writes

DST becomes a Cobre case directory: config.json, stages.json, penalties.json, and initial_conditions.json at the top, entity registries under system/, inflow and load data under scenarios/, and bounds and generic constraints under constraints/. Stage-varying tables are Parquet; everything else is JSON. The layout is Cobre's documented input format (see the cobre documentation).

Next to the case, conversion_manifest.json records provenance: the bridge version and git commit, the source directory, a hash of every input file read, the entity counts, and every diagnostic raised during the run.

Diagnostics (a missing optional file, a bound clamped to keep the LP feasible, a feature the converter leaves out) are rendered as grouped panels on stderr with the affected plants and stages. --diagnostics-json saves them to a file; --dry-run runs the whole conversion in memory and lists what would be written.

What compare writes

compare prints a per-variable summary table and writes artifacts to COBRE_OUTPUT_DIR/comparison_artifacts/ (or --out-dir). --format chooses the set: parquet and json (the tidy comparison dataset) by default, csv, html for a multi-tab report.html covering costs, system and energy balance, network, convergence, performance, and per-plant detail, or all. compare is informational and always exits 0; the report is where you judge the differences.

Machine-readable output

With --json, a command prints exactly one JSON document to stdout, {schema_version, command, status, summary, diagnostics}, and nothing else on stdout, including when it fails. Human-readable rendering is suppressed.

Command Exit codes
check 0 ready, 1 ready with warnings, 2 will not convert
convert 0 converted, 1 conversion error, 2 --validate reported a load failure
compare always 0
dashboard 0 written, 1 error

An error status and a non-zero exit code always travel together.

Configuration

Defaults for the compare options can live in a cobre-bridge.toml:

[compare]
format = ["console", "html"]   # or one string; same tokens as --format
out_dir = "comparisons"

[compare.results]
tolerance = 0.01               # relative

The file is looked up in the working directory and its parents, then $XDG_CONFIG_HOME/cobre-bridge/config.toml, then ~/.config/cobre-bridge/config.toml; the first one found is used. The same settings exist as environment variables (COBRE_BRIDGE_RESULTS_TOLERANCE, COBRE_BRIDGE_FORMAT, COBRE_BRIDGE_OUT_DIR). Precedence is flag > environment > file > built-in default.

Documentation

License

Apache-2.0

Metadata

Release files for cobre-bridge 0.17.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cobre-bridge 0.17.0
File Size Uploaded Provenance Actions
cobre_bridge-0.17.0.tar.gz 2.4 MB With provenance Details for cobre_bridge-0.17.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cobre-bridge 0.17.0
File Interpreter ABI Platform Actions
cobre_bridge-0.17.0-py3-none-any.whl Python 3 none any Details for cobre_bridge-0.17.0-py3-none-any.whl

Total release size: 3.3 MB

Release files / cobre_bridge-0.17.0.tar.gz

Download URL cobre_bridge-0.17.0.tar.gz
Size 2.4 MB
Tags Source
SHA-256 checksum
How to use checksums
e3bee5f1f891eb7b1ce91897f7bc0e692b413bfcb7a26d454647e18b4c2eef47
BLAKE2b-256 checksum
How to use checksums
8c214cc828f98259c6711fbcf1437640901f3a46095388bb8e2d9f0e09b85758
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.

Transparency log

Release files / cobre_bridge-0.17.0-py3-none-any.whl

Download URL cobre_bridge-0.17.0-py3-none-any.whl
Size 859.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fc8b76d8e9f79c3ae4dab976c0fa7aeac8f1c9dcdda570515b325529498ae421
BLAKE2b-256 checksum
How to use checksums
e3d5afd7a515290400abf421723e22f9ea84f41c586fa755799a16081ce83d9e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.

Transparency log

Security for cobre-bridge 0.17.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cobre_bridge-0.17.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page