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 |