Orchestrators¶
Run the component circuit through each timestep.
tango_core.orchestrators.system_direct
¶
SystemDirect — single-pass orchestrator for tango.
Auto-selected when sim_config.injection_mode is absent — i.e. the input graph declares no boundary-condition variable to solve for (e.g. a bare wellbore test fixture). Executes each component exactly once per timestep, in component_idx order, wiring each component's outlet into its downstream neighbor's inlet immediately after it solves.
The run advances one sync interval at a time (see
tango_core.core.time_stepping). With a single subsystem, every step is
its own interval. With several, each subsystem takes its own steps through
the interval in circuit order, and a stream passing into another subsystem
is collected over the sender's steps and handed to each of the receiver's
steps through the edge's SyncRule (sync_stream). A stream that
wraps around the circuit, from the last subsystem back to the first,
reaches the first subsystem in the next interval, the same one-pass lag
as between two steps of a single subsystem.
This is also the base class for SystemBCIteration (see that module's docstring). SystemDirect owns the only implementation of "one circuit pass" and "loop over timesteps" — SystemBCIteration reuses both via inheritance instead of re-implementing them. The choice between the two orchestrator classes is a topology question (does this graph declare a BC-iteration circuit at all); InjectionPolicy is the sole authority over how many passes a single sync interval takes once that topology choice has been made.
SystemDirect(components, time_stepping, economic=None)
¶
Bases: Orchestrator
Single-pass orchestrator: one circuit pass per timestep, no BC concept.
Also the base class for SystemBCIteration — see module docstring.
Initialize, sorting components by component_idx for circuit order.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
components
|
dict[str, FlowComponent]
|
Named physical components keyed by YAML name. |
required |
time_stepping
|
TimeStepping
|
The run's subsystems, grids, and sync rules
( |
required |
economic
|
EconomicComponent | None
|
Optional economic component (from the |
None
|
Raises:
| Type | Description |
|---|---|
ConfigError
|
A subsystem is not a contiguous run of
|
intervals = time_stepping.intervals()
instance-attribute
¶
The run's sync intervals, in order; each pass of run() solves one.
components
property
¶
Return the named component dict.
run_interval(i)
¶
Execute one circuit pass over sync interval i.
record(interval)
¶
Record every component in the circuit for the accepted interval.
Each component records its held steps first, then its subsystem's last step in the interval from its live state.
finalize()
¶
Run the economic component (if any) exactly once, after all timesteps.
Called by run() after the loop over self.intervals
finishes — not once per interval like run_interval(), because
CAPEX sizing and the LCOE denominator both read the physical
components' recorded history over the whole run (run-averaged
turbine/pump/HX duty and net power/thermal output; see
components/economic/doublet.py), which is complete only after
the last timestep.
The economic component has no inlet/outlet (it is a plain
Component, not a FlowComponent), so it gets the whole
components dict handed to it directly (a private, non-Pydantic
attribute — the same "live cross-reference" pattern GraphSurface
already uses for its TESPy network), rather than going through the
Stream hand-off every flow component uses.
run()
¶
Execute every sync interval, then the economic finalize step (if any).
tango_core.orchestrators.system_bc_iteration
¶
SystemBCIteration — convergence-loop orchestrator for tango.
Auto-selected when sim_config.injection_mode is present in the input file.
━━━ What this solver is doing ━━━
Each sync interval (with a single subsystem, each timestep) solves the
closed circuit (injection well -> reservoir or loop -> production well(s)
-> surface -> back to the injection well) at a fixed mass rate and
injection wellhead pressure, both from the config. The circuit's one
unknown is the injection temperature/enthalpy: the surface plant's outlet
becomes the injection well's inlet, so _converge_injection_enthalpy
re-solves the circuit until that enthalpy stops moving.
With several subsystems, each pass of that loop solves every subsystem
through all its steps in the interval (see SystemDirect), and the
injection enthalpy is one value for the whole interval: the circuit entry
holds it over each of its steps, and the loop converges it to the surface
plant's outlet enthalpy averaged over the interval. time_stepping.sync
therefore cannot set a rule for the edge into the circuit entry.
One exception to the fixed injection pressure: a grouped_subsurface at
the circuit entry fixes the production wellhead pressure instead
(target_extraction_pressure) and solves for the injection pressure it
needs (see tango_core.components.well.grouped_subsurface's "Boundary
conditions"). Right after it solves, each pass sets the surface plant's
injection pressure to that value (SurfaceComponent.set_injection_pressure),
so the plant delivers it in the same pass, and the loop is converged only
once that pressure has also stopped moving (_DP_INJECTION_TOL). The
surface plant's configured injection_pressure is then only the first
timestep's starting guess.
Two independent sub-problems — do not conflate:
- Injection enthalpy (this loop) — converges the surface outlet's enthalpy fed back into the injection well.
- Production pump (inner loop, inside the production well) — finds the
pump pressure rise needed to lift the produced fluid to
target_extraction_Pat the surface inlet.
MANUAL_FRACKING_CHECK then compares the solved state against both
fracking limit, by pressure and by flow (see InjectionPolicy), and raises
FrackingViolationError on a violation; MANUAL doesn't check. There
is no mode that adjusts pressure or flow toward a fracking threshold:
finding a good operating point is an optimization question (LCOE vs.
power), answered by the opt_* applications with fracking as a search
constraint. See InjectionPolicy (tango_core.core.policies).
━━━ Planned: inner pump loop ━━━
The old BC_calculator had a hardcoded 5-iteration loop for pump_dp with a
d(P_out)/d(P_in) ≈ 1 assumption and silent failure on phase-boundary
crossings. Replace with a convergence-based loop::
for pump_iter in range(MAX_PUMP_ITER): # MAX_PUMP_ITER = 50
try:
pump.solve(inlet_P=prod_well.outlet_P + pump_dp, ...)
except SaturationError:
pump_dp += (target - pump.outlet_P)
continue # also halve step on boundary-crossing
dp_error = target - pump.outlet_P
if abs(dp_error) / target < PUMP_TOLERANCE:
break
pump_dp += dp_error
else:
raise ConvergenceError(...)
SystemBCIteration(components, time_stepping, mass_rate, bc_checkpoint_idx, policy=InjectionPolicy.MANUAL, max_inner_iterations=DEFAULT_MAX_INNER_ITER, economic=None)
¶
Bases: SystemDirect
Convergence-loop orchestrator for injection-pressure BC iteration.
Subclasses SystemDirect, reusing its component ordering/wiring
(self._ordered, _pending_inlets/_record_outlet/_next_inlet)
as the building block.
Each timestep runs an injection-enthalpy convergence loop
(_converge_injection_enthalpy) that re-solves the whole circuit every
iteration; MANUAL_FRACKING_CHECK then checks the result against both
fracking limit. The choice between SystemDirect and this class is a topology
question (does this graph declare a circuit with a BC variable to solve
for at all), not a duplicate encoding of policy.
Components are executed in ascending component_idx order each
iteration. The injection well (idx 0) is solved first; the circuit
continues through reservoir → production wells → surface → back to
injection well.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
components
|
dict[str, FlowComponent]
|
Named components keyed by YAML name. |
required |
time_stepping
|
TimeStepping
|
The run's subsystems, grids, and sync rules
( |
required |
mass_rate
|
float
|
Mass flow rate (kg/s) — from |
required |
bc_checkpoint_idx
|
int
|
|
required |
policy
|
InjectionPolicy
|
Injection control policy (default |
MANUAL
|
max_inner_iterations
|
int
|
Maximum iterations for the injection-
temperature convergence loop ( |
DEFAULT_MAX_INNER_ITER
|
economic
|
EconomicComponent | None
|
Optional economic component — see |
None
|
Initialize the base single-pass engine, then store BC-specific state.
See the class docstring for the meaning of each argument.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
components
|
dict[str, FlowComponent]
|
Named components keyed by YAML name. |
required |
time_stepping
|
TimeStepping
|
The run's subsystems, grids, and sync rules. |
required |
mass_rate
|
float
|
Mass flow rate (kg/s). |
required |
bc_checkpoint_idx
|
int
|
|
required |
policy
|
InjectionPolicy
|
Injection control policy. |
MANUAL
|
max_inner_iterations
|
int
|
Maximum iterations for the injection- temperature convergence loop. |
DEFAULT_MAX_INNER_ITER
|
economic
|
EconomicComponent | None
|
Optional economic component — see |
None
|
Raises:
| Type | Description |
|---|---|
ConfigError
|
See |
run_interval(i)
¶
Execute one sync interval according to self.policy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
i
|
int
|
Zero-based sync interval index. |
required |
Raises:
| Type | Description |
|---|---|
ConfigError
|
If the circuit has no injection well. |
FrackingViolationError
|
If the fracking limit is exceeded
( |
run()
¶
Execute the full simulation (all sync intervals).
Logs a startup line, then delegates the interval loop to
SystemDirect.run() (inherited), which calls _after_interval
for the per-interval summary.