Changelog¶
All notable changes to TANGO are documented here.
From 1.1.0 on, version numbers follow Effort-based Versioning (EffVer): the number says how much work upgrading takes, and the Breaking section of each release says what to change.
In Development¶
Added¶
sim_config.time_stepping: give a run's steps as a fixed grid (scheme: fixed, astepin seconds and anum_steps) or as an explicit list of step end times (scheme: times, in seconds). The project lifetime is where the grid ends. A list of times can resolve fast early behavior, such as the first weeks of an AGS loop, with short steps and use long steps afterwards.num_tsteps/dt_yearsstill work, as a shorthand for one fixed grid, and give the same results as before. See Time stepping.- Subsystems on different time grids:
sim_config.time_steppingcan split the circuit into several subsystems, each a contiguous run of components with its own grid, for example a closed loop's wells on 6-month steps and the surface plant on 1-year steps. Streams between subsystems are passed on at the times every grid shares, by a per-edge sync rule (holdorperiod_average, set undersync:or left to the default). Each component records its own steps;SystemBCIterationconverges the injection enthalpy once per sync interval. A component with external simulator state (RAFT) takes one step per sync interval. See Time stepping.
Changed¶
- Run averages are time-weighted: net electric and thermal power, the node duties used for plant CAPEX, and downhole pump power each weight a step by its length, so LCOE and the opt apps' mean-power objectives are right on uneven steps. On an even grid the results are unchanged.
- Each component records the step behind every history entry in a new
time_history(t_startanddt, in seconds).
Breaking¶
- The per-step results CSV (
<stem>.smry.csv) has one row per step end time, with atime [s]column in place oftimestep [-]andyear [yr](which gave each step's start in years). Each component's values sit in the rows of its own step ends, so components on different grids, or with differentsave_intervals, line up by time. The phase-diagram slider is labeled the same way. - For code that calls components directly:
FlowComponent.solve(inlet)issolve(inlet, step), taking aTimeStep; components no longer have adt_yearsfield;SystemDirect/SystemBCIterationtake aTimeStepping(fromSimConfig.time_stepping_for()) in place ofn_tsteps/dt_years; andOrchestrator.run_timestep(t)isrun_interval(i), one sync interval.
Fixed¶
just slurmand the SLURM job scripts accept an environment with RAFT installed: afterjust setup-raft, the up-to-date check (uv sync --check --offline) counted the optionalraftgroup as extra packages and refused to submit with "The uv environment is out of date". The check now passes--inexact, so it still catches missing or outdated locked packages but ignores extra ones.
1.2.0 — 2026-11-09¶
Added¶
tango_core initcopies the RAFT example:templates/AGS_ORC_electric_raft.yml, with RAFT's config and mesh intemplates/raft/, now ship in the package. Add RAFT withuv add "geg-raft @ git+https://github.com/GEG-ETHZ/RAFT@v0.2.1"and run the example from your own project, no source checkout needed.
Changed¶
- The documentation site is public and shows the public pages only.
- TANGO has a DOI, 10.5281/zenodo.23952662: Zenodo archives every GitHub Release.
CITATION.cffand the README carry it.
1.1.0 — 2026-11-03¶
First public release: tango-core is open source under Apache-2.0, and
releases go to PyPI. It completes the example coverage matrix with an
optimized design for every example config, can simulate an AGS loop's
wells and rock with RAFT (from a source checkout), moves the stream interface from temperature to
specific enthalpy, adds interactive phase diagrams, and fixes several
physics and solver bugs those diagrams exposed. Run-time guards turn
physically impossible results into typed errors, component efficiencies
are realistic and cited, and third-party licenses are a release gate.
Breaking: the package and command are renamed tango_core, and
tango_core run needs --save-dir or --no-save. Results change
substantially for CO2 and closed-loop (AGS) configs; every example config
is regoldened.
The version is 1.1.0 rather than the 2.0.0 that EffVer gives a package rename: this is the first public release, and nobody outside GEG upgrades from 1.0.x.
Breaking¶
Configs, scripts, and workflows written for an earlier version need these changes:
auto-pressure,auto-flow, andauto-bothinjection modes are removed; a config that names one fails validation with a message saying so. Usemanual-fracking-checkand find the operating point with anapplications/opt_*/search.sim_config.max_mass_rateis rejected as an unknown key. Drop it; it only servedauto-flow.example_configs/is nowtemplates/, in the repository, in the wheel (tango_core/templates/), and in whattango_core initcopies.- The sweep apps are deleted (
run_*_sweep,sweep_demo_AGS_direct_heat), and the surrogate app moved toapplications/_on_hold/opt_hydro_df_electric_surrogate/. Use theopt_*apps, orWorkflowin a loop as its docstring shows. - Unknown surface-node keys raise
ConfigError. Fix the typo or remove the key. p0_out{N}is nowp0_megapascals_out{N}, in MPa. The old key was passed to TESPy as bar, so its values were 10x too low; rename the key and give the value in MPa.- A linked config value that disagrees raises
ConfigError. Values derived from another one (e.g.hydro_static_pressure,well_eff_diameter, the injection well's length, a numerical well'snum_cellswithcell_length) must match it; drop them from the config and let TANGO derive them. tango_core run --save-dirwrites<name>.results.ymlinstead of<name>.yml. Update anything that reads the old name.just slurm-fetchneeds app names or--all. A bare call fetches nothing.- The package is
tango_coreand the command istango_core. Replaceimport tangowithimport tango_coreandtango_cliwithtango_corein scripts and notebooks; there is no alias for the old names. tango_core runneeds--save-dir DIRor--no-save. A run with neither stops with an error instead of discarding its results.
Added¶
- Releases on PyPI.
pip install tango-coreoruv add tango-core. Pushing a version tag runs.github/workflows/release.yml, which uploads the release to TestPyPI and then, after a maintainer approves, the same files to PyPI, using Trusted Publishing (no stored token).CONTRIBUTING.mdhas the steps. grouped_subsurfacecomponent (type: grouped_subsurface): an AGS loop's injection, horizontal and production wells grouped into one circuit component, configured as three segment blocks (seetemplates/AGS_ORC_electric_grouped_subsurface.yml); a first, fixed-topology step toward grouped subsystems (GitHub #102). Variantnumericalmarches the threeNumericalWells in sequence and gives results identical to configuring them as separate components; it is the shape an external subsurface simulator plugs in behind. The linked lengths (production length, loop depth,layout.well_spacing) are derived the same way as for the three-component AGS configs. Both variants take the loop's mass flow and temperature at the injection wellhead and its pressure at the production wellhead (sim_config.target_extraction_pressure), and solve for the injection pressure, the way RAFT's own template sets the well up; this keeps the injected mass rate under tango's control if RAFT loses fluid to storage or leak-off (GitHub #63).SystemBCIterationhands that pressure to the surface plant in the same pass (SurfaceComponent.set_injection_pressure) and waits for it to settle (|ΔP| < 1 kPa), so the surfaceinjection_pressurein these templates is only the first timestep's starting guess. Thenumericalvariant finds the injection pressure by shooting and reproduces a separate-well run's injection pressure and cell profiles to within 7e-11 over 25 years (GitHub #130). A topology diagram,docs/diagrams/AGS_ORC_electric_raft_topology.svg, marks where tango and RAFT exchange these boundary conditions and how each timestep's passes converge.- Optional
raftdependency group for the RAFT wellbore/rock simulator (just setup-raft, oruv sync --group raft), pinned to release tagv0.2.1. Plainuv syncnever fetches it; see the install guide (docs/guides/install.md) for access to the private repo. RAFT runs from a source checkout only: the PyPI package has noraftextra and leaves out the RAFT example (templates/AGS_ORC_electric_raft.yml,templates/raft/) until RAFT's own PyPI name is settled. With direnv, a git-ignored.envrc.localcan setTANGO_UV_SYNC_ARGSso the automatic sync keeps optional groups installed. grouped_subsurfacevariantraft: RAFT simulates the loop's wells and the surrounding rock (templates/AGS_ORC_electric_raft.yml, same site and plant as the numerical example).tango_core.external.raft_wrapper.RaftWrapper(the config'sraft:block) drives RAFT one trial per injection-enthalpy iteration and accepts the last one per timestep, converting between tango's enthalpy and RAFT's temperature. RAFT's config template and mesh (templates/raft/, made by hand; the example's mesh is committed to git) are checked against the tango config rather than overridden. Itsstate/historyrecord, per timestep, RAFT's inlet and outlet values, the solves and wall time the timestep took, RAFT's step statistics for the accepted trial (internal steps, attempts, cuts, and the size of every internal step), and RAFT's profile along the well (pressure, temperature, and enthalpy at each node; mass flow, Reynolds number, and heat transfer coefficient for each element). The step sizes and profiles are lists per timestep, so they are in.results.yml, not the CSV.raft.verbosity(quiet,lite,full) sets RAFT's own console output, separately from tango's--log-level. Withtango_core run --save-dir, RAFT keeps its own output (matrix and well VTKs at the template'soutput_vtk, its flow log) in<stem>.raft/; without it, RAFT writes no VTKs and keeps nothing. The RAFT template setsNR_tolto 1e-8 instead of RAFT's 1e-7: RAFT divides its residual by the mesh's 12,054 nodes, so at 1e-7 the production flow could be off by ~1.2e-3 of the injected rate, above tango's 1e-3 check.- RAFT failures that used to pass silently now raise: a step RAFT
accepted at
timestep_minwith an extrapolation error aboverel_error_T(ConvergenceError). tango checks only what crosses the coupling: the production flow against the injected rate (1e-3,ConfigError) and a liquid outlet (SaturationError); RAFT's profile along the well is recorded but not checked, since it's RAFT's interior. - The RAFT template's well boundary conditions are checked, not switched.
RaftWrapper.preparerequires the template's well inlet group to take a flux and a temperature and its outlet group a pressure (allfunction: external, as in RAFT's own example template) and raisesConfigErrornaming any mismatch; it used to overwrite them silently. - Grouped subsurface docs page (
docs/components/grouped-subsurface.md), withgrouped_subsurface's config keys, its segment andraft:blocks, and its outputs generated bytools/gen_reference.py, which now documents nested config blocks. - CI runs one simulated year on the real RAFT (job "tests with RAFT",
needs the
RAFT_DEPLOY_KEYsecret), so a change in RAFT's coupling API fails CI. FluidState.with_PQ()/update_PQ(): saturation states.Component.accept_timestep(): called once per timestep after the final solve, beforerecord(); a no-op unless a component keeps state outside tango (e.g. in an external simulator).- Docs site —
mkdocs.yml(read by Zensical), adocsdependency group,just docs/just docs-build, and.github/workflows/docs.yml, which builds on every PR and deploys to GitHub Pages once the site is confirmed org-private (PAGES_PRIVATE). - Architecture and runtime pages — layer graph, config-to-objects,
component circuit, nested loops, BC iteration and one-run diagrams under
docs/architecture/anddocs/runtime/; aREADME.mdin eachsrc/tango_core/subpackage; API reference from the docstrings. - README banner and diagrams — a wordmark banner in the cold-to-hot
gradient (
tools/readme_assets.py), a hero and three editable.drawio.svgdiagrams built around one system pictogram: what TANGO models, how you use it, and how the code is organized. All are generated byjust diagramsfromtools/diagrams/. - Component pages (wells, reservoir, surface plant, economics), an
optimization guide, and a config reference and outputs
reference whose tables are generated from the code by
tools/gen_reference.py(just docs-gen; checked in CI). 155 field docstrings were drafted for them and are markedTODO(docs): drafted, review.until reviewed. - Glossary (
docs/guides/glossary.md) and an internal docs preview (mkdocs.internal.yml,just docs-internal) that adds the task log, roadmap, and archive; until the public release, the org-private Pages site deploys this build. AGENTS.mdat the root, indocs/and insrc/tango_core/components/;CLAUDE.mdandGEMINI.mdpoint to it.- Project files —
SECURITY.md(private vulnerability reporting on GitHub),CITATION.cff,.editorconfig, and GitHub templates for pull requests, bugs, features and tasks. - GitHub Actions CI (
.github/workflows/tests.yml) — format check, lint, mypy strict, the generated-docs check, and the pre-push test selection (-m "not slow and not perf") on macOS, Linux and Windows, on every pull request and push tomainanddevelop;license-check.ymlgates releases;.github/workflows/docs.ymlbuilds the docs site on every pull request. - Coverage matrix complete:
AGS_ORC_electric.yml,hydro_direct_heat.yml,CPG_direct_heat.yml,CO2_EGS_direct_heat.yml,CO2_AGS_direct_heat.yml, and the CO2 power cells, including direct-CO2 plantsCO2_EGS_electric.ymlandCO2_AGS_electric.yml(the CO2 itself drives the turbine; LCOE 0.40 and 2.89 vs 1.55 and 10.9 for the binary versions). Matrix and per-config review checklist: GitLab #67. - Interactive P-h phase diagrams (GitLab #56):
tango_core run --save-dirwrites one Plotly<config>.phase_<fluid>.htmlper working fluid, with a year slider, configurable isotherms/isentropes/isochores/ quality lines (--phase-diagram-config), a shaded two-phase region, a phase-color legend, and wells drawn along their computed profiles (including the downhole pump step).just phase-diagramswrites every config's into gitignoredscratch_output/<config>/. - Run-time guards in
GraphSurface, as typed errors that optimizers treat as infeasible designs: PassivePressureRiseError: a heat exchanger, valve, separator, mixer or cycle closer whose outlet pressure is above its inlet (TESPy solves a fixed absolutep_outabove the real inlet as free compression).NegativeNetPowerError: a turbine plant that consumes more power than it makes. Checked once per timestep, on the converged state.ValveCannotRaisePressureError: aPumpOrValveon its Valve leg whose pressure would rise. The only power-state error that retries the node as a pump; any other is reported as itself.NegativeNetThermalError: a heat plant whose produced fluid has cooled so far (e.g. a depleted reservoir) that itsnet_thermalexchangers would heat it. Checked once per timestep, on the converged state.TESPyConvergenceError: an unconverged TESPy solve, except TESPy's measured ~1 J/kg stall on a pump drawing exactly saturated liquid, which is used with a warning naming the pump.subcooling_Ksurface-node key (TESPyTd_bp,td_bubblesince TESPy 0.11): an outlet that many kelvin below saturation at its actual pressure.- Third-party license tooling:
tools/check_licenses.pyrecords the dependency graph (direct/indirect, depth, scope), evaluates license expressions, supports reviewed approvals, and draws a draw.io dependency tree; alicense_checkCI job runs on MRs intomainand on release tags. docs/SOURCES.md, a verified bibliography that code and configs cite by key;docs/is now user-facing (shipped in the wheel), with developer docs indev_docs/.dev_docs/tespy_limitations.mdlists what TESPy solves without complaint and TANGO's guards.
Changed¶
- Breaking:
tango_core runneeds--save-dir DIRor--no-save. Running without either (or with both) now stops with an argparse error, so results are never lost by forgetting--save-dir;--no-savewrites nothing, for tests and quick checks (GitHub #125). - One name:
tango_core. The import package istango_core(import tango_core,src/tango_core/), matching the distributiontango-core, and the command istango_core(tango_core run,tango_core validate,tango_core init,tango_core --version).import tangoandtango_cliare gone, with no alias; update imports and scripts. The CLI module istango_core.cli, and the source hash DVC tracks issrc/tango_core.hash. - Python 3.12 and 3.13 are supported as well as 3.11
(
requires-python = ">=3.11,<3.14"); a CI job installs the package as a PyPI user would and runs the tests on both. numpy is capped below 2.5, which removednumpy.row_stackthat pymoo 0.6.1.3 still calls. - Fewer runtime dependencies. Installing
tango-coreno longer pulls in packages its code doesn't use (pip,pexpect,python-arango,tqdm,msgpack,oyaml,termcolor,tabulate,openpyxl,seaborn,polars,jinja2,networkx,fluprodia), type stubs, or DVC plugins; the pinnedpip<24no longer downgrades pip. Thedevextra is gone: development tools are an unpublished dependency group thatuv syncinstalls. - Smaller source archive (sdist). It now holds the package source, tests, templates, applications, and the release files (license, README, changelog, citation) instead of every file in the repository, and leaves out what the wheel leaves out: the on-hold app and the DVC locks; the wheel is unchanged.
- SPDX license headers. Every Python file starts with
SPDX-FileCopyrightTextandSPDX-License-Identifierlines, andREUSE.tomlcovers the other files, so the repository complies with the REUSE specification. Areuse lintprek hook keeps it that way. - License: Apache-2.0. TANGO is open source under the Apache License,
Version 2.0 (
LICENSE.txt), copyright 2025 ETH Zurich. The proprietary license and the internal distribution notice (NOTICE) are gone. The package metadata declares the SPDX expressionApache-2.0, andtango_core --versionprints the copyright and license line. example_configs/is nowtemplates/.tango_core initcopies it toDEST/templates/, and the wheel ships it astango_core/templates/.- Forge — GitHub (
GEG-ETHZ/TANGO-core) replaces gitlab.ethz.ch for code, issues, pull requests, CI and releases. Install and clone commands, contributor workflow and release steps point to GitHub;.gitlab-ci.ymland.gitlab/are removed. - README — rewritten as a landing page: overview, diagrams,
requirements, installation, quickstart, documentation map, help, citation
and license. Detailed install, run and Euler steps moved to
docs/guides/. - CONTRIBUTING, directory READMEs, deep dives — restructured with
consistent titles and verified commands.
tests/README.mdnow states correctly that the pre-push hook skipsslowandperftests. - Historical docs — progress summaries, refactor notes and the phase
0/1 diagrams moved to
docs/archive/, off the site. - Developer docs are back in
docs/. The task log, roadmap, design notes and archive sit next to the site pages; the public build excludes them and the internal preview includes them.dev_docs/is gone. The wheel still ships onlydocs/SOURCES.mdfromdocs/. tango_core run --save-dirwrites the full results as<name>.results.yml(was<name>.yml, the same name as the input file).- CSV headers carry units: every
.smry.csv/.econ.csvcolumn ends in its unit, e.g.production_well_T_outlet [K],LCOE [USD/kWh]. - Phase diagrams number every state point in flow order, with a "State points" key under the plot, and open on the final year instead of animating through every year on load.
- TESPy 0.7.1 → 0.11.2 (GitLab #75). LCOE results for every example
config are unchanged to 1e-6. ORC designs that used to fail to converge at
random now solve every time. The
subcooling_Ksurface-node key now maps to TESPy'std_bubble. - Linked config values have one source. A quantity that several
components need is written once and the rest derived
(
tango_core.workflows.linked_quantities); a config that gives a copy which disagrees raisesConfigErrorinstead of running with it. Doublet:reservoir.reservoir_depthand the pump depth (production_well_upper.well_length) set the injection well's length, the lower production segment,well_eff_diameterandhydro_static_pressure(= brine density x g x depth; 2% lower than the old hand-entered 50 MPa in the hydro configs, 24.5 vs 25 MPa in CPG). AGS: the injection well's length sets the production well and the loop's depth, and the loop length setslayout.well_spacing. Every example config drops its redundant copies. - Numerical wells:
num_cellsandcell_lengthare linked towell_length(give either, both if they agree, or neither for the default). Derived values (T_r, cross-section, ...) are no longer written byto_dict(), and a config that supplies one that disagrees raises instead of being silently overwritten;LumpedReservoir's derived values work the same way.set_well_length()changes a length with an explicit choice of what follows it. - Surface-node keys are checked: an unknown key (a typo, a renamed key)
raises
ConfigErrorinstead of being ignored. The TESPy starting-pressure guess is nowp0_megapascals_out{N}, in MPa likep_out_megapascals; the oldp0_out{N}was passed to TESPy unconverted in bar, so the ORC configs' and opt apps' MPa values were 10x too low. - Realistic component efficiencies in every example config, each with
a citation: turbines 0.85 and surface pumps 0.75 (DiPippo 2016),
downhole pumps 0.55 overall ESP string (van 't Spijker & Ungemach 2016).
Three marginal examples were adjusted to stay net-positive
(
EGS_electric.ymldeepened to a hypothetical 5000 m;CPG_electric.ymlat 125 kg/s;CO2_AGS_ORC_electric.ymlat 20 years). - Descriptive surface node names in the example configs (e.g.
evaporator,preheater,flash_valve,separator,brine_pump,condensate_pump,district_heating_hx; everyPumpOrValveiscirculation_control). Application parameter paths that address these nodes changed accordingly. - Binary (ORC) plant configs carry
ORCin their file names. - Condensers subcool by 1 K (
subcooling_K: 1.0) instead of ending at exactly saturated liquid, except four ORC condensers andCPG_electric.yml's, which already sit at or below their cooling limit. tango_core initcopies every application by default (--appnarrows,--no-appsskips).- The pre-push remote-freshness hook passes when you have rewritten your own pushed commits (amend/rebase), and still blocks when someone else pushed.
Removed¶
- The sweep apps (
run_AGS_direct_heat_sweep,run_EGS_direct_heat_sweep,run_hydro_df_electric_sweep,sweep_demo_AGS_direct_heat). Theopt_*apps cover their configs;Workflow's docstring shows the sweep pattern.just appsdrops its--slowflag, which only ran their full grids. auto-pressure,auto-flowandauto-bothinjection modes, withsim_config.max_mass_rateand thehydro_sf_electric_autopressure.ymlandhydro_sf_electric_autoflow.ymlexamples. They iterated pressure or flow toward a fracking threshold within each timestep;auto-pressurecould cycle without converging, andauto-bothwas never implemented. Find operating points with theapplications/opt_*/searches instead, which treat fracking as a constraint undermanual-fracking-check.
Fixed¶
- Phase diagrams color each stretch of a well by its own phase. A well's
profile was drawn in one color, taken from its middle node, so an 8 km AGS
well was colored "supercritical" along its whole length, including the top
~2.3 km below the critical pressure. The line now changes color where it
crosses the critical pressure or the saturation curve. A
grouped_subsurfaceis drawn as its three legs, labeledinjection_well,horizontal_well, andproduction_well, and theraftvariant's legs follow RAFT's recorded profile instead of one straight line. - Mass rate around a closed circuit is checked. The BC iteration fed the
surface outlet's mass rate back as the next pass's injected rate; a
component that lost mass would have lowered the injected rate on every
pass without an error. It now raises
ConfigError(GitHub #63). No example config is affected: every component conserves mass. - Optimizations used the base design's well resolution.
Minimizationbuilt its template withWorkflow.to_dict(), which pinned each numerical well's cell count, so AGS designs with longer wells were simulated with far coarser cells (an 8000 m loop in 10 cells of 800 m instead of 40 of 200 m; up to 1.3% in LCOE). The template is now the config as written. - Sweeps: the EGS direct-heat sweep never moved the lower production segment's starting depth with the reservoir depth, so its rock temperatures stayed at the base design's; the hydro_df sweep varied the reservoir depth and the well lengths independently; all three sweeps inherited the pinned cell counts above. They now build from the YAML and set only source values; the hydro_df one-at-a-time design drops from 59 to 55 rows.
- Parallel optimizations on TESPy 0.11:
Minimizationand the surrogate sweep take a config dict (base_cfg), not aWorkflow, so nothing unpicklable is sent to worker processes. - hydro_df's two flash-pressure parameters give the same design in either application order.
- Energy was lost at every component boundary for CO2: components
passed temperature and each rebuilt enthalpy from (T, P), and near CO2's
critical point the tabular property backend lost up to ~42 kJ/kg per
hand-off (~1.1 MW in
CO2_EGS_direct_heat.yml).Streamnow carries specific enthalpy. The wellhead-to-plant pipe now drops pressure at constant enthalpy (it was isothermal). - Production wells had their rock temperatures upside down: the
rock-temperature profile increased in depth along the flow, which is
reversed for upward flow. Small effect for hydrothermal/EGS/CPG (within
~1%), large for closed AGS loops (
CO2_AGS_ORC_electricLCOE 55.1 -> 10.9). - The injection-enthalpy loop could accept an open loop: its relaxed guess never reached the injection well, and convergence was checked against that unused guess (loop open by up to ~3.6 kJ/kg). Every config now closes within 1 kJ/kg every year.
AUTO_PRESSURE/AUTO_BOTHdepleted the reservoir once per outer iteration instead of once per timestep.- Free compression in two heat configs:
CPG_direct_heat.ymlandCO2_EGS_direct_heat.ymlhad heat exchangers raising pressure for free, which had been letting them reinject dense CO2. Both now use a pressure ratio and an injection cooler;CPG_direct_heat.ymlruns at 75 kg/s and its reservoir now supplies the heat (its CO2 had been reinjected hotter than the reservoir, so all delivered heat was pump work). - The
PumpOrValvefallback reported the wrong error: a negative-net- power or free-compression failure was retried as a pump and surfaced as "negative pump power". - A CO2 EGS power example ran away: reinjected CO2 sat on its
pseudo-critical density drop;
CO2_EGS_ORC_electric.ymlnow cools it before reinjection.
1.0.1 — 2026-09-24¶
Patch release: completes two more cells of the example coverage matrix,
fixes two real bugs found while doing so, adds full regression coverage
for every example_configs/ YAML plus a release-tag test gate, and adds
tango_cli run --save-dir (previously, running a config via tango_cli
directly produced no output at all — only applications/ scripts could
save anything).
Added¶
EGS_electric.yml— completes the EGS coverage-matrix row (heat + power).CPG_electric.yml— new CPG power coverage-matrix cell, ported from old tango'sexamples/CPG_num_pp.yml(preserved at git tagpre-tango-core-rename-2026-09-18).tests/regtest/test_example_configs.py— full-length (realsim_config.num_tsteps, never a reduced smoke count) regression coverage for everyexample_configs/*.yml: injection-well physics invariants, surface net-power/thermal sanity, and a golden LCOE value per config. Includes a guard test that fails if a newexample_configs/file ever ships without coverage.just test --example-configsruns this plushydro_sf_electric.yml's own dedicated, more detailed coverage in one command.- Release-tag test gate (
tools/check_full_tests_before_tag_push.py) — a pre-push hook that runsjust test --alland blocks the push if avX.Y.Zrelease tag is being pushed and the suite fails. Local, not GitLab CI, since this repo's runner is too slow fortests/regtest/(already excluded from CI for that reason). tango_cli run --save-dir DIR— writes<name>.yml(full results, reloadable withWorkflow.from_file()),<name>.smry.csv(one row per timestep, one column per component's own scalar history field), and<name>.econ.csv(one row, the economic component's final state). Saving is opt-in; nothing is written without this flag.- Per-config CoolProp backend selection (
common.coolprop_backend) — BICUBIC's tabulated backend has coarse resolution right at a fluid's critical point; a config can now opt into the exact (slower) HEOS backend near one instead. - New TANGO Commandment: every
example_configs/YAML must be regression-tested (seeCONTRIBUTING.md).
Fixed¶
CPG_electric.yml's surface plant physics: held CO2 supercritical through the whole cycle, including the turbine/condenser outlet pressures — but an absolute pressure only has real physical meaning where temperature and pressure are locked together by a fluid's saturation curve, which doesn't exist above the critical point. Fixed by condensing CO2 after the turbine instead, the same mechanismhydro_sf_electric.yml's water cycle and old tango's own CPG model both use.CPG_electric.yml'sLCOEwasNaN: its condenser'scooling_tower_mode: DRYgave a parasitic cooling-tower power draw that exceeded its own net turbine output (CPG condenses its entire flow, unlikehydro_sf_electric.yml's small flash-split fraction, so this term matters far more here) — andDRYwas never grounded in what old tango's own config actually used (WET, its unoverridden default). Fixed by switching toWET.- Two mis-attributed physics citations: Adams → Zhang for the well heat-loss model, Adams → Birdsell for the well-pattern impedance formula (both verified against Crossref/DataCite).
--p/similar ambiguous CLI abbreviations acrossapplications/scripts used to fail with a confusing "ambiguous option" error instead of a clear one (allow_abbrev=Falseadded everywhere); a script whose--helpsilently ran its sweep instead of showing help;run_hydro_df_electric_sweep.py's docstring/--helpnow states its design-matrix size and that it's fixed, not tunable at runtime.- An orphaned old-tango-vs-new-tango parity test (
test_lcoe_parity) survived — with its original, much-looser tolerance — long after the actual comparison it once ran against was deleted. Replaced with a tight self-consistency golden-value check, consolidated intotest_example_configs.pyalongside every other config's.
Changed¶
just demosrenamed tojust apps— its job is smoke-testingapplications/scripts;example_configs/regression coverage moved tojust test --example-configs/--allinstead of living in this recipe.
1.0.0¶
The first public release. This entry covers everything between old-tango-main-2026-06-08
(the last commit before the multi-month tango_next rewrite landed on main) and this tag —
a full rewrite of TANGO's core, squashed into a single commit
(c5a9d8c, "refactor to make tango robust"). Old TANGO's src/tango/ package still exists,
preserved at git tag pre-tango-core-rename-2026-09-18, but is no longer part of the working
tree; everything below refers to the new implementation unless noted otherwise.
Added¶
GraphSurface: replaces bespoke per-layout Python surface-plant code with a YAMLnodes/edgesgraph. New surface configurations are authored as data, not new component classes.LockedState: enforces that every value meant to be recomputed each simulated year actually is — raises immediately instead of silently reusing a stale number from the previous timestep.InjectionPolicy: replaces three separate, ambiguous fracking-safety settings from old TANGO with a single explicit setting (5 modes: manual, manual+check, auto-pressure, auto-flow, auto-both).- Real economic model and multi-objective optimizer (
pymoo_api): replaces a placeholder economic model. Supports HPC/Euler-parallelized sweeps with automatic worker sizing, mid-run checkpointing, and warm-starting, and saves every evaluated design as a ready-to-run file (rather than only a single "recommended" design as before). Wires parameters and objectives through a small set of composable functions instead of old TANGO'seval-based configuration. - Pydantic-based config validation (
src/tango/core/specs.py): raises typedConfigErrors and warnings for out-of-range, missing, or contradictory configuration values, replacing untyped dict-based config handling. - AGS (closed-loop) direct-heat system: implemented end to end, including a parameter-sweep example — the first fully modern closed-loop system type in TANGO.
- New example ports: added a supercritical-CO2 power-generation topology
(
CPG_electric.yml) and the ORC power cycle (ported ontoGraphSurface). - Adaptive well discretization: scales segment count automatically with well length (manual override still available).
- CI-enforced regression tests: compare new-TANGO output against golden snapshots and against old TANGO's own results.
- "TANGO Commandments": added a short list of hard design rules to
CONTRIBUTING.md(e.g. every closed fluid loop must contain a pump/compressor), each tied to the real bug that motivated it.
Changed¶
- Downhole production-well pump model: replaced constant-temperature (isothermal) pump with an entropy-conserving (isentropic) model including an efficiency penalty — a more accurate ~53% pump-power increase for one benchmark design.
- Production-well pump pressure targeting: replaces a one-shot correction with a real iterative (secant-method) solve that accounts for density feedback on friction loss.
- Fluid-property evaluation: switches the hot path to a pre-tabulated/interpolation mode of the same underlying property library — roughly halves that hotspot's cost, for up to an 18% total runtime improvement (about 2x on surface-solver-heavy runs).
- AGS closed loop: adds a real circulation pump (previously thermosiphon-only); requires every closed fluid loop to contain a pump or compressor, enforced at construction time.
- Labels optimizer output columns explicitly as decision-variable, objective, or reported-only, and shows real units on plot axes.
- Catches CoolProp failures inside the surface-plant solver as a single failed design, instead of crashing an entire optimization run.
Fixed¶
Real physics/correctness bugs found while porting old TANGO's behavior to the new
implementation (see docs/bugs-fixed-in-tango.md for full detail on each):
- Fixed AGS never advancing simulated time past year one in old TANGO (a fake-convergence
bug) — every downstream multi-year AGS number from the old system was invalid. The new
implementation's
LockedStateguardrail structurally cannot have this bug. - Fixed the new implementation's own reservoir initial-pressure formula, which borrowed a safety-ceiling formula instead of the true initial condition (~12% error); now agrees with old TANGO to sub-microkelvin precision.
- Fixed an AGS well-depth bug: a well starting partway down another well segment had its surrounding rock temperature computed as if it started at the surface, modeling a heat sink as a heat source. Corrected the best-case AGS design temperature from 92.7°C to 136.6°C.
- Fixed old TANGO's well-cost safety-limit formula, which used diameter where the equation
called for radius (off by a factor of
-ln(2)). - Fixed old TANGO's
check_fracking, which didn't gate what its name implied (only capped flow, not pressure) — superseded by the unifiedInjectionPolicy. - Fixed old TANGO's boolean config fields, which used
== "yes"string comparisons soTruein YAML silently did nothing — the new implementation uses real booleans throughout. - Fixed old TANGO silently swallowing solver non-convergence (warning and proceeding, or
reusing the last unconverged guess) — the new implementation raises
ConvergenceError. - Fixed the economic model double-counting well mobilization cost when a well was split into multiple physics sub-components.
- Fixed numerically-marched wells falling about 1% short of their declared length (an off-by-one in the march step count).
- Fixed the optimizer scoring a crashed design better than a design that ran but failed — a crash now always scores strictly worse.
Known limitations¶
- MOOSE-coupled examples (~55 configs) cannot currently be run — hardcoded to a former team member's machine with no remaining documentation. Not part of this release.
- Pump electricity accounting needs human-in-the-loop verification before net-power or LCOE outputs should be trusted; the current implementation is based on static code analysis only.
GraphSurface's fixed outlet pressures (flash pressure, condensing pressure) are a deliberate modeling choice — real plant control targets, not derived quantities — but are only self-consistent if calibrated to the site's assumed conditions, and nothing currently checks that. Old TANGO's pressure-monotonicity sanity guard has no equivalent yet. Seedocs/TANGO_vision_and_roadmap/README.mdfor the full discussion.- Seasonal heat-demand variation is not modeled — direct-heat and cogeneration examples run at constant mass flow.
- Combined heat-and-power (cogeneration) has topology precedent and support in
GraphSurface, but the economic side (how to compute/report a combined levelized cost) needs a design decision before an example is built. - Deleted old TANGO's
examples/directory and its example-coverage audit as part of this release's cleanup; preserved at git tagpre-tango-core-rename-2026-09-18for anyone who needs to consult them.