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 |
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.