Run a simulation¶
This guide runs one TANGO simulation from a config file, saves its results and points to the tools for running many. It assumes TANGO is installed (Install).
1. Choose a config¶
Start from a maintained config in templates/; never write one from scratch. Each covers one system type and is regression-tested, so it is the reference for what a valid config looks like. The list is in Templates. The flagship is templates/hydro_sf_electric.yml, a hydrothermal doublet with a single-flash surface plant.
2. Validate it¶
uv run tango_core validate templates/hydro_sf_electric.yml
validate checks that every required field is present, every component type is registered and every schema is satisfied, without running any physics. A problem is reported as a ConfigError that names the field.
3. Run it¶
uv run tango_core run templates/hydro_sf_electric.yml --save-dir results/
The run logs one summary line per timestep. With --save-dir DIR, it writes three files:
| File | Contents |
|---|---|
<name>.yml |
Every component's final config and state; reload it with Workflow.from_file() |
<name>.smry.csv |
One row per timestep, one column per recorded quantity |
<name>.econ.csv |
The economics: CAPEX by category, OPEX, LCOE. Omitted if the config has no economic: block |
Every run needs either --save-dir DIR or --no-save, which writes nothing; without one of them tango_core run stops with an error, so results are never lost by forgetting the flag. To see every convergence iteration, add --log-level DEBUG. One run shows what happens inside a run.
Exit codes¶
| Code | Meaning |
|---|---|
0 |
Success |
1 |
The config is invalid (ConfigError) |
2 |
The simulation failed, for example it did not converge or violated the fracking limit (any other TangoError) |
An unexpected exception that is not a TangoError (a bug) also ends the process with exit code 1, but prints a Python traceback instead of a one-line message. Report it as a bug.
uv run tango_core --version prints the installed version and the license line. Quote the version together with any result you share.
4. Run from Python¶
from tango_core.workflows.workflow import Workflow
workflow = Workflow.from_file("templates/hydro_sf_electric.yml")
workflow.run()
Optimizations use this pattern: load a config, change values, build a Workflow and run it.
Tests, templates and applications¶
Three directories hold runnable material, each for a different purpose:
| Directory | Purpose | Run with |
|---|---|---|
tests/ |
Automated correctness checks. tests/unit/ covers components in isolation; tests/regtest/ runs full simulations, including a golden LCOE per template |
just test (see Running checks) |
templates/ |
The maintained configs; each backs a test, an application or both | uv run tango_core run templates/<file>.yml --save-dir results/ |
applications/ |
Multi-run pipelines built on a template: optimizations and demos | DVC or the app's own script |