Skip to content

Workflow

Load a config, build the components, pick an orchestrator and run.

tango_core.workflows.workflow

Workflow — top-level entry point for tango simulations.

Workflow(config)

Parses a tango input file and drives the simulation.

Orchestrator is selected automatically from the input file

sim_config.injection_mode present → SystemBCIteration sim_config.injection_mode absent → SystemDirect

Usage::

wf = Workflow.from_file("templates/hydro_sf_electric.yml")
wf.run()

from_file/from_str/to_file/to_str/to_dict are the supported (de)serialization surface — one controlled API for load/dump, insulated from which YAML library is used underneath.

Every to_dict() call reconstructs fresh from this Workflow's actual current live state — common:/layout:/ sim_config: from their retained, frozen, canonical Common/ Layout/SimConfig instances, components: from each live component's own model_dump() (which, being Pydantic, is inherently live — no caching possible). A mutation to a genuinely-mutable field (e.g. surface.injection_pressure) is reflected immediately, every time.

Every top-level YAML block has a real schema: common:/layout:/ sim_config: validate against Common/Layout/SimConfig (core/specs.py); components: and economic: are each validated per-component (every Component subclass, including DoubletEconomicComponent, is its own schema). Unknown keys raise ConfigError at load time rather than being silently accepted and never read by anything. Unlike components:, economic: is deliberately NOT part of the per-timestep circuit — see _build_economic_component() and SystemDirect.finalize().

description: is the one top-level block that's entirely optional (see Description in core/specs.py) — a human-readable summary of what a config models and why, validated if present, simply absent (self.description is None) if not. title: is similar but unvalidated (just read raw as a plain string).

common: gets one more guarantee beyond validation: every component that needs shared fluid/rock parameters holds a REFERENCE to the same Common instance (Pydantic does not copy nested model fields on construction), not an independent copy. Common is frozen, so there's exactly one place these values live and no way for one component to silently diverge from another — structurally, not via a guard list. See core/specs.py.

This is also how fluid identity (Common.fluid_name) is guaranteed consistent across an entire flow path today: every component on the circuit reads it off the SAME shared Common, so there is nothing to hand around or re-check per timestep (Stream, the per-component inlet/outlet type, deliberately carries no fluid-identity field of its own — see core/stream.py). __init__ asserts this identity once, right after building components, so a future refactor that accidentally constructs a second Common for one component fails loudly at construction time instead of silently drifting. If a real fluid boundary is ever introduced (e.g. a secondary/ORC loop with a different working fluid from the geofluid loop), that component would need an explicit second identity of its own — not a relaxation of this check for the whole Workflow.

A common use for to_dict(): parameter sweeps that mutate a copy of the config between runs — safe regardless of whether the Workflow was originally built via from_file/from_str or a raw dict, since it always returns a fresh dict, never a shared reference::

base_wf = Workflow.from_file(path)
for rock_k in sweep_values:
    cfg = base_wf.to_dict()          # fresh reconstruction each call
    cfg["common"]["rock_k"] = rock_k
    Workflow(cfg).run()

Build the orchestrator and components from a parsed config dict.

Linked values across components (e.g. a doublet's reservoir depth and its wells' lengths) are filled in and checked first; see tango_core.workflows.linked_quantities.

from_file(path) classmethod

Load a tango YAML input file and construct a Workflow.

Parameters:

Name Type Description Default
path Path | str

Path to the .yml input file.

required

Raises:

Type Description
ConfigError

If the file does not exist or cannot be parsed.

from_str(s) classmethod

Parse a YAML config string and construct a Workflow.

Raises:

Type Description
ConfigError

If the string cannot be parsed as YAML.

to_dict()

Reconstruct a config dict from this Workflow's CURRENT live state.

Every call recomputes fresh — nothing here is a cached copy of whatever this Workflow happened to be constructed from (see the class docstring for why that matters). Mutating the returned dict never affects this Workflow or any other to_dict() call, since it's built fresh from model_dump() calls, not shared references.

Uses plain model_dump() throughout, NOT mode="json": component state uses float('nan') as LockedState's "not yet computed" sentinel, and mode="json" converts NaN to None (not valid JSON), which then fails to reload. Plain model_dump() keeps it a real float — yaml.safe_dump/safe_load round-trip NaN correctly (the .nan tag). Enum fields (injection_mode, FrictionModel, ...) are normalized to plain strings by _yaml_safe() afterward instead, since that's the only other thing plain model_dump() leaves non-YAML-safe.

to_str()

Serialize this Workflow's current live state back to a YAML string.

to_file(path)

Write this Workflow's config to a YAML file at path.

run()

Execute the full simulation.