Install¶
There are two ways to install TANGO:
| You want to | Install as | Section |
|---|---|---|
| Use TANGO in your own analysis project | A dependency from PyPI | Use a release |
| Change TANGO itself | A development checkout | Develop TANGO |
Prerequisites¶
| Requirement | Version | Install |
|---|---|---|
| Python | 3.11, 3.12, or 3.13 (TANGO requires >=3.11,<3.14) |
macOS: brew install python@3.11 · Ubuntu/Debian: sudo apt install python3.11 python3.11-venv · Windows: python.org |
| uv | latest | macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh \| sh · Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex" |
TANGO is released under the Apache License 2.0 (see LICENSE.txt).
Use a release¶
- Create a new project for your analysis:
uv init --python 3.13 my-study && cd my-study
In the new pyproject.toml, set requires-python = ">=3.13,<3.14" (or any range within 3.11 to 3.13). TANGO supports Python 3.11 to 3.13, and uv doesn't enforce that upper bound: on Python 3.14 the install fails later, while building a dependency from source.
- From inside the new project, add TANGO from PyPI:
uv add tango-core
With pip instead of uv: pip install tango-core. uv records the installed version in uv.lock, so the build stays reproducible until you upgrade. To pin a specific release, use uv add "tango-core==1.2.0"; to install a tagged release from source, use uv add "git+https://github.com/GEG-ETHZ/TANGO-core.git" --tag v1.2.0. Releases are listed in CHANGELOG.md and cut as described in Contributing.
- Check the installation:
uv run tango_core --version
Expected output starts with tango_core 1.2.0, followed by the copyright and license line.
- Copy the templates and the application pipelines into your project as a starting point:
uv run tango_core init .
This copies the templates/ and every applications/ pipeline (optimizations and demos) that ship with the installed version. Files that already exist are left as they are, so local edits are never overwritten. To copy only some pipelines, add --app <name> (repeatable; --list-apps prints the available names); to skip them, add --no-apps.
- Optional: add RAFT, the finite-element simulator behind the
grouped_subsurfacecomponent'sraftvariant, and run the RAFT example thattango_core initcopied (templates/AGS_ORC_electric_raft.yml, with RAFT's config and mesh intemplates/raft/). RAFT isn't on PyPI yet, so install it from its GitHub release:
uv add "geg-raft @ git+https://github.com/GEG-ETHZ/RAFT@v0.2.1"
uv run tango_core run templates/AGS_ORC_electric_raft.yml --no-save
Run it from the folder that holds templates/: the example finds RAFT's config at templates/raft/ relative to the working directory. A full run takes about 10 minutes.
To upgrade to the latest release, run uv lock --upgrade-package tango-core && uv sync, or uv add "tango-core==<version>" for a specific one.
The distribution is tango-core, and the import name is tango_core:
from tango_core.workflows.workflow import Workflow
Develop TANGO¶
- Clone the repository and install everything, including the development tools and git hooks:
git clone https://github.com/GEG-ETHZ/TANGO-core.git tango-core
cd tango-core
just setup
To push branches, you need write access to the repository; members of GEG usually clone over SSH instead (git@github.com:GEG-ETHZ/TANGO-core.git, see Connect to GitHub with SSH). Everyone else contributes through a fork and a pull request.
Without just, run uv sync, then install the hooks as shown in Contributing.
-
Optional: install direnv and hook it into your shell.
just setupapproves the repository's.envrc. From then on, entering the directory checks the lock file, syncs dependencies and activates the virtual environment. -
Check the setup with a first run:
uv run tango_core run templates/hydro_sf_electric.yml --no-save
Optional: RAFT subsurface simulator¶
The grouped_subsurface component's raft variant delegates the wells and surrounding rock to RAFT. In a source checkout, RAFT is an optional dependency group pinned to a release tag in pyproject.toml (in your own project, see step 5 of Use a release):
- Run
just setup-raft(oruv sync --group raft). With direnv, the recipe also writesTANGO_UV_SYNC_ARGS="--group raft"to the git-ignored.envrc.local, so the automaticuv synckeeps RAFT installed..envrc.localbelongs to one checkout, so runjust setup-raftagain in each new clone or git worktree. - RAFT meshes are made by hand (with RAFT's developer), never generated by tango. The example's mesh,
templates/raft/AGS_single.msh, is committed to git; other meshes are stored with DVC (see Contributing).
RAFT's console output is set separately from tango's --log-level, by verbosity in the component's raft: block: quiet (the default), lite (one line per internal RAFT timestep), or full (everything RAFT prints, including each timestep's extrapolation error). RAFT prints this output directly rather than through Python's logging, so it can't be filtered or redirected with tango's logging settings (GEG-ETHZ/RAFT#10).
Running checks¶
| Check | Command |
|---|---|
| Everything, in CI order (format, lint, type check, fast tests) | just check |
| Tests, fast subset | just test |
| Tests, full suite | just test --all |
| Lint | uv run ruff check . |
| Format | uv run ruff format . (add --check to verify only) |
| Type check | just typecheck |
| Docs site | just docs-build |
Run every command from the repository root.
Troubleshooting¶
| Symptom | Cause and fix |
|---|---|
Permission denied (publickey) during uv add or git clone |
Your SSH key is not registered on GitHub, or your account lacks access to GEG-ETHZ/TANGO-core. Follow the SSH guide linked above, then ask a maintainer for access. |
requires-python / no matching Python |
TANGO needs Python 3.11, 3.12, or 3.13. Install one, or let uv fetch it: uv python install 3.13. |
tango_core init leaves templates/ unchanged |
Intended: it never overwrites an existing folder. Choose another destination, or move the existing folder to get fresh copies. |