Skip to content

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 ParamSpec applies its value to a config dict (and reads it back), and each ObjectiveSpec reads 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 fresh Workflow is built and run from a mutated copy of the base config on every evaluation, rather than trying to mutate a live, already-solved Workflow in place. The same goes for everything sent to worker processes: only plain data (config dicts, picklable specs) crosses a process boundary, never a live Workflow.
  • 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 real out["G"] constraint violation (> 0); pymoo's own constraint-domination ranking (feasible always beats infeasible, regardless of F) means the objective fallback value's magnitude is irrelevant, so it can just be 0.0 rather than a magic huge number.
  • Only specific, known-physical failure modes become a CV — everything else raises. _evaluate_one catches exactly INFEASIBLE_DESIGN_EXCEPTIONS (CoolPropError, FrackingViolationError, ConvergenceError, InvalidPowerStateError, CoolingLimitError, SaturationError, WellPressureCollapseError) — the tango_core errors that genuinely mean "this sampled design is infeasible," not "something is broken." A bare except Exception would also swallow ConfigError (almost always a bug in a ParamSpec.apply, not an infeasible design) and the LockedStateError family (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.