Optimization¶
An optimization searches the design space of one config for the best
trade-off between objectives, for example the lowest LCOE against the
highest net power. TANGO runs a full simulation for every candidate design,
so an optimization is many ordinary runs steered by a genetic algorithm
(NSGA-II, from pymoo), implemented in pymoo_api.
Ready-made apps include applications/opt_hydro_sf_electric,
opt_hydro_df_electric, and opt_AGS_direct_heat.
To start, copy the closest app (uv run tango_core init . --app <name>)
and change its parameters and objectives. Run it small first: a tiny
--n-max-gen and --pop-size with a throwaway --save-dir.
The three building blocks¶
A parameter (ParamSpec) is one decision variable: a name, bounds,
and a function that writes the value into a copy of the config. Each
candidate is a fresh config, never a modified live object.
@dataclass
class _PathsApply:
"""Picklable ``ParamSpec.apply`` that sets one value at several config paths.
A module-level dataclass rather than a closure, so it pickles for
``n_processes > 1``. ``read`` returns the value at the first path.
"""
paths: tuple[tuple[str, ...], ...]
def __call__(self, cfg: dict[str, Any], value: float) -> dict[str, Any]:
for path in self.paths:
target = cfg
for key in path[:-1]:
target = target[key]
if path[-1] not in target:
raise KeyError(f"config has no {'.'.join(path)} to set (typo in this param's path?)")
target[path[-1]] = float(value)
return cfg
def read(self, cfg: dict[str, Any]) -> float:
value: Any = cfg
for key in self.paths[0]:
value = value[key]
return float(value)
def _param(name: str, bounds: tuple[float, float], *paths: str) -> ParamSpec:
"""``ParamSpec`` setting ``name`` at each dotted config path in ``paths``."""
return ParamSpec(name=name, apply=_PathsApply(tuple(tuple(p.split(".")) for p in paths)), bounds=bounds)
An objective (ObjectiveSpec) reads one number from a finished run;
every objective is minimized, so a quantity to maximize is negated.
Constraints (ConstraintSpec) work the same way and mark a design
infeasible instead of ranking it.
@dataclass
class _EconomicStateEvaluate:
"""Picklable ``ObjectiveSpec.evaluate`` reading one ``economic.state`` value."""
key: str
def __call__(self, wf: Workflow) -> float:
return float(wf.to_dict()["economic"]["state"][self.key])
Minimization ties them to a base workflow and runs the search, in
parallel when n_processes is above one. A run that fails to converge or
breaks a physical limit counts as infeasible instead of stopping the search.
m = Minimization(
base_cfg=self.base_config(),
params=self.param_specs() if param_specs is None else param_specs,
objectives=self.objective_specs,
constraints=self.constraint_factory(args) if self.constraint_factory is not None else [],
report_specs=self.report_specs,
pymoo_config=PymooConfig(
n_max_gen=args.n_max_gen,
pop_size=args.pop_size,
ftol=args.ftol,
xtol=args.xtol,
termination_period=args.termination_period,
n_processes=args.n_processes,
seed=None if args.no_seed else args.seed,
crossover_prob=args.crossover_prob,
mutation_prob=args.mutation_prob,
report_archive=args.report_archive,
),
verbose=not args.quiet,
save_dir=args.save_dir,
seed_from=args.seed_from,
check_param_sensitivity=not args.skip_param_check,
capture_trajectory_path=args.capture_trajectory,
)
res, df = m.run()
The examples above are included from applications/opt_hydro_sf_electric/opt_hydro_sf_electric.py and from OptApp.run_optimization in src/tango_core/pymoo_api.py, so they always match the code.
How the optimization works¶
Multi-objective optimization API for tango, built on pymoo.
A thin wrapper around pymoo that provides:
- Typed interfaces (
Minimization,ParamSpec,ObjectiveSpec,PymooConfig) in place of pymoo's*args/**kwargs-heavy API, so a misconfigured search fails at construction instead of deep inside pymoo. - A strong mechanism for setting decision variables and extracting
objectives: each
ParamSpecapplies its value to a config dict (and reads it back), and eachObjectiveSpecreads one number from a finished run. - Parallel evaluation with minimal configuration: set
PymooConfig.n_processes. - Plotting utilities (Pareto scatter and parallel-coordinates plots) to help downselect designs from a front.
Adapted to tango's actual seams:
- Parameters mutate config dicts, not live objects.
Workflow.to_dict()'s own class docstring already shows this exact pattern (cfg = base_wf.to_dict(); cfg[...] = ...; Workflow(cfg).run()) — a freshWorkflowis built and run from a mutated copy of the base config on every evaluation, rather than trying to mutate a live, already-solvedWorkflowin place. The same goes for everything sent to worker processes: only plain data (config dicts, picklable specs) crosses a process boundary, never a liveWorkflow. - Constraint violations are real pymoo constraints, not objective-space
penalties. A common alternative pattern falls back to a fixed huge
objective value (e.g.
1.02e12) on simulation failure — that value has to be large enough to dominate every real objective, which makes it scale-dependent and easy to get wrong. Here, a failed evaluation instead sets a realout["G"]constraint violation (> 0); pymoo's own constraint-domination ranking (feasible always beats infeasible, regardless ofF) means the objective fallback value's magnitude is irrelevant, so it can just be0.0rather than a magic huge number. - Only specific, known-physical failure modes become a CV — everything
else raises.
_evaluate_onecatches exactlyINFEASIBLE_DESIGN_EXCEPTIONS(CoolPropError,FrackingViolationError,ConvergenceError,InvalidPowerStateError,CoolingLimitError,SaturationError,WellPressureCollapseError) — thetango_coreerrors that genuinely mean "this sampled design is infeasible," not "something is broken." A bareexcept Exceptionwould also swallowConfigError(almost always a bug in aParamSpec.apply, not an infeasible design) and theLockedStateErrorfamily (internal contract violations), silently poisoning results across a long unattended search instead of crashing loudly where the bug actually is.
InjectionPolicy: the base config must set sim_config.injection_mode
(MANUAL or MANUAL_FRACKING_CHECK, the only modes there are); the
search itself chooses the operating point, with a fracking violation under
MANUAL_FRACKING_CHECK counting as an infeasible design.
Every class and option: API reference.