Techno-economic ANalysis of Geoenergy Operations. TANGO couples reservoir, wells, and surface plant in one modular simulator, solves them over the project's lifetime, and computes the levelized cost of electricity or heat.
Note
TANGO is research software of the Geothermal Energy and Geofluids group at ETH Zürich, released under the Apache License 2.0.
- What TANGO models
- How you use TANGO
- How the code is organized
- Start here
- Setup
- Documentation and layout
- Development and help
- License
To run TANGO, go to Setup. To work on it, read the package tour and CONTRIBUTING.md. Working with an AI agent? Paste this into it:
Read AGENTS.md in GEG-ETHZ/TANGO-core; it holds every instruction for agents in this repository.
TANGO needs Python 3.11, 3.12, or 3.13 (>=3.11,<3.14) and uv. just and direnv are optional. The distribution is tango-core, the import name is tango_core, and the command is tango_core.
Add it to your own project from PyPI:
uv add tango-core # or: pip install tango-core
uv run tango_core init . # copies the templates into ./templatesTo install a tagged release from source instead, use uv add "git+https://github.com/GEG-ETHZ/TANGO-core.git" --tag v1.2.0.
Or clone the repository to work on it:
git clone git@github.com:GEG-ETHZ/TANGO-core.git tango-core
cd tango-core
just setup # installs dependencies and all git hooksThen run the flagship example, a single-flash hydrothermal power plant, and save its results:
uv run tango_core validate templates/hydro_sf_electric.yml
uv run tango_core run templates/hydro_sf_electric.yml --save-dir results/results/ then holds the solved config, a per-timestep CSV and an economics CSV. The same from Python:
from tango_core.workflows.workflow import Workflow
wf = Workflow.from_file("templates/hydro_sf_electric.yml")
wf.run()The installation guide covers installing from PyPI, pinning a release, upgrades, and setting up a development checkout; Run a simulation describes each result file and the exit codes; optimizations live in applications/.
The documentation is published at https://geg-ethz.github.io/TANGO-core/, built from docs/; just docs previews it locally.
| Section | What it covers |
|---|---|
| Getting started | Installation, first run, templates, applications, Euler |
| Architecture | Package layers, config to objects, the component circuit |
| Runtime | The nested loops, boundary-condition iteration, one run end to end |
| API reference | Generated from the docstrings |
| Contributing | The TANGO commandments, workflow, tests, releases |
src/tango_core/ the package: core, components, orchestrators, workflows, CLI, optimization
templates/ maintained configs, one or more per system type; back the tests and applications
applications/ optimizations and demos; each optimization is a DVC pipeline with a SLURM script
tests/ unit/ (fast, run in CI) and regtest/ (full simulations; the fast subset runs before push)
docs/ the documentation site: guides, architecture, runtime, deep dives, API reference
tools/ maintenance scripts, the diagram generators and git-hook helpers
just check # format, lint, strict type check, fast tests
just docs # documentation site on localhost
just diagrams # regenerate the banner and the diagramsCode changes follow the TANGO commandments; branching, pull requests and releases are in CONTRIBUTING.md and changes per release in CHANGELOG.md.
| Need | Where |
|---|---|
| A question about using TANGO | Open an issue on GitHub |
| A bug | Open an issue with the config and the full traceback; see Error tracebacks |
| A security problem | Follow SECURITY.md; do not open a public issue |
| A publication | Cite TANGO with CITATION.cff or DOI 10.5281/zenodo.23952662, which always resolves to the latest release; GitHub shows a "Cite this repository" button |
Copyright © 2025 ETH Zurich. Authors: Chad Baker and Dubhaltach McSweeney, Geothermal Energy and Geofluids (GEG) group, Department of Earth and Planetary Sciences.
TANGO is licensed under the Apache License, Version 2.0; see LICENSE.txt.