Skip to content

Components

The physical and economic components a config wires into a circuit.

tango_core.components.registry

Component registry for tango.

Maps (type, variant) string pairs from the input YAML to concrete Component classes. Workflow.from_file() uses this to instantiate components without hard-coding class names.

To add a new component type
  1. Implement the Component subclass with a from_dict(config: dict) classmethod.
  2. Add a (type_str, variant_str): ClassName entry here.

tango_core.components.well.base

Abstract base for well components in tango, and the well sections the economic model costs.

HORIZONTAL_ANGLE_DEG = 90.0 module-attribute

angle_from_vert_deg of a horizontal well (0 = straight down, 180 = straight up -- see components/well/numerical.py's module docstring).

WellRole

Bases: StrEnum

What a drilled well section is for, which decides how the economic model costs it.

HORIZONTAL = 'horizontal' class-attribute instance-attribute

A horizontal section (e.g. an AGS loop's lateral): a separate drilling operation, costed on its own.

PRODUCTION = 'production' class-attribute instance-attribute

A vertical production section. Several of them may make up one physical wellbore (e.g. a lower section plus an upper one carrying a pump).

WellSection(role, well_length, diameter, pump_power_watts_history=(), pump_power_durations=()) dataclass

One drilled well section, as the economic model sees it.

well_length instance-attribute

Drilled length (m).

diameter instance-attribute

Inner diameter (m).

pump_power_watts_history = () class-attribute instance-attribute

Downhole pump power draw (W) per recorded timestep; empty for a section without a pump.

pump_power_durations = () class-attribute instance-attribute

Length (s) of the step behind each entry of pump_power_watts_history, for time-weighted means.

HasWellSections

Bases: Protocol

A component that contains drilled well sections.

well_sections()

Return this component's well sections, in flow order.

WellComponent

Bases: FlowComponent

Abstract base for all wellbore components (injection and production).

Concrete implementations: LumpedInjectionWell, NumericalInjectionWell, LumpedProductionWell, NumericalProductionWell, LumpedProductionWellWithPump.

All wellbore geometry fields live here — subclasses add fluid/physics fields.

prev = Field(frozen=True) class-attribute instance-attribute

Circuit index of the upstream component.

next = Field(frozen=True) class-attribute instance-attribute

Circuit index of the downstream component.

well_length = Field(frozen=True) class-attribute instance-attribute

Total wellbore length from wellhead to bottom (m).

diameter = Field(frozen=True) class-attribute instance-attribute

Wellbore inner diameter (m).

pipe_roughness = Field(frozen=True) class-attribute instance-attribute

Absolute pipe wall roughness for Darcy-Weisbach friction (m).

gravity = Field(default=GRAVITY, frozen=True) class-attribute instance-attribute

Gravitational acceleration (m/s²) — defaults to core/constants.py's GRAVITY, overridable per well since gravity varies regionally.

solve(inlet, step) abstractmethod

Compute and return the outlet fluid state from the inlet state through the wellbore.

well_sections()

Return this well as a single section.

The well at the circuit entry (component_idx == 0) is the injection well. Any other well is horizontal if its angle_from_vert_deg (NumericalWell only) is 90, and a vertical production section otherwise.

tango_core.components.well.lumped

Lumped-parameter wellbore components for tango.

LumpedInjectionWell and LumpedProductionWell model a single-segment wellbore as a 1-D pipe with: - Darcy–Weisbach frictional pressure drop - Hydrostatic pressure change (positive going down, negative going up) - Linear geothermal temperature profile (no wellbore heat-transfer model)

LumpedProductionWellWithPump adds a pump pressure boost at the wellhead.

Design intent: The Lumped* prefix marks 0-D / lumped-parameter models. These are permanent optional variants to be kept alongside higher-fidelity numerical-integration models once those are implemented. Do NOT deprecate or remove them when adding e.g. NumericalInjectionWell.

Marches in temperature. These wells work in temperature and convert back to enthalpy at the outlet, so they don't conserve energy where enthalpy changes steeply with temperature: near a fluid's critical point or its saturation line. Use variant: numerical (which marches in enthalpy) for CO2 or for flow near saturation; every template's wells do.

Simplified-physics TODOs are marked throughout; upgrade path for each is noted.

WellboreState(h_inlet=_ls(), T_inlet=_ls(), P_inlet=_ls(), mass_rate=_ls(), rho=_ls(), mu=_ls(), velocity=_ls(), Re=_ls(), friction_factor=_ls(), delta_p_friction=_ls(), delta_p_hydrostatic=_ls(), h_outlet=_ls(), T_outlet=_ls(), P_outlet=_ls()) dataclass

Bases: StateMethods

Full simulation state for one wellbore solve step.

All fields are LockedState[float] so that each is writable exactly once per timestep. The dataclass is frozen=True to prevent replacing the wrapper objects themselves (the LockedState invariant is enforced on the value inside). mark_all_stale() (inherited from StateMethods) is called by the orchestrator (via Component.mark_all_stale()) immediately before each solve() to open the write slot for the new timestep.

h_inlet = field(default_factory=_ls) class-attribute instance-attribute

Inlet specific enthalpy (J/kg), from inlet.

T_inlet = field(default_factory=_ls) class-attribute instance-attribute

Inlet temperature (K), derived from (h_inlet, P_inlet); this model's own physics works in temperature.

P_inlet = field(default_factory=_ls) class-attribute instance-attribute

Inlet pressure (Pa).

mass_rate = field(default_factory=_ls) class-attribute instance-attribute

Mass flow rate through the well (kg/s).

rho = field(default_factory=_ls) class-attribute instance-attribute

Fluid density used for the wellbore losses (kg/m3).

mu = field(default_factory=_ls) class-attribute instance-attribute

Fluid dynamic viscosity used for the wellbore losses (Pa s).

velocity = field(default_factory=_ls) class-attribute instance-attribute

Mean flow velocity in the well (m/s).

Re = field(default_factory=_ls) class-attribute instance-attribute

Reynolds number (dimensionless).

friction_factor = field(default_factory=_ls) class-attribute instance-attribute

Darcy friction factor (dimensionless).

delta_p_friction = field(default_factory=_ls) class-attribute instance-attribute

Frictional pressure loss along the well, a positive magnitude (Pa).

delta_p_hydrostatic = field(default_factory=_ls) class-attribute instance-attribute

Hydrostatic pressure difference over the well depth, a positive magnitude; added in injection wells, subtracted in production wells (Pa).

h_outlet = field(default_factory=_ls) class-attribute instance-attribute

Outlet specific enthalpy (J/kg), derived from (T_outlet, P_outlet) -- what outlet carries.

T_outlet = field(default_factory=_ls) class-attribute instance-attribute

Outlet temperature (K).

P_outlet = field(default_factory=_ls) class-attribute instance-attribute

Outlet pressure (Pa).

ProductionWellWithPumpState(h_inlet=_ls(), T_inlet=_ls(), P_inlet=_ls(), mass_rate=_ls(), rho=_ls(), mu=_ls(), velocity=_ls(), Re=_ls(), friction_factor=_ls(), delta_p_friction=_ls(), delta_p_hydrostatic=_ls(), h_outlet=_ls(), T_outlet=_ls(), P_outlet=_ls(), pump_delta_p=_ls(), pump_power_watts=_ls()) dataclass

Bases: WellboreState

Wellbore state extended with pump data for LumpedProductionWellWithPump.

pump_delta_p = field(default_factory=_ls) class-attribute instance-attribute

Pressure rise across the downhole pump (Pa); 0 when no boost is needed.

pump_power_watts = field(default_factory=_ls) class-attribute instance-attribute

Power the pump delivers to the fluid, mass_rate times enthalpy rise including pump efficiency (W); never negative.

WellboreHistory(h_inlet=list(), h_outlet=list(), T_inlet=list(), T_outlet=list(), P_inlet=list(), P_outlet=list(), mass_rate=list(), rho=list(), mu=list(), velocity=list(), Re=list(), friction_factor=list(), delta_p_friction=list(), delta_p_hydrostatic=list()) dataclass

Per-timestep history of scalar wellbore state (inlet → outlet).

One list field per WellboreState attribute (TANGO Commandment: every *State attribute must have an analog in its *History class) — see record().

T_inlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep inlet temperature (K).

T_outlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep outlet temperature (K).

P_inlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep inlet pressure (Pa).

P_outlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep outlet pressure (Pa).

mass_rate = field(default_factory=list) class-attribute instance-attribute

Per-timestep mass flow rate through the well (kg/s).

rho = field(default_factory=list) class-attribute instance-attribute

Per-timestep fluid density used for the wellbore losses (kg/m3).

mu = field(default_factory=list) class-attribute instance-attribute

Per-timestep fluid dynamic viscosity used for the wellbore losses (Pa s).

velocity = field(default_factory=list) class-attribute instance-attribute

Per-timestep mean flow velocity in the well (m/s).

Re = field(default_factory=list) class-attribute instance-attribute

Per-timestep Reynolds number (dimensionless).

friction_factor = field(default_factory=list) class-attribute instance-attribute

Per-timestep Darcy friction factor (dimensionless).

delta_p_friction = field(default_factory=list) class-attribute instance-attribute

Per-timestep frictional pressure loss along the well, a positive magnitude (Pa).

delta_p_hydrostatic = field(default_factory=list) class-attribute instance-attribute

Per-timestep hydrostatic pressure difference over the well depth, a positive magnitude; added in injection wells, subtracted in production wells (Pa).

record(state)

Append one timestep snapshot.

ProductionWellWithPumpHistory(h_inlet=list(), h_outlet=list(), T_inlet=list(), T_outlet=list(), P_inlet=list(), P_outlet=list(), mass_rate=list(), rho=list(), mu=list(), velocity=list(), Re=list(), friction_factor=list(), delta_p_friction=list(), delta_p_hydrostatic=list(), pump_delta_p=list(), pump_power_watts=list()) dataclass

Bases: WellboreHistory

Extends WellboreHistory with pump data for LumpedProductionWellWithPump.

pump_delta_p = field(default_factory=list) class-attribute instance-attribute

Per-timestep pressure rise across the downhole pump (Pa); 0 when no boost is needed.

pump_power_watts = field(default_factory=list) class-attribute instance-attribute

Per-timestep power the pump delivers to the fluid, mass_rate times enthalpy rise including pump efficiency (W); never negative.

record(state)

Append one timestep snapshot, including pump data.

LumpedInjectionWell

Bases: WellComponent

Single-segment injection wellbore: surface → reservoir bottom.

Simplified physics: - P_bottom = P_top + ρ·g·depth − ΔP_friction (down → +hydrostatic) - T_bottom = T_top + thermal_gradient · depth (linear geotherm)

TODO: replace linear T profile with transient conductive model. TODO: replace constant ρ, μ with CoolProp lookups.

common = Field(frozen=True) class-attribute instance-attribute

Shared fluid/rock parameters — a reference to the SAME Common instance every other component in the Workflow holds, not an independent copy. See core/specs.py.

state = Field(default_factory=WellboreState) class-attribute instance-attribute

Well state of the current solve; an orchestrator that re-solves within a timestep restores it first.

history = Field(default_factory=WellboreHistory) class-attribute instance-attribute

Per-timestep record of the well state.

solve(inlet, step)

Compute bottom-hole T and P from surface injection conditions.

LumpedProductionWell

Bases: WellComponent

Single-segment production wellbore: reservoir bottom → surface.

Simplified physics: - P_top = P_bottom − ρ·g·depth − ΔP_friction (up → −hydrostatic) - T_top = T_inlet (perfectly insulated — a more detailed thermal model is future work)

TODO: implement Zhang et al. (2011) transient conduction model. TODO: replace constant ρ, μ with CoolProp lookups.

common = Field(frozen=True) class-attribute instance-attribute

Shared fluid/rock parameters — a reference to the SAME Common instance every other component in the Workflow holds, not an independent copy. See core/specs.py.

state = Field(default_factory=WellboreState) class-attribute instance-attribute

Well state of the current solve; an orchestrator that re-solves within a timestep restores it first.

history = Field(default_factory=WellboreHistory) class-attribute instance-attribute

Per-timestep record of the well state.

solve(inlet, step)

Compute wellhead T and P from reservoir outlet conditions.

LumpedProductionWellWithPump

Bases: WellComponent

Upper production wellbore segment with an optional pump.

TODO: replace with TESPy Compressor or explicit pump curve. TODO: track pump electricity consumption in EconomicComponent. Assumptions: - All of the pump's losses heat the produced fluid. The actual enthalpy rise is the isentropic rise divided by pump_efficiency, and the pump's electricity draw is mass_rate times that same rise. This is right for losses in the pump and its fluid-cooled downhole motor. It is not quite right when pump_efficiency is an overall pump-string figure that also covers surface equipment (cable, transformer, frequency converter), whose losses heat the surroundings rather than the fluid: the electricity draw is still correct, but the discharge enthalpy is slightly overstated (about 1 kJ/kg for a 50 bar boost of hot brine at an overall efficiency of 0.55).

common = Field(frozen=True) class-attribute instance-attribute

Shared fluid/rock parameters — a reference to the SAME Common instance every other component in the Workflow holds, not an independent copy. See core/specs.py.

pump_efficiency = Field(default=1.0, frozen=True) class-attribute instance-attribute

Pump efficiency (dimensionless): the isentropic enthalpy rise divided by the actual one, which is also the electricity drawn per unit mass. Defaults to 1.0 (ideal pump). The templates use 0.55, the overall electric submersible pump (ESP) string efficiency of van 't Spijker & Ungemach (2016) (see docs/SOURCES.md#vantspijker2016): pump 70% × motor 90% × cable 97% × transformer 99% × frequency converter 94%. The overall figure is used, not the 70% pump-only one, because downhole pump power is billed as electricity drawn at the surface. See the class's Assumptions section for what this means for the fluid's enthalpy, and solve()'s docstring for the pump model this scales.

target_extraction_pressure = Field(default=0.0, frozen=True) class-attribute instance-attribute

Target outlet pressure from the pump (Pa). 0 means no active pump. Sourced from sim_config.target_extraction_pressure — the SAME single value SurfaceComponent uses, threaded in by _build_components (see that field's docstring in core/specs.py for the duplicated-value bug this replaced).

state = Field(default_factory=ProductionWellWithPumpState) class-attribute instance-attribute

Well state of the current solve; an orchestrator that re-solves within a timestep restores it first.

history = Field(default_factory=ProductionWellWithPumpHistory) class-attribute instance-attribute

Per-timestep record of the well state.

solve(inlet, step)

Compute wellhead T and P including wellbore losses and pump boost.

If a pump boost is needed, the boosted pump-discharge pressure is found by iterating (Secant method) rather than applied as a closed-form correction tacked onto the natural (un-boosted) result: this segment's OWN friction/hydrostatic loss depends on fluid density, which in turn depends on the (boosted) pressure — a genuine fixed-point problem, not a one-shot calculation.

Pump work uses a standard isentropic-efficiency model (entropy at the true inlet state, isentropic enthalpy at the candidate discharge pressure, efficiency-derated to get the actual enthalpy rise, then flashed back to temperature) rather than assuming the compression is perfectly isothermal. The isothermal/isentropic gap is driven by TEMPERATURE, not pressure level or pressure-rise size: dH|_S - dH|_T = T*alpha*V*dP, where alpha is the fluid's thermal expansion coefficient. Because alpha grows as temperature rises toward the fluid's own critical point, the same pressure boost applied at a higher temperature produces a larger isothermal/isentropic divergence than the identical boost applied near ambient temperature — the effect is set by how warm the fluid runs relative to its own critical point, not by the absolute pressure level.

tango_core.components.well.numerical

Discretized (numerically-integrated) wellbore components for tango.

NumericalWell marches the wellbore state node-by-node: the wellbore is split into num_cells axial CELLS, bounded by num_cells + 1 axial NODES (node 0 = inlet, node num_cells = outlet), and pressure + enthalpy are integrated node-by-node with real CoolProp fluid-property lookups at each step. Cells and nodes are NOT the same count, and mixing them up is an easy mistake to make in this file: geometry/material fields that describe one CELL (cell_length, T_r — see _compute_derived's docstring) have num_cells entries; marched per-position quantities (P, h, T_f, rho, mu, u in _march, and the *_cells state/ history fields below despite their name) have num_cells + 1 entries.

Governing equations (per cell):

  • Pressure: P[i] = P[i-1] - upward_component·ρ·g·dz - ΔP_friction (Darcy-Weisbach)
  • Enthalpy: h[i] = h[i-1] - upward_component·g·dz - Q_loss / ṁ (Zhang 2011 heat-loss)

A single class covers injection, production, and (future) deviated wells, distinguished only by angle_from_vert_deg: 0° = straight down (injection), 180° = straight up (production), values in between describe a deviated well, 90° a horizontal one. upward_component = -cos(radians(angle)) (the vertical component of the unit flow direction, positive upward) so it matches the sign convention above exactly at the two endpoints (upward_component = -1 for straight-down injection, +1 for straight-up production) while interpolating smoothly in between — a horizontal well (90°) correctly gets zero elevation-dependent pressure/enthalpy change. Friction and heat-loss terms use the full cell_length (flow-path distance) unscaled by angle, since those depend on distance traveled, not vertical rise. NumericalInjectionWell/NumericalProductionWell below are thin subclasses that just set the angle_from_vert_deg default so existing YAML configs need no changes.

The rock temperature profile (T_r, built in _compute_derived) is projected onto true vertical depth via cos(angle_from_vert_deg) before thermal_gradient (K per vertical meter) is applied — so a horizontal section correctly sees roughly-constant rock temperature even though fluid keeps traveling along the flow path. cell_length (friction, heat-loss geometry) is deliberately not scaled this way, since those depend on distance traveled, not vertical rise. See _compute_derived's docstring for the full breakdown.

Default physics selections

FrictionModel.HAALAND, HeatTransferModel.ZHANG_2011.

See core/physics_models.py to add or select a different variant.

Dimensionless time: t_d advances by t_scaling_factor * step.dt once per committed step, so steps of any length move it by the real elapsed time; the injection-enthalpy loop's re-solves within a timestep restore it from the timestep-start snapshot (Component.snapshot_convergence_state).

History: each spatially-distributed quantity is one state variable whose value is a vector along the well axis; recorded as one entry per timestep. See save_interval on the base Component class.

Serialization: cell arrays are stored as list[float] so they serialize natively via Pydantic. The inner solve loop uses local numpy arrays for performance; results are converted to lists before storing in state.

TARGET_CELL_LENGTH_M = 250.0 module-attribute

Axial resolution (m) that NumericalWell.num_cells is derived from when not given explicitly, via ceil(well_length / TARGET_CELL_LENGTH_M / 10) * 10.

Holding cell_length (not num_cells) constant across wells of different lengths is the right invariant: discretization error is a function of cell_length, so a short well and a long well resolved to the SAME cell_length carry the same accuracy, whereas giving every well the same flat num_cells under-resolves long wells and over-resolves short ones.

250 m comes from a mesh-convergence sweep (see applications/demo_well_mesh_convergence/) that found num_cells=15 the smallest value keeping delivered production temperature within 0.1% relative error of a num_cells=100 baseline, on a 5000 m well -- rounded up to the nearest 10 (num_cells=20) gives 5000 / 20 = 250 m/cell. Rounding to the nearest 10 (rather than using the raw cell count) keeps num_cells values tidy across configs without meaningfully changing accuracy, since the error margin at 15 cells already has headroom under the 0.1% target.

DERIVED_FIELDS = ('relative_roughness', 'cross_sectional_area', 't_scaling_factor', 'T_r') module-attribute

NumericalWell fields computed by init() from its inputs. Not serialized; a config should leave them out (init() rejects a value that disagrees with the computed one).

NumericalWellState(h_inlet=_ls_nan(), T_inlet=_ls_nan(), P_inlet=_ls_nan(), mass_rate=_ls_nan(), t_d=_ls_zero(), P_cells=_ls_cells(), h_cells=_ls_cells(), T_cells=_ls_cells(), rho_cells=_ls_cells(), mu_cells=_ls_cells(), u_cells=_ls_cells(), h_outlet=_ls_nan(), T_outlet=_ls_nan(), P_outlet=_ls_nan(), pump_power_watts=_ls_zero()) dataclass

Bases: StateMethods

Full discretized simulation state for one numerical-well solve step.

All scalar fields are LockedState[float] and cell arrays are LockedState[list[float]], each writable exactly once per timestep. mark_all_stale() (inherited from StateMethods) is called by the orchestrator (via Component.mark_all_stale()) immediately before each solve().

The *_cells fields hold num_cells + 1 values — one per axial NODE, not one per cell (the name is inherited from src/tango_core; see module docstring's cells-vs-nodes note).

h_inlet = field(default_factory=_ls_nan) class-attribute instance-attribute

Specific enthalpy (J/kg) arriving on inlet -- the march's starting state.

T_inlet = field(default_factory=_ls_nan) class-attribute instance-attribute

Temperature (K) at the inlet, derived from (h_inlet, P_inlet).

P_inlet = field(default_factory=_ls_nan) class-attribute instance-attribute

Inlet pressure (Pa).

mass_rate = field(default_factory=_ls_nan) class-attribute instance-attribute

Mass flow rate through the well (kg/s).

t_d = field(default_factory=_ls_zero) class-attribute instance-attribute

Dimensionless time at the end of this solve step (see module docstring). Also read via get_stale() at the start of the NEXT solve() call to get the value carried over from the previous timestep — a genuine cross-timestep accumulator, same as LumpedReservoir.state.energy_extracted, which is exactly why it lives in state: a within-timestep re-solve (an injection-temperature convergence loop) restores the whole of state first, so this always advances from the last converged value, never from a discarded re-solve attempt.

P_cells = field(default_factory=_ls_cells) class-attribute instance-attribute

Pressure at each axial node (Pa).

h_cells = field(default_factory=_ls_cells) class-attribute instance-attribute

Specific enthalpy at each axial node (J/kg).

T_cells = field(default_factory=_ls_cells) class-attribute instance-attribute

Temperature at each axial node (K).

rho_cells = field(default_factory=_ls_cells) class-attribute instance-attribute

Fluid density at each axial node (kg/m3).

mu_cells = field(default_factory=_ls_cells) class-attribute instance-attribute

Fluid dynamic viscosity at each axial node (Pa s).

u_cells = field(default_factory=_ls_cells) class-attribute instance-attribute

Mean flow velocity at each axial node (m/s).

h_outlet = field(default_factory=_ls_nan) class-attribute instance-attribute

Specific enthalpy (J/kg) at the last node -- what outlet carries.

T_outlet = field(default_factory=_ls_nan) class-attribute instance-attribute

Outlet temperature (K).

P_outlet = field(default_factory=_ls_nan) class-attribute instance-attribute

Outlet pressure (Pa).

pump_power_watts = field(default_factory=_ls_zero) class-attribute instance-attribute

Pump shaft power (W). Non-zero only for pump-equipped well components.

NumericalWellHistory(h_inlet=list(), T_inlet=list(), P_inlet=list(), mass_rate=list(), t_d=list(), P_cells=list(), h_cells=list(), T_cells=list(), rho_cells=list(), mu_cells=list(), u_cells=list(), h_outlet=list(), T_outlet=list(), P_outlet=list(), pump_power_watts=list()) dataclass

Per-timestep history of spatially-distributed well state.

Shape: history.T_cells[timestep] is the full axial temperature list for that timestep — one entry per timestep, each entry holding num_cells + 1 node values (see NumericalWellState's docstring). One list field per NumericalWellState attribute (TANGO Commandment: every *State attribute must have an analog in its *History class).

T_inlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep inlet temperature (K).

P_inlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep inlet pressure (Pa).

mass_rate = field(default_factory=list) class-attribute instance-attribute

Per-timestep mass flow rate through the well (kg/s).

t_d = field(default_factory=list) class-attribute instance-attribute

Per-timestep dimensionless time at the end of the timestep.

P_cells = field(default_factory=list) class-attribute instance-attribute

Per-timestep list of the pressure at each axial node (Pa).

h_cells = field(default_factory=list) class-attribute instance-attribute

Per-timestep list of the specific enthalpy at each axial node (J/kg).

T_cells = field(default_factory=list) class-attribute instance-attribute

Per-timestep list of the temperature at each axial node (K).

rho_cells = field(default_factory=list) class-attribute instance-attribute

Per-timestep list of the fluid density at each axial node (kg/m3).

mu_cells = field(default_factory=list) class-attribute instance-attribute

Per-timestep list of the fluid dynamic viscosity at each axial node (Pa s).

u_cells = field(default_factory=list) class-attribute instance-attribute

Per-timestep list of the mean flow velocity at each axial node (m/s).

h_outlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep outlet specific enthalpy (J/kg).

T_outlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep outlet temperature (K).

P_outlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep outlet pressure (Pa).

pump_power_watts = field(default_factory=list) class-attribute instance-attribute

Pump shaft power per timestep (W). Zero for non-pump components.

record(state)

Append a copy of state as one timestep entry.

WellLengthSideEffect

Bases: StrEnum

Which linked quantity absorbs a well_length change -- see set_well_length.

KEEP_CELL_LENGTH = 'keep-cell-length' class-attribute instance-attribute

Keep the resolution: num_cells follows the new length.

KEEP_NUM_CELLS = 'keep-num-cells' class-attribute instance-attribute

Keep the cell count: cell_length follows the new length.

NumericalWell

Bases: WellComponent

Discretized wellbore: one marching scheme for injection, production, and (future) deviated/horizontal wells.

See module docstring for governing equations, the angle_from_vert_deg convention, and the T_r deviated-well caveat.

angle_from_vert_deg = Field(default=0.0, frozen=True) class-attribute instance-attribute

0 = straight down (injection), 180 = straight up (production), 90 = horizontal. Values in between describe a deviated well.

common = Field(frozen=True) class-attribute instance-attribute

Shared fluid/rock parameters — a reference to the SAME Common instance every other component in the Workflow holds (Pydantic does not copy nested model fields on construction), not an independent copy. Common itself is frozen, so there is exactly one place these values can come from and no way for this well to silently diverge from the reservoir or any other well. See core/specs.py.

num_cells = Field(frozen=True) class-attribute instance-attribute

Axial discretization cell count. well_length, num_cells and cell_length are linked (well_length = num_cells * cell_length); a config may give num_cells, cell_length, both (they must agree) or neither (num_cells then defaults to TARGET_CELL_LENGTH_M per cell, rounded up to the nearest 10 -- see that constant's docstring). Resolved by the _resolve_discretization validator below. To change well_length in a config dict, use set_well_length, which makes the caller choose which of the other two absorbs the change.

discretization_given = Field(default=(), frozen=True, exclude=True) class-attribute instance-attribute

Which of num_cells/cell_length the config itself gave (set by _resolve_discretization). Serialization writes only those, so a to_dict() copy re-derives a default cell count from its own well_length rather than pinning the original one.

cell_length = Field(frozen=True) class-attribute instance-attribute

Flow-path length per cell (m), exactly well_length / num_cells. Given alone in a config, it is a target: num_cells becomes the smallest count whose cells are no longer than it, and this field is then set to the exact resulting length. Used for friction and heat-loss geometry, deliberately not scaled by angle, since those depend on distance traveled.

wellhead_depth = Field(default=0.0, frozen=True) class-attribute instance-attribute

True vertical depth (m) of the well's shallow end, whichever way the fluid flows: the top of an injection or production well (0 for a well that reaches the surface; the bottom of the upper segment for the lower segment of a split production well), or the depth of a horizontal well. The rock temperature at each cell (T_r) is measured from here.

gravity_scale_factor = Field(default=1.0, frozen=True) class-attribute instance-attribute

Multiplier on gravity in the march's pressure and enthalpy steps (dimensionless); 1.0 is real gravity.

friction_model = Field(default=FrictionModel.HAALAND, frozen=True) class-attribute instance-attribute

Friction-factor correlation for the pressure loss.

heat_transfer_model = Field(default=HeatTransferModel.ZHANG_2011, frozen=True) class-attribute instance-attribute

Correlation for heat exchange between the fluid and the surrounding rock.

relative_roughness = Field(default=0.0, exclude=True) class-attribute instance-attribute

Pipe roughness divided by diameter (dimensionless).

cross_sectional_area = Field(default=0.0, exclude=True) class-attribute instance-attribute

Flow cross-section of the well (m2).

t_scaling_factor = Field(default=0.0, exclude=True) class-attribute instance-attribute

Factor 4 k / (rho c d^2) that converts elapsed time to dimensionless time t_d (1/s).

T_r = Field(default_factory=list, exclude=True) class-attribute instance-attribute

Rock temperature profile along well axis (K), one value per cell.

state = Field(default_factory=NumericalWellState) class-attribute instance-attribute

Well state of the current solve; an orchestrator that re-solves within a timestep restores it first.

history = Field(default_factory=NumericalWellHistory) class-attribute instance-attribute

Per-timestep record of the well state.

init()

Pre-compute geometry constants from validated input fields.

Raises:

Type Description
ConfigError

The config supplied a derived value (see DERIVED_FIELDS) that disagrees with what this well's inputs give. Remove it (expunge_derived_fields) so it is recomputed.

solve(inlet, step)

March the discretized wellbore from inlet to outlet conditions.

NumericalInjectionWell

Bases: NumericalWell

Discretized injection wellbore: surface → reservoir bottom.

Thin NumericalWell subclass — only sets the angle_from_vert_deg default (straight down). See module docstring for the shared marching scheme.

angle_from_vert_deg = 0.0 class-attribute instance-attribute

Well angle from vertical (degrees); 0, straight down, for injection.

NumericalProductionWell

Bases: NumericalWell

Discretized production wellbore: reservoir bottom → surface.

Thin NumericalWell subclass — only sets the angle_from_vert_deg default (straight up). See module docstring for the shared marching scheme.

The hot brine enters at the bottom (cell 0, reservoir pressure/temperature) and exits at the top (cell n-1, lower P and slightly lower T due to Zhang heat-loss to the cooler rock above).

angle_from_vert_deg = 180.0 class-attribute instance-attribute

Well angle from vertical (degrees); 180, straight up, for production.

NumericalProductionWellWithPump

Bases: NumericalProductionWell

Upper production wellbore with numerical heat loss and an optional pump.

Inherits the full Zhang 2011 marching heat-loss model from NumericalProductionWell. After the wellbore solve, a pump boost is applied to P_outlet if target_extraction_pressure exceeds the wellbore outlet pressure.

Use this for the upper production well segment in a split (lower/upper) production wellbore configuration. Assumptions: - All of the pump's losses heat the produced fluid. The actual enthalpy rise is the isentropic rise divided by pump_efficiency, and the pump's electricity draw is mass_rate times that same rise. This is right for losses in the pump and its fluid-cooled downhole motor. It is not quite right when pump_efficiency is an overall pump-string figure that also covers surface equipment (cable, transformer, frequency converter), whose losses heat the surroundings rather than the fluid: the electricity draw is still correct, but the discharge enthalpy is slightly overstated (about 1 kJ/kg for a 50 bar boost of hot brine at an overall efficiency of 0.55).

pump_efficiency = 1.0 class-attribute instance-attribute

Pump efficiency (dimensionless): the isentropic enthalpy rise divided by the actual one, which is also the electricity drawn per unit mass. Defaults to 1.0 (ideal pump). The templates use 0.55, the overall electric submersible pump (ESP) string efficiency of van 't Spijker & Ungemach (2016) (see docs/SOURCES.md#vantspijker2016): pump 70% × motor 90% × cable 97% × transformer 99% × frequency converter 94%. The overall figure is used, not the 70% pump-only one, because downhole pump power is billed as electricity drawn at the surface. See the class's Assumptions section for what this means for the fluid's enthalpy, and solve()'s docstring for the pump model this scales.

target_extraction_pressure = 0.0 class-attribute instance-attribute

Target outlet pressure after pump boost (Pa). 0 = no active pump. Sourced from sim_config.target_extraction_pressure — the SAME single value SurfaceComponent uses, threaded in by _build_components (see that field's docstring in core/specs.py for the duplicated-value bug this replaced).

solve(inlet, step)

March wellbore heat loss, then apply a pump boost if needed.

If the natural (un-boosted) march already reaches target_extraction_pressure, this is identical to NumericalWell.solve(). Otherwise, the pump-discharge pressure is found by ITERATING (Secant method) rather than tacking a closed-form correction onto the already-completed natural march: this segment's own friction/gravity loss depends on fluid density, which in turn depends on the (boosted) pressure profile — a genuine fixed-point problem. Concretely: guess a discharge pressure at the pump, re-run the ENTIRE march (_march()) from that boosted starting state, compare the resulting outlet pressure to the target, and refine — because the density used for friction/heat-loss over the whole segment must reflect the boosted pressure, not the natural (lower-pressure) one a pump sitting anywhere below the very last cell would actually see.

Pump work uses a standard isentropic-efficiency model — entropy at the true inlet state, isentropic enthalpy at the candidate discharge pressure, efficiency-derated to the actual enthalpy rise, then handed to the march as enthalpy directly — rather than assuming the compression is perfectly isothermal. The gap between an isothermal and an isentropic-efficiency result is driven by TEMPERATURE, not pressure level or the size of the pressure rise: dH|_S - dH|_T = T*alpha*V*dP, where alpha is the fluid's thermal expansion coefficient. Because alpha grows as temperature rises toward the fluid's own critical point, the same pressure boost applied at a higher temperature produces a larger isothermal/isentropic divergence than the identical boost applied near ambient temperature — the effect is set by how warm the fluid runs relative to its own critical point, not by the absolute pressure level.

default_num_cells(well_length)

num_cells for a well whose config gives neither num_cells nor cell_length.

expunge_derived_fields(well_cfg)

Remove DERIVED_FIELDS from a well's config dict so init() recomputes them.

Workflow.to_dict() doesn't write them, so this only matters for a config dict that was given them explicitly.

set_well_length(well_cfg, well_length, side_effect)

Set well_length in a NumericalWell config dict, keeping its discretization consistent.

well_length, num_cells and cell_length are linked, so changing the length means one of the other two must change too; side_effect says which. A config that gives neither keeps giving neither (the default resolution applies to the new length). Also removes the derived fields (expunge_derived_fields).

tango_core.components.reservoir.base

Abstract base for reservoir components in tango.

ReservoirComponent

Bases: FlowComponent

Abstract base for all reservoir components.

External simulators (CMG, MOOSE) are meant to implement this interface as adapters; none exists yet, so LumpedReservoir is the only implementation. The native implementation assumes incompressible 1D Darcy flow; external simulators may relax this assumption during transients.

prev = Field(frozen=True) class-attribute instance-attribute

Circuit index of the upstream component.

next = Field(frozen=True) class-attribute instance-attribute

Circuit index of the downstream component.

reservoir_depth = Field(frozen=True) class-attribute instance-attribute

Depth of the reservoir mid-point (m).

thickness = Field(frozen=True) class-attribute instance-attribute

Reservoir thickness (m).

permeability = Field(frozen=True) class-attribute instance-attribute

Reservoir permeability (m²).

porosity = Field(frozen=True) class-attribute instance-attribute

Reservoir porosity (dimensionless).

hydro_static_pressure = Field(frozen=True) class-attribute instance-attribute

Hydrostatic pressure at reservoir depth (Pa), used only for the fracking-safety ceiling. Derived from the config as brine_density × gravity × reservoir_depth (see tango_core.workflows.linked_quantities), so it's the same pressure the reservoir starts at; a config value that disagrees raises ConfigError. For another in-situ density, set brine_density and leave this out.

over_pressure_percentage = Field(frozen=True) class-attribute instance-attribute

Over-pressure as a percentage of hydrostatic pressure (%). Combines with hydro_static_pressure for the fracking-safety ceiling only.

brine_density = Field(default=1000.0, frozen=True) class-attribute instance-attribute

Brine density (kg/m³). Sets both the reservoir's initial/undepleted pressure and hydro_static_pressure, each brine_density × g × reservoir_depth.

gravity = Field(default=GRAVITY, frozen=True) class-attribute instance-attribute

Gravitational acceleration (m/s²) — defaults to core/constants.py's GRAVITY, overridable per reservoir since gravity varies regionally.

solve(inlet, step) abstractmethod

Compute and return the reservoir outlet state from the injection inlet state.

tango_core.components.reservoir.lumped

Lumped-parameter reservoir component for tango.

LumpedReservoir models the subsurface as a single pressure-drop element using a doublet radial-flow impedance formula and tracks thermal depletion via a cumulative-energy model. See References below for both.

Pressure model (doublet impedance): Z = μ · [ln(L / (e · D)) + D / L] / (ρ · k · b_eff · π) ΔP = ṁ · Z

Temperature model (thermal depletion): E += ṁ · (h_out − h_in) · Δt (cumulative energy extracted) ψ = E / (V_rock · ρ_rock · Cp_rock · (T₀ − T_inj)) γ = depletion_curve(ψ, p1, p2, p3) (Adams 2015 fitting function) T_outlet = T_inj + γ · (T₀ − T_inj)

where T₀ = initial reservoir temperature, T_inj = current injection temperature.

References

Doublet impedance: Adams & Schädle (2020), genGEO; see docs/SOURCES.md#adams2020gengeo. Thermal depletion (cumulative-energy / γ(ψ) fitting function): Adams et al. (2015); see docs/SOURCES.md#adams2015.

LumpedReservoirState(T_inlet=_ls(), P_inlet=_ls(), mass_rate=_ls(), T_reservoir_initial=_ls(), P_reservoir=_ls(), rho=_ls(), mu=_ls(), impedance=_ls(), delta_p_darcy=_ls(), h_inlet=_ls(), h_outlet=_ls(), psi=_ls(), gamma=_ls(), T_outlet=_ls(), P_outlet=_ls(), p1=_ls(), p2=_ls(), p3=_ls(), energy_extraction_rate=_ls(), energy_extracted=(lambda: _ls(0.0))(), ever_solved=(lambda: _locked(value=False))()) dataclass

Bases: StateMethods

Full simulation state for one reservoir solve step.

All fields are LockedState[float] so each is writable exactly once per timestep. mark_all_stale() (inherited from StateMethods) is called by the orchestrator (via Component.mark_all_stale()) immediately before each solve(). T_outlet and P_outlet start stale with NaN; use is_stale() rather than math.isnan() to detect "not yet solved" on the first call.

T_inlet = field(default_factory=_ls) class-attribute instance-attribute

Inlet temperature from the injection well (K).

P_inlet = field(default_factory=_ls) class-attribute instance-attribute

Inlet pressure from the injection well (Pa).

mass_rate = field(default_factory=_ls) class-attribute instance-attribute

Mass flow rate through the reservoir (kg/s).

T_reservoir_initial = field(default_factory=_ls) class-attribute instance-attribute

Un-depleted geothermal temperature at reservoir depth (K).

P_reservoir = field(default_factory=_ls) class-attribute instance-attribute

Un-depleted reservoir pressure (Pa) — see LumpedReservoir.P_initial.

rho = field(default_factory=_ls) class-attribute instance-attribute

Fluid density, averaged between inlet and previous outlet (kg/m3).

mu = field(default_factory=_ls) class-attribute instance-attribute

Fluid dynamic viscosity, averaged between inlet and previous outlet (Pa s).

impedance = field(default_factory=_ls) class-attribute instance-attribute

Doublet radial-flow impedance Z (Pa·s/kg). ΔP = ṁ·Z.

delta_p_darcy = field(default_factory=_ls) class-attribute instance-attribute

Darcy pressure drop across the reservoir, mass_rate times impedance (Pa); P_outlet = P_inlet - delta_p_darcy.

h_inlet = field(default_factory=_ls) class-attribute instance-attribute

Specific enthalpy at inlet (J/kg).

h_outlet = field(default_factory=_ls) class-attribute instance-attribute

Specific enthalpy at outlet (J/kg) — computed at T_outlet, P_outlet.

psi = field(default_factory=_ls) class-attribute instance-attribute

Fractional energy extraction ψ = E_extracted / E_reservoir.

gamma = field(default_factory=_ls) class-attribute instance-attribute

Depletion factor γ ∈ [0, 1]. T_outlet = T_inj + γ·(T₀ − T_inj).

T_outlet = field(default_factory=_ls) class-attribute instance-attribute

Outlet temperature

P_outlet = field(default_factory=_ls) class-attribute instance-attribute

Outlet pressure

p1 = field(default_factory=_ls) class-attribute instance-attribute

Adams 2015 depletion curve coefficient p1 — recomputed every solve() call from the current fluid properties (see _recompute_depletion_coeffs).

p2 = field(default_factory=_ls) class-attribute instance-attribute

Adams 2015 depletion curve coefficient p2.

p3 = field(default_factory=_ls) class-attribute instance-attribute

Adams 2015 depletion curve coefficient p3.

energy_extraction_rate = field(default_factory=_ls) class-attribute instance-attribute

Instantaneous thermal power extracted from the reservoir this solve (W) — mdot * (h_prod_prev - h_in). Written by solve() before calling set_cumulative(), which reads it back to increment energy_extracted: the rate is a fresh, ordinary state field; only the accumulation step is special.

energy_extracted = field(default_factory=lambda: _ls(0.0)) class-attribute instance-attribute

Cumulative thermal energy extracted from the reservoir (J), across all timesteps so far. Updated via set_cumulative() (see below), not update() — it's a running total, not a value recomputed from scratch each timestep. Genuinely depends on its own value from the previous converged timestep, which is exactly why it lives in state: a within-timestep re-solve (an injection-temperature convergence loop) restores the whole of state first, so this always increments from the last converged value, never from a discarded re-solve attempt.

ever_solved = field(default_factory=lambda: _locked(value=False)) class-attribute instance-attribute

Whether solve() has ever completed for this component instance.

solve() needs to know whether T_outlet/P_outlet hold a real previous-timestep value or are still at their unsolved NaN default. Read via the normal get_stale() (before this call) / update() (for the next call) cycle — not via is_stale()/is_fresh() directly, which would break across a Workflow.to_dict() → mutate → Workflow(cfg) sweep-point reconstruction (LockedState's Pydantic validator always starts a reconstructed instance fresh — see LockedState.__get_pydantic_core_schema__'s docstring — so the status can't be trusted as the signal post-reconstruction). The value round-trips correctly regardless of status, so reading it the same way every other LockedState field is read sidesteps the problem entirely.

set_cumulative(dt)

Increment energy_extracted from energy_extraction_rate * dt.

No automatic derivation exists for this — every accumulator is hand-written physics — this is tango's one leaf implementation, called from solve() right where the inline energy_extracted.increment(...) call used to be.

Parameters:

Name Type Description Default
dt float

Length of the step being accumulated over (s).

required

reset_cumulative()

Reset energy_extracted to zero (e.g. re-running from t=0 without reconstructing).

LumpedReservoirHistory(T_inlet=list(), T_outlet=list(), P_inlet=list(), P_outlet=list(), mass_rate=list(), T_reservoir_initial=list(), P_reservoir=list(), rho=list(), mu=list(), impedance=list(), delta_p_darcy=list(), h_inlet=list(), h_outlet=list(), psi=list(), gamma=list(), p1=list(), p2=list(), p3=list(), energy_extraction_rate=list(), energy_extracted=list(), ever_solved=list()) dataclass

Per-timestep history of lumped reservoir scalar state.

One list field per LumpedReservoirState attribute (TANGO Commandment: every *State attribute must have an analog in its *History class) — see record().

T_inlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep inlet temperature (K).

T_outlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep outlet temperature (K).

P_inlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep inlet pressure (Pa).

P_outlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep outlet pressure (Pa).

mass_rate = field(default_factory=list) class-attribute instance-attribute

Per-timestep mass flow rate (kg/s).

T_reservoir_initial = field(default_factory=list) class-attribute instance-attribute

Per-timestep un-depleted reservoir temperature (K).

P_reservoir = field(default_factory=list) class-attribute instance-attribute

Per-timestep un-depleted reservoir pressure (Pa).

rho = field(default_factory=list) class-attribute instance-attribute

Per-timestep averaged fluid density (kg/m3).

mu = field(default_factory=list) class-attribute instance-attribute

Per-timestep averaged fluid dynamic viscosity (Pa s).

impedance = field(default_factory=list) class-attribute instance-attribute

Per-timestep reservoir impedance (Pa s/kg).

delta_p_darcy = field(default_factory=list) class-attribute instance-attribute

Per-timestep Darcy pressure drop across the reservoir (Pa).

h_inlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep inlet specific enthalpy (J/kg).

h_outlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep outlet specific enthalpy (J/kg).

psi = field(default_factory=list) class-attribute instance-attribute

Per-timestep fractional energy extraction psi (dimensionless).

gamma = field(default_factory=list) class-attribute instance-attribute

Per-timestep depletion factor gamma, between 0 and 1.

p1 = field(default_factory=list) class-attribute instance-attribute

Per-timestep depletion curve coefficient p1.

p2 = field(default_factory=list) class-attribute instance-attribute

Per-timestep depletion curve coefficient p2.

p3 = field(default_factory=list) class-attribute instance-attribute

Per-timestep depletion curve coefficient p3.

energy_extraction_rate = field(default_factory=list) class-attribute instance-attribute

Per-timestep thermal power extracted from the reservoir (W).

energy_extracted = field(default_factory=list) class-attribute instance-attribute

Per-timestep cumulative thermal energy extracted (J).

ever_solved = field(default_factory=list) class-attribute instance-attribute

Per-timestep copy of state.ever_solved; always True, since solve() sets it before the timestep is recorded.

record(state)

Append one timestep snapshot.

LumpedReservoir

Bases: ReservoirComponent

0-D lumped reservoir: doublet radial-flow impedance + Adams 2015 thermal depletion.

Implements the DOUBLET well pattern.

common = Field(frozen=True) class-attribute instance-attribute

Shared fluid/rock parameters — a reference to the SAME Common instance every other component in the Workflow holds, not an independent copy. See core/specs.py.

well_spacing = Field(default=707.0, frozen=True) class-attribute instance-attribute

Injector-to-producer horizontal distance (m) — from layout: block.

well_eff_diameter = Field(default=0.41, frozen=True) class-attribute instance-attribute

Effective well diameter for the impedance calculation (m): the mean of the injection and production well diameters. Derived from the config (see tango_core.workflows.linked_quantities); a config value that disagrees raises ConfigError.

well_pattern = Field(frozen=True) class-attribute instance-attribute

Well pattern for analytic impedance solution — threaded from Layout.well_pattern (already validated/coerced there) via _build_components's layout_extras mechanism.

wp = Field(default=WellPattern.Doublet, exclude=True) class-attribute instance-attribute

Resolved well_pattern object

net_to_gross_ratio = Field(default=1.0, frozen=True) class-attribute instance-attribute

Net-to-gross ratio for effective reservoir thickness (dimensionless).

T_initial = Field(default=0.0, exclude=True) class-attribute instance-attribute

Un-depleted reservoir temperature = surface_T + gradient × depth (K).

P_initial = Field(default=0.0, exclude=True) class-attribute instance-attribute

Un-depleted reservoir pressure = brine_density × g × reservoir_depth (Pa). Distinct from the fracking-safety ceiling (hydro_static_pressure × (1 + over_pressure_percentage/100)).

rock_volume = Field(default=0.0, exclude=True) class-attribute instance-attribute

Rock (non-fluid) volume = thickness × area × (1 − porosity) (m³).

rock_C_v = Field(default=0.0, exclude=True) class-attribute instance-attribute

Volumetric heat capacity of rock = rock_density × rock_cp (J/(m³·K)).

state = Field(default_factory=LumpedReservoirState) class-attribute instance-attribute

Reservoir state of the current solve; an orchestrator that re-solves within a timestep restores it first.

history = Field(default_factory=LumpedReservoirHistory) class-attribute instance-attribute

Per-timestep record of the reservoir state.

init()

Pre-compute geometry and depletion coefficients from validated fields.

solve(inlet, step)

Compute reservoir outlet (T, P) from doublet impedance and thermal depletion.

tango_core.components.reservoir.wellpattern_impedance

Explicit solution for Isolated Doublet, Five Spot and Inverted Five Spot well patterns

WellPattern

Bases: StrEnum

Well pattern geometries with closed-form hydraulic impedance solutions.

Each member represents a fixed well pattern layout (Doublet, Five Spot, Inverted Five Spot). Members may be looked up by their string value or name.

Example: WellPattern("DOUBLET"), WellPattern("doublet"), and WellPattern("Doublet") (member name) all resolve to the same member — lookup is case-insensitive via _missing_ below.

.. warning:: Configs using FiveSpot or InvertedFiveSpot are invalid for now (GitHub issue #109). Only the reservoir impedance below knows about the pattern. The economics cost them as a single doublet (one injection and one production well, one well_spacing of surface pipe), and the single modeled injection or production well carries the full mass rate instead of its per-well share. The member docstrings' layouts (which wells sit at the corners) also disagree with the pre-1.0 cost model's; #109 tracks settling which is right.

Doublet = 'DOUBLET' class-attribute instance-attribute

Doublet Well Pattern: one injection well, one prodcution well

x: injection, o: production

x - - - - - o

well_spacing in config.yml file is the distance between the injection production pair

FiveSpot = '5SPOT' class-attribute instance-attribute

Five Spot Well Pattern: four production wells, one injection well

x: injection, o:production

o - - - - - o | | - x - | | o - - - - - o

well_spacing in config.yml file is the distance between an injection production pair

InvertedFiveSpot = 'INVERTED_5SPOT' class-attribute instance-attribute

Inverted Five Spot Well Pattern: four injection wells, one production well

x: injection, o:production

x - - - - - x | | - o - | | x - - - - - x

well_spacing in config.yml file is the distance between an injection production pair

AGSDoublet = 'AGS_DOUBLET' class-attribute instance-attribute

Injection and production pair in an AGS system, does not have an impedance function implemented yet

has_impedance_formula()

Function to allow validation of well pattern by checking if it is implemented before running starting to run the similuation. The impedance functions are defined in self.impedance()

impedance(mu, rho, permeability, thickness, net_to_gross_ratio, well_spacing, well_eff_diameter)

Compute the hydraulic (flow) impedance for this well pattern.

Implements the closed-form impedance solutions for Doublet, Five Spot, and Inverted Five Spot patterns based on Birdsell et al. (2024) -- see this class's own References section below.

Parameters:

Name Type Description Default
mu float

Dynamic viscosity of the reservoir fluid (Pa·s).

required
rho float

Density of the reservoir fluid (kg/m³).

required
permeability float

Reservoir rock permeability (m²).

required
thickness float

Gross reservoir thickness (m).

required
net_to_gross_ratio float

Net-to-gross ratio for effective reservoir thickness (dimensionless).

required
well_spacing float

Injector-to-producer horizontal distance, L (m).

required
well_eff_diameter float

Effective well diameter used in the impedance calculation, D (m).

required

Returns:

Type Description
float

Flow impedance Z, relating mass flow rate to pressure drop

float

(Pa·s/kg).

Raises:

Type Description
NotImplementedError

If this member has no impedance formula defined yet.

References

Birdsell et al. (2024); see docs/SOURCES.md#birdsell2024.

tango_core.components.surface.base

Abstract base for surface / power-plant components in tango.

SurfaceComponent

Bases: FlowComponent

Abstract base for surface / power-plant components.

The surface component is always at component_idx=0 (the BC checkpoint). Its injection_pressure field provides the initial guess to SystemBCIteration. Concrete implementation: GraphSurface, which builds its TESPy network from a YAML power_plant.nodes/edges block rather than hardcoding a fixed topology — see components/surface/graph.py for the single-flash, direct-heat, or any other plant design.

prev = Field(frozen=True) class-attribute instance-attribute

Circuit index of the upstream component.

next = Field(frozen=True) class-attribute instance-attribute

Circuit index of the downstream component.

common = Field(frozen=True) class-attribute instance-attribute

Shared fluid/rock parameters — a reference to the SAME Common instance every other component in the Workflow holds, not an independent copy. Provides surface_temperature/surface_pressure (ambient BC state). See core/specs.py.

injection_pressure instance-attribute

Injection wellhead pressure (Pa): the pressure the plant delivers at its outlet.

Fixed for the whole run, except when a grouped_subsurface is the circuit entry: that loop solves for the injection pressure it needs, and SystemBCIteration sets it here every pass (set_injection_pressure), so the configured value is only the first timestep's starting guess and .results.yml holds the last timestep's solved value. Not frozen, unlike the other fields here, for that reason, and because tests and tools set it directly on a built component (see Component's class docstring).

pipe_diameter = Field(frozen=True) class-attribute instance-attribute

Surface pipe inner diameter (m).

pipe_roughness = Field(frozen=True) class-attribute instance-attribute

Absolute pipe wall roughness (m).

approach_temperature = Field(frozen=True) class-attribute instance-attribute

Heat exchanger approach temperature (K).

Residual gap between the cooled fluid's final temperature and the ambient temperature into which heat is being rejected.

target_extraction_pressure = Field(frozen=True) class-attribute instance-attribute

Minimum required extraction pressure at the surface inlet (Pa). Sourced from sim_config.target_extraction_pressure — the SINGLE shared source, threaded in by _build_components (see that field's docstring in core/specs.py). Any pump-bearing production well in the same Workflow declares a field of this exact same name and receives the identical value the same way — do not set this directly in a component's own YAML block (_build_components now rejects that explicitly).

set_injection_pressure(P)

Set the injection wellhead pressure (Pa) the plant delivers on its next solve.

get_injection_pressure()

Return the injection wellhead pressure (Pa) the plant delivers.

solve(inlet, step) abstractmethod

Compute power plant outputs, and compute and return the reinjection state from the production inlet.

tango_core.components.surface.graph

Generic, YAML-graph-driven surface / power-plant component for tango.

GraphSurface builds its TESPy network entirely from a power_plant.nodes/power_plant.edges block in the YAML, rather than hardcoding a fixed topology in Python. One class covers single-flash, AGS direct-heat, and any future topology; adding a new plant design is a YAML change, not a new Python class.

Required naming convention (the one piece that can't be pure YAML — this is wiring to the rest of the simulation, not plant layout, so it has to be an explicit, documented contract rather than inferred from graph shape):

  • Exactly one Source node named "inlet" — solve() writes T/p/m/fluid onto its outgoing connection from its inlet parameter each timestep.
  • Exactly one Sink node named "outlet" — solve() forces its incoming connection's pressure to self.injection_pressure (the BC variable SystemBCIteration iterates), and reads self.outlet back off it after solving.
  • Any node contributing to the plant's net output tags itself with role: net_electric or role: net_thermal (see ComponentRole in core/policies.py). Untagged nodes (valves, separators, condensers, mixers) are solved as part of the network but not summed into either total.

Sign convention for role aggregation (no per-component-type branch needed): TESPy's P.val/Q.val are positive when power/heat flows into the fluid and negative when it flows out. Summing -P.val over every net_electric node therefore adds turbines (negative P → positive contribution) and subtracts compressors/pumps (positive P → negative contribution) uniformly; summing -Q.val over net_thermal nodes gives positive delivered heat for a heat exchanger rejecting heat to a district-heating loop.

type: PumpOrValve (in addition to the real TESPy component types) is a per-node opt-in for a circulation point whose physically correct resolution (a passive Valve, or a real Compressor) depends on design-point conditions rather than being knowable up front -- see init()/_NetworkBundle/_check_pump_or_valve_validity. It builds and holds TWO full networks, tries the Valve-resolved one first each solve(), and falls back to the Compressor-resolved one if that's physically invalid for the current timestep -- see docs/archive/bugs-fixed-in-tango.md's "AGS closed loop has no pump anywhere" entry for the physical motivation.

Example YAML (AGS direct-heat — the topology that motivated this class):

surface:
  type: 'graph'
  power_plant:
    nodes:
      inlet: {type: Source}
      district_heating_hx: {type: SimpleHeatExchanger, role: net_thermal, T_out: 323.15, pressure_ratio: 0.99}
      circulation_control: {type: PumpOrValve, role: net_electric, efficiency: 1.0}
      outlet: {type: Sink}
    edges:
      1: {source: inlet, target: district_heating_hx}
      2: {source: district_heating_hx, target: circulation_control}
      3: {source: circulation_control, target: outlet}

Unit conventions (TESPy network created with p_unit="bar", T_unit="C"):

  • YAML pressures in Pa -> bar via x 1e-5; p_out_megapascals -> bar via x 10
  • Temperatures: K -> degC for TESPy input, TESPy degC -> K for output
  • Power: TESPy node .P.val/.Q.val in W (SI), regardless of the h_unit="kJ/kg" display setting

GraphSurfaceState(h_inlet=_ls(), T_inlet=_ls(), P_inlet=_ls(), mass_rate=_ls(), dP_pipe=_ls(), P_tespy_inlet=_ls(), net_power_W=_ls(), net_thermal_W=_ls(), h_outlet=_ls(), T_outlet=_ls(), P_outlet=_ls(), rho=_ls(), mu=_ls(), node_detail=_ls_dict()) dataclass

Bases: StateMethods

Full simulation state for one graph-surface solve step.

Every field is LockedState-wrapped — writable exactly once per timestep, LockedState[float] for scalars and LockedState[dict[str, dict[str, float]]] for node_detail. mark_all_stale() (inherited from StateMethods) is called by the orchestrator (via Component.mark_all_stale()) immediately before each solve().

h_inlet = field(default_factory=_ls) class-attribute instance-attribute

Specific enthalpy (J/kg) arriving on inlet; set on TESPy's inlet connection as-is.

T_inlet = field(default_factory=_ls) class-attribute instance-attribute

Inlet temperature from the production well (K), derived from (h_inlet, P_inlet).

P_inlet = field(default_factory=_ls) class-attribute instance-attribute

Inlet pressure from the production well, before the surface pipe (Pa).

mass_rate = field(default_factory=_ls) class-attribute instance-attribute

Mass flow rate through the plant (kg/s).

dP_pipe = field(default_factory=_ls) class-attribute instance-attribute

Friction pressure drop across the surface pipe (Pa).

P_tespy_inlet = field(default_factory=_ls) class-attribute instance-attribute

Pressure passed to TESPy inlet = P_inlet - dP_pipe (Pa).

net_power_W = field(default_factory=_ls) class-attribute instance-attribute

Sum of -P.val (W) over role=net_electric nodes. 0 if none tagged.

net_thermal_W = field(default_factory=_ls) class-attribute instance-attribute

Sum of -Q.val (W) over role=net_thermal nodes. 0 if none tagged.

h_outlet = field(default_factory=_ls) class-attribute instance-attribute

Specific enthalpy (J/kg) on TESPy's outlet connection -- what outlet carries.

T_outlet = field(default_factory=_ls) class-attribute instance-attribute

Outlet temperature returned to the injection well (K).

P_outlet = field(default_factory=_ls) class-attribute instance-attribute

Outlet pressure returned to the injection well (Pa).

rho = field(default_factory=_ls) class-attribute instance-attribute

Fluid density at the outlet (kg/m3).

mu = field(default_factory=_ls) class-attribute instance-attribute

Fluid dynamic viscosity at the outlet (Pa s).

node_detail = field(default_factory=_ls_dict) class-attribute instance-attribute

Per-node diagnostic snapshot, keyed by node name then quantity (P/Q in W where the component has them, T/p/m in SI units off that node's outgoing connection where one exists). Rebuilt fresh every solve() via whole-value update() (there's no write-once concern to protect since it's fully recomputed, not accumulated, but it's still LockedState-wrapped like every other field here for uniformity — see mark_all_stale()). {} if record_node_detail=False on the component. This is a generic replacement for hardcoded per-component named fields — works for any topology, at the cost of dict-key access instead of attribute access.

GraphSurfaceHistory(h_inlet=list(), h_outlet=list(), T_inlet=list(), T_outlet=list(), P_inlet=list(), P_outlet=list(), mass_rate=list(), dP_pipe=list(), P_tespy_inlet=list(), rho=list(), mu=list(), net_power_W=list(), net_thermal_W=list(), node_history=dict()) dataclass

Per-timestep history of graph-surface scalar and per-node state.

One list field per GraphSurfaceState attribute (TANGO Commandment: every *State attribute must have an analog in its *History class) — see record(). node_detail is the one field whose analog is NOT a same-named, same-shaped list: it's a dict[node][quantity] -> value snapshot, so its time-series analog is node_history (dict[node][quantity] -> list[value], transposed by node/quantity rather than by timestep) — a flat node_detail: list[dict] would just duplicate node_history in a clumsier shape.

T_inlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep inlet temperature (K).

T_outlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep outlet temperature (K).

P_inlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep inlet pressure (Pa).

P_outlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep outlet pressure (Pa).

mass_rate = field(default_factory=list) class-attribute instance-attribute

Per-timestep mass flow rate (kg/s).

dP_pipe = field(default_factory=list) class-attribute instance-attribute

Per-timestep friction pressure drop across the surface pipe (Pa).

P_tespy_inlet = field(default_factory=list) class-attribute instance-attribute

Per-timestep pressure passed to the TESPy inlet (Pa).

rho = field(default_factory=list) class-attribute instance-attribute

Per-timestep fluid density at the outlet (kg/m3).

mu = field(default_factory=list) class-attribute instance-attribute

Per-timestep fluid dynamic viscosity at the outlet (Pa s).

net_power_W = field(default_factory=list) class-attribute instance-attribute

Per-timestep net electric power of the role=net_electric nodes, before economics-level parasitic loads (W).

net_thermal_W = field(default_factory=list) class-attribute instance-attribute

Per-timestep net thermal power of the role=net_thermal nodes (W).

node_history = field(default_factory=dict) class-attribute instance-attribute

node_history[node_name][quantity] -> time series. Populated lazily from state.node_detail; stays empty if record_node_detail=False. Keys appear the first timestep a node reports that quantity; every recorded node/quantity pair grows one entry per record() call so all lists stay the same length.

record(state)

Append a snapshot of state as one timestep entry.

GraphSurface

Bases: SurfaceComponent

TESPy-backed surface / power plant with topology read entirely from YAML.

See module docstring for the inlet/outlet/role naming contract. TESPy objects are built once in init() and stored as private (non-Pydantic, leading-underscore) attributes, excluded from model_dump() — on restore, call init() again to rebuild the network.

power_plant = Field(default_factory=dict, frozen=True) class-attribute instance-attribute

{"nodes": {name: {type, role?, ...attrs}}, "edges": {n: {source, target, source_port?, target_port?}}}. See module docstring for the full shape.

well_spacing = Field(default=707.0, frozen=True) class-attribute instance-attribute

Injector-to-producer distance (m), used as surface pipe length, before the Darcy-Weisbach friction drop to the TESPy inlet.

record_node_detail = Field(default=True, frozen=True) class-attribute instance-attribute

If True (default), populate state.node_detail / history.node_history with every node's P/Q/T/p/m each solve(). Set False to skip this (e.g. a large network run over many timesteps where the extra bookkeeping/storage isn't worth it).

state = Field(default_factory=GraphSurfaceState) class-attribute instance-attribute

Plant state of the current solve; an orchestrator that re-solves within a timestep restores it first.

history = Field(default_factory=GraphSurfaceHistory) class-attribute instance-attribute

Per-timestep record of the plant state.

record(timestep)

Raise if the converged timestep delivers negative power or heat, then record it.

A plant with a turbine delivers negative power when the turbine no longer covers the plant's own pumps, and a plant with role: net_thermal exchangers delivers negative heat when the produced fluid has cooled so far (e.g. once the reservoir is depleted) that those exchangers would heat it instead. Both are checked here, once per timestep on the converged state, rather than in solve(): the injection-enthalpy iteration's first pass starts a closed loop from the cold seed, whose produced fluid is legitimately too cool for a solve or two before the loop converges.

Only a plant with a turbine is expected to make power. A plant without one (e.g. a direct-heat plant whose only electric node is a circulation pump) is always a net consumer, which is its correct state, and the economics count its power as a by-product cost.

Raises:

Type Description
NegativeNetPowerError

with the net electric output.

NegativeNetThermalError

with the net thermal output.

init()

Build the TESPy network(s) from power_plant.nodes/edges.

Normally builds exactly one network. If any node's type is PumpOrValve, builds TWO instead -- one resolving every such node to Valve, one to Compressor -- and activates the Valve one first; solve() falls back to the Compressor one if the Valve one turns out physically invalid for a given timestep's conditions. See _NetworkBundle's docstring for why this is two full networks rather than one smarter one.

solve(inlet, step)

Solve the TESPy network and extract outlet conditions + net power/thermal.

tango_core.components.economic.base

Abstract base for economic components in tango.

EconomicComponent

Bases: Component

Abstract base for economic components.

Economic components run exactly once, after all physical timesteps are complete, and compute project-level metrics (CAPEX, LCOE, etc.) from the other components' final solved state — not once per timestep like every other component. It is a plain Component, not a FlowComponent: no fluid flows through it, so it has no inlet/outlet and its solve() takes no inlet. See SystemDirect.finalize() and Workflow._build_economic_component() for how this is wired: an economic component is deliberately excluded from the per-timestep _ordered/_by_idx circuit (no prev/next), and instead receives every other component by reference (self._components, set by the orchestrator immediately before calling solve()) — see DoubletEconomicComponent for the concrete implementation.

_components/_lifetime are declared PrivateAttr (rather than left as bare, undeclared attributes the way GraphSurface's TESPy network is — see that class's docstring) specifically so external callers (SystemDirect.finalize(), Workflow.__init__) setting them from OUTSIDE this class type-check under mypy; a bare undeclared assignment only type-checks from within the defining class's own methods.

project_maturity = Field(frozen=True) class-attribute instance-attribute

Whether wells/permitting/exploration already exist (BROWN_FIELD) or must still be paid for (GREEN_FIELD).

discount_rate = Field(frozen=True) class-attribute instance-attribute

Discount rate as a dimensionless fraction (e.g. 0.095 = 9.5%).

main_product = Field(default=MainProduct.ELECTRICITY, frozen=True) class-attribute instance-attribute

Which output is the plant's primary product — determines LCOE vs LCOH.

solve() abstractmethod

Compute economic metrics from the other components' final solved state.

Reads sibling components via self._components (a private, non-Pydantic attribute set by the orchestrator right before this call — see the class docstring).

tango_core.components.economic.doublet

Doublet CAPEX/LCOE economic component for tango.

Computes total CAPEX (wells, permitting, exploration, surface pipes, surface plant) and levelized cost (LCOE or LCOH, via MainProduct) for a hydrothermal DOUBLET topology — one injection well, one production well (itself possibly split across several physics sub-components, or paired with a separate horizontal loop segment — see _compute_well_capex), and a TESPy-node-based surface plant. Well costs use a single fixed formula (the gengeo model — see _well_section_cost); its three coefficients are overridable Fields, but the formula's SHAPE is not configurable, and no alternative well-cost model is supported. Only H2O is supported (no CO2-specific cost terms). This is not a general-purpose economic engine — it covers exactly the well/surface-plant shapes tango's own templates use today, nothing broader.

Runs exactly once, after every physical timestep completes — see EconomicComponent's (base.py) and SystemDirect.finalize()'s docstrings for why. Surface-plant CAPEX sizing and the LCOE denominator use the RUN-AVERAGED power/heat-duty of each turbine/pump/condenser node — the time-weighted mean over every recorded timestep, each weighted by the length of its step (time_weighted_mean), not any single timestep's snapshot — since a single timestep's value isn't representative of the plant's actual annual output/cost basis the way a full-run average is.

Sign convention: GraphSurface's own TESPy wiring gives pumps POSITIVE node power (consumes energy) and turbines NEGATIVE (generates energy). Every cost formula that takes a fractional-exponent power of a raw node value (e.g. a pump/turbine equipment-cost curve) applies abs() to that value first, so it stays correct regardless of a given plant topology's exact port wiring — a bare negative number raised to a fractional power would otherwise silently NaN.

Known scope limits (real gaps, not oversights — flagged so a caller can tell a config is hitting one rather than assume a wrong-looking number is a bug): - Direct-heat district-heating exchanger equipment cost is not costed at all. A plain district-heating SimpleHeatExchanger node isn't recognized by any surface-plant cost formula here (those only recognize cooler/condenser/turbine/pump-style equipment), so CAPEX_surface_plant comes back exactly 0.0 for a pure direct-heat topology (e.g. AGS/EGS direct-heat configs). CAPEX_total/LCOH for such a config is therefore real but understates true cost until a district-heat-exchanger cost formula is added. - No production-well-pump "lineshaft" cost add-on. Would only ever apply when a production pump's average power is negative; LumpedProductionWellWithPump.pump_power_watts (well/lumped.py) is non-negative by construction, so that condition can never arise here. - No cost-year/PPI-table interpolation. Uses a single fixed-year cost-index snapshot (core/economic_constants.py) rather than interpolating by calendar year, since tango has no calendar concept (no start_date) yet.

EconomicState(CAPEX_well=_ls(), CAPEX_permitting=_ls(), CAPEX_exploration=_ls(), CAPEX_surface_pipes=_ls(), CAPEX_surface_plant=_ls(), CAPEX_total=_ls(), net_power_W=_ls(), net_thermal_W=_ls(), LCOE=(lambda: _ls(float('nan')))(), specific_investment_cost=(lambda: _ls(float('nan')))(), OPEX=(lambda: _ls(float('nan')))()) dataclass

Bases: StateMethods

Final CAPEX/LCOE result of one DoubletEconomicComponent.solve() call.

Computed exactly once (see module docstring) — unlike every other component's state, this is never recomputed per-timestep, but still uses LockedState for consistency with the rest of tango's write-once-per-solve convention. Deliberately has no *History analog (see CONTRIBUTING.md's *State/*History parity commandment for this exception) — EconomicComponent runs exactly once, via finalize(), never through record().

CAPEX_well = field(default_factory=_ls) class-attribute instance-attribute

Capital cost of the injection, horizontal, and production wells, divided by the drilling success probability ($); only the production well is charged for BROWN_FIELD.

CAPEX_permitting = field(default_factory=_ls) class-attribute instance-attribute

Capital cost of permitting ($).

CAPEX_exploration = field(default_factory=_ls) class-attribute instance-attribute

Capital cost of exploration ($).

CAPEX_surface_pipes = field(default_factory=_ls) class-attribute instance-attribute

Capital cost of the surface pipe between the two wellheads, one run of length well_spacing ($).

CAPEX_surface_plant = field(default_factory=_ls) class-attribute instance-attribute

Capital cost of the surface-plant equipment ($).

CAPEX_total = field(default_factory=_ls) class-attribute instance-attribute

Sum of all CAPEX categories above ($).

net_power_W = field(default_factory=_ls) class-attribute instance-attribute

Run-averaged net electric power after parasitic loads (W).

net_thermal_W = field(default_factory=_ls) class-attribute instance-attribute

Run-averaged net thermal power (W).

LCOE = field(default_factory=lambda: _ls(float('nan'))) class-attribute instance-attribute

Levelized cost of the main product, electricity or heat ($/kWh); NaN when undefined.

specific_investment_cost = field(default_factory=lambda: _ls(float('nan'))) class-attribute instance-attribute

CAPEX_total per unit of main-product power ($/kW) -- see _compute_specific_investment_cost.

OPEX = field(default_factory=lambda: _ls(float('nan'))) class-attribute instance-attribute

Net annual O&M cost ($/yr) -- see _compute_opex.

DoubletEconomicComponent

Bases: EconomicComponent

CAPEX + LCOE for a hydrothermal DOUBLET plant — see module docstring for scope.

capacity_factor = Field(default=0.9, frozen=True) class-attribute instance-attribute

Plant capacity factor (dimensionless fraction).

opex_cost_fraction = Field(default=0.045, frozen=True) class-attribute instance-attribute

Base O&M cost as a fraction of CAPEX, before by-product revenue offset.

electricity_price = Field(default=0.25, frozen=True) class-attribute instance-attribute

By-product electricity price ($/kWh) — used only when main_product is HEAT.

heat_price = Field(default=0.05, frozen=True) class-attribute instance-attribute

By-product heat price ($/kWh) — used only when main_product is ELECTRICITY.

gengeo_quadratic_length_coeff = Field(default=0.105, frozen=True) class-attribute instance-attribute

_well_section_cost's L^2 coefficient — economies-of-scale term on a well section's own combined depth. GenGEO's default cost basis; override from YAML if a different cost basis is needed.

gengeo_diameter_length_coeff = Field(default=1776.0, frozen=True) class-attribute instance-attribute

_well_section_cost's d*L coefficient (diameter- and length-dependent casing/material cost). GenGEO's default cost basis.

gengeo_mobilization_cost_usd = Field(default=275300.0, frozen=True) class-attribute instance-attribute

_well_section_cost's fixed mobilization cost, charged once per well SECTION (see _compute_well_capex's docstring for what counts as one section). GenGEO's default cost basis.

state = Field(default_factory=EconomicState) class-attribute instance-attribute

Final economic results, computed once after the last timestep.

solve()

Compute CAPEX + LCOE from self._components (set by the orchestrator).

Raises:

Type Description
RuntimeError

If called without self._components having been set first (i.e. called directly rather than via SystemDirect.finalize()).