Skip to content

Wells

well components/well/ · config type: injection_well, production_well, production_well_with_pump, horizontal_well

Wells carry the fluid between the surface and the reservoir: the injection well takes the cooled fluid down, the production well brings the hot fluid up, and a pumped production well adds the pressure the surface plant needs. Every well computes friction and the hydrostatic pressure change; the numerical variant also computes the heat exchanged with the rock.

Variant Use it when Model
lumped Quick studies and sweeps One segment, closed form; temperature follows the geothermal gradient, no heat exchange with the rock
numerical Heat loss to the rock matters, or the well is inclined or horizontal (angle_from_vert_deg) Marched cell by cell, with CoolProp fluid properties and a heat-loss model at every node

horizontal_well (AGS closed loops) exists only as numerical. External well simulators (Moskito, OLGA, T2Well) are planned as further variants.

How the models work

Lumped wells

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.

Numerical wells

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.

Config keys

horizontal_well · numerical → NumericalWell

Key Type Default Meaning
component_idx int required undocumented
save_interval int \| None 1 undocumented
prev int required undocumented
next int required undocumented
well_length float required undocumented
diameter float required undocumented
pipe_roughness float required undocumented
gravity float 9.81 undocumented
angle_from_vert_deg float 0.0 undocumented
num_cells int required undocumented
discretization_given tuple[str, ...] () undocumented
cell_length float required undocumented
wellhead_depth float 0.0 undocumented
gravity_scale_factor float 1.0 undocumented
friction_model FrictionModel <FrictionModel.HAALAND: 'haaland'> undocumented
heat_transfer_model HeatTransferModel <HeatTransferModel.ZHANG_2011: 'zhang-2011'> undocumented

Filled in automatically, not set in this block: common from the common: block.

injection_well · lumped → LumpedInjectionWell

Key Type Default Meaning
component_idx int required undocumented
save_interval int \| None 1 undocumented
prev int required undocumented
next int required undocumented
well_length float required undocumented
diameter float required undocumented
pipe_roughness float required undocumented
gravity float 9.81 undocumented

Filled in automatically, not set in this block: common from the common: block.

injection_well · numerical → NumericalInjectionWell

Key Type Default Meaning
component_idx int required undocumented
save_interval int \| None 1 undocumented
prev int required undocumented
next int required undocumented
well_length float required undocumented
diameter float required undocumented
pipe_roughness float required undocumented
gravity float 9.81 undocumented
num_cells int required undocumented
discretization_given tuple[str, ...] () undocumented
cell_length float required undocumented
wellhead_depth float 0.0 undocumented
gravity_scale_factor float 1.0 undocumented
friction_model FrictionModel <FrictionModel.HAALAND: 'haaland'> undocumented
heat_transfer_model HeatTransferModel <HeatTransferModel.ZHANG_2011: 'zhang-2011'> undocumented

Filled in automatically, not set in this block: common from the common: block.

production_well · lumped → LumpedProductionWell

Key Type Default Meaning
component_idx int required undocumented
save_interval int \| None 1 undocumented
prev int required undocumented
next int required undocumented
well_length float required undocumented
diameter float required undocumented
pipe_roughness float required undocumented
gravity float 9.81 undocumented

Filled in automatically, not set in this block: common from the common: block.

production_well · numerical → NumericalProductionWell

Key Type Default Meaning
component_idx int required undocumented
save_interval int \| None 1 undocumented
prev int required undocumented
next int required undocumented
well_length float required undocumented
diameter float required undocumented
pipe_roughness float required undocumented
gravity float 9.81 undocumented
num_cells int required undocumented
discretization_given tuple[str, ...] () undocumented
cell_length float required undocumented
wellhead_depth float 0.0 undocumented
gravity_scale_factor float 1.0 undocumented
friction_model FrictionModel <FrictionModel.HAALAND: 'haaland'> undocumented
heat_transfer_model HeatTransferModel <HeatTransferModel.ZHANG_2011: 'zhang-2011'> undocumented

Filled in automatically, not set in this block: common from the common: block.

production_well_with_pump · lumped → LumpedProductionWellWithPump

Key Type Default Meaning
component_idx int required undocumented
save_interval int \| None 1 undocumented
prev int required undocumented
next int required undocumented
well_length float required undocumented
diameter float required undocumented
pipe_roughness float required undocumented
gravity float 9.81 undocumented
pump_efficiency float 1.0 undocumented

Filled in automatically, not set in this block: common from the common: block, target_extraction_pressure from sim_config.target_extraction_pressure.

production_well_with_pump · numerical → NumericalProductionWellWithPump

Key Type Default Meaning
component_idx int required undocumented
save_interval int \| None 1 undocumented
prev int required undocumented
next int required undocumented
well_length float required undocumented
diameter float required undocumented
pipe_roughness float required undocumented
gravity float 9.81 undocumented
num_cells int required undocumented
discretization_given tuple[str, ...] () undocumented
cell_length float required undocumented
wellhead_depth float 0.0 undocumented
gravity_scale_factor float 1.0 undocumented
friction_model FrictionModel <FrictionModel.HAALAND: 'haaland'> undocumented
heat_transfer_model HeatTransferModel <HeatTransferModel.ZHANG_2011: 'zhang-2011'> undocumented

Filled in automatically, not set in this block: common from the common: block.

Outputs per timestep

Columns in <name>.smry.csv, where <name> is the component's key in the config.

horizontal_well · numerical → NumericalWell

Column Meaning
<name>_h_inlet undocumented
<name>_T_inlet undocumented
<name>_P_inlet undocumented
<name>_mass_rate undocumented
<name>_t_d undocumented
<name>_h_outlet undocumented
<name>_T_outlet undocumented
<name>_P_outlet undocumented
<name>_pump_power_watts undocumented

injection_well · lumped → LumpedInjectionWell

Column Meaning
<name>_h_inlet undocumented
<name>_h_outlet undocumented
<name>_T_inlet undocumented
<name>_T_outlet undocumented
<name>_P_inlet undocumented
<name>_P_outlet undocumented
<name>_mass_rate undocumented
<name>_rho undocumented
<name>_mu undocumented
<name>_velocity undocumented
<name>_Re undocumented
<name>_friction_factor undocumented
<name>_delta_p_friction undocumented
<name>_delta_p_hydrostatic undocumented

injection_well · numerical → NumericalInjectionWell

Column Meaning
<name>_h_inlet undocumented
<name>_T_inlet undocumented
<name>_P_inlet undocumented
<name>_mass_rate undocumented
<name>_t_d undocumented
<name>_h_outlet undocumented
<name>_T_outlet undocumented
<name>_P_outlet undocumented
<name>_pump_power_watts undocumented

production_well · lumped → LumpedProductionWell

Column Meaning
<name>_h_inlet undocumented
<name>_h_outlet undocumented
<name>_T_inlet undocumented
<name>_T_outlet undocumented
<name>_P_inlet undocumented
<name>_P_outlet undocumented
<name>_mass_rate undocumented
<name>_rho undocumented
<name>_mu undocumented
<name>_velocity undocumented
<name>_Re undocumented
<name>_friction_factor undocumented
<name>_delta_p_friction undocumented
<name>_delta_p_hydrostatic undocumented

production_well · numerical → NumericalProductionWell

Column Meaning
<name>_h_inlet undocumented
<name>_T_inlet undocumented
<name>_P_inlet undocumented
<name>_mass_rate undocumented
<name>_t_d undocumented
<name>_h_outlet undocumented
<name>_T_outlet undocumented
<name>_P_outlet undocumented
<name>_pump_power_watts undocumented

production_well_with_pump · lumped → LumpedProductionWellWithPump

Column Meaning
<name>_h_inlet undocumented
<name>_h_outlet undocumented
<name>_T_inlet undocumented
<name>_T_outlet undocumented
<name>_P_inlet undocumented
<name>_P_outlet undocumented
<name>_mass_rate undocumented
<name>_rho undocumented
<name>_mu undocumented
<name>_velocity undocumented
<name>_Re undocumented
<name>_friction_factor undocumented
<name>_delta_p_friction undocumented
<name>_delta_p_hydrostatic undocumented
<name>_pump_delta_p undocumented
<name>_pump_power_watts undocumented

production_well_with_pump · numerical → NumericalProductionWellWithPump

Column Meaning
<name>_h_inlet undocumented
<name>_T_inlet undocumented
<name>_P_inlet undocumented
<name>_mass_rate undocumented
<name>_t_d undocumented
<name>_h_outlet undocumented
<name>_T_outlet undocumented
<name>_P_outlet undocumented
<name>_pump_power_watts undocumented