Skip to content

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 (SimConfig.time_stepping_for()); every component is in exactly one subsystem.

required
economic EconomicComponent | None

Optional economic component (from the economic: YAML block). Deliberately kept OUT of components/ _ordered/_by_idx — it must run exactly once, after every physical timestep completes (see finalize()), not once per timestep like every other component. See DoubletEconomicComponent's module docstring for why it can't just be component_idx N+1 in the per-timestep loop.

None

Raises:

Type Description
ConfigError

A subsystem is not a contiguous run of component_idx, a sync rule names an edge the circuit does not have, or a component that keeps external state takes more than one step in a sync interval.

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:

  1. Injection enthalpy (this loop) — converges the surface outlet's enthalpy fed back into the injection well.
  2. Production pump (inner loop, inside the production well) — finds the pump pressure rise needed to lift the produced fluid to target_extraction_P at 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 (SimConfig.time_stepping_for()).

required
mass_rate float

Mass flow rate (kg/s) — from sim_config.mass_rate, used every timestep.

required
bc_checkpoint_idx int

component_idx of the boundary-condition checkpoint component (the surface) — from sim_config.bc_checkpoint_idx. Used to look up the surface via _find_surface() for circuit-seeding and convergence checks.

required
policy InjectionPolicy

Injection control policy (default MANUAL).

MANUAL
max_inner_iterations int

Maximum iterations for the injection- temperature convergence loop (_converge_injection_enthalpy, used by MANUAL/MANUAL_FRACKING_CHECK). Raises ConvergenceError if exhausted without converging.

DEFAULT_MAX_INNER_ITER
economic EconomicComponent | None

Optional economic component — see SystemDirect.__init__.

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

component_idx of the boundary-condition checkpoint component (the surface).

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

None

Raises:

Type Description
ConfigError

See SystemDirect.__init__; also a time_stepping.sync rule for the edge into the circuit entry, whose inlet this loop converges instead.

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 (MANUAL_FRACKING_CHECK only).

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.