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
- Implement the Component subclass with a
from_dict(config: dict)classmethod. - Add a
(type_str, variant_str): ClassNameentry 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.
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
|
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, |
required |
well_eff_diameter
|
float
|
Effective well diameter used in the
impedance calculation, |
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
Sourcenode named"inlet"—solve()writesT/p/m/fluidonto its outgoing connection from itsinletparameter each timestep. - Exactly one
Sinknode named"outlet"—solve()forces its incoming connection's pressure toself.injection_pressure(the BC variableSystemBCIterationiterates), and readsself.outletback off it after solving. - Any node contributing to the plant's net output tags itself with
role: net_electricorrole: net_thermal(seeComponentRoleincore/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.valin W (SI), regardless of theh_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 |