Grouped subsurface¶
well components/well/grouped_subsurface.py · config type: grouped_subsurface
An AGS loop's whole subsurface (injection well, horizontal well and production well) as one circuit component, so the same config shape can be simulated by different models: tango's own numerical wells, or RAFT, which also models the surrounding rock.
Both variants set the loop's mass flow and temperature at the injection
wellhead and its pressure at the production wellhead
(sim_config.target_extraction_pressure), and solve for the injection
pressure, which the surface plant then delivers. The configured surface
injection_pressure is only the first timestep's starting guess. Why, and
how the numerical variant does it, is under "Boundary conditions" below.
| Variant | Use it when | Model |
|---|---|---|
numerical |
The standard AGS loop with tango's own wells | Three numerical wells marched in sequence, from the injection pressure that delivers the production pressure (found by shooting; the same physics as three separate well components, solved the other way round) |
raft |
The rock's heat exchange should come from a 3D finite-element model | RAFT simulates the wells and the rock; needs the optional RAFT install (Install) |
Example: templates/AGS_ORC_electric_grouped_subsurface.yml (numerical) and
templates/AGS_ORC_electric_raft.yml (raft), the same site and plant.
How the models work¶
The grouped loop¶
An AGS subsurface grouped into one component: injection well -> horizontal well -> production well.
An advanced geothermal system (AGS) circulates its working fluid through a
sealed loop: down a vertical injection well, along a horizontal well at
depth, and back up a vertical production well, exchanging heat with the
rock by conduction only. GroupedSubsurfaceComponent groups those three
wells into one circuit component, so the whole subsurface can be simulated
by different models behind the same config shape:
NumericalGroupedSubsurface(variantnumerical): the three wells areNumericalWellsegments marched in sequence, exactly as when they are configured as three separate components.RaftGroupedSubsurface(variantraft): RAFT simulates the wells and the surrounding rock (seetango_core.external.raft_wrapper). Its segment blocks give only geometry (well_length,diameter,pipe_roughness), and araft:block names RAFT's config template.
The loop's geometry is given as three segment blocks, each a well config::
grouped_subsurface:
type: grouped_subsurface
variant: numerical
component_idx: 0
prev: 1
next: 1
injection_well: {well_length: 8000.0, diameter: 0.311, pipe_roughness: 5.5e-5}
horizontal_well: {well_length: 3000.0, diameter: 0.311, pipe_roughness: 5.5e-5}
production_well: {diameter: 0.311, pipe_roughness: 5.5e-5}
The production well's length and the horizontal well's wellhead_depth
both equal the injection well's length, and layout.well_spacing equals
the horizontal well's length; these are derived (see
tango_core.workflows.linked_quantities). The loop sets each segment's
common, circuit indices, save_interval and
angle_from_vert_deg itself, so a segment block may not give them.
Mass flow rate is assumed constant around the loop: the outlet carries the inlet's mass rate.
Boundary conditions¶
The loop is solved with its mass flow and temperature fixed at the inlet (injection wellhead) and its pressure fixed at the outlet (production wellhead), and it solves for the injection pressure that delivers that:
- Inlet, set by tango: the mass rate (
sim_config.mass_rate) and the injection enthalpy (the surface plant's outlet, converged bySystemBCIteration). - Outlet, set by tango: the production wellhead pressure,
target_extraction_pressure(fromsim_config, the same value the surface plant gets as the minimum pressure it needs at its inlet). - Solved by the subsurface model: the injection wellhead pressure
(
state.P_inlet), the production temperature and enthalpy, and, for RAFT, the production mass flow.
SystemBCIteration hands the solved injection pressure to the surface
plant in the same pass (SurfaceComponent.set_injection_pressure), so the
plant's circulation pump or valve delivers exactly the pressure the loop
needs. The surface plant's configured injection_pressure is then only
the first timestep's starting guess.
Why this way round: an external simulator (RAFT) may later lose fluid to storage or leak-off. With the injected mass rate set at the inlet, a loss shows up as a lower production flow, where a makeup tank can replace it (GitHub #63); with the pressure set at the inlet instead, a loss would change the injected rate, which tango controls. RAFT's own template is set up this way too. Both variants use these boundary conditions, so they stay directly comparable.
The numerical variant marches its wells from the inlet, so it finds the
injection pressure by shooting (NumericalGroupedSubsurface's
solve_for_outlet_pressure): it marches from a trial injection pressure
and corrects the trial until the production pressure matches the target.
Given the injection pressure the old inlet-pressure-driven march used, it
reproduces that march's results (tested to 1e-6 relative in
tests/unit/test_grouped_subsurface.py).
RAFT coupling¶
RaftWrapper: drives RAFT, an external wellbore and rock simulator, one tango timestep at a time.
RAFT (GEG-ETHZ/RAFT, the optional raft dependency group) solves flow and heat in
a well embedded in a 3D finite-element model of the surrounding rock. Its
coupling API (geg_raft.api.RaftModel) advances a trial state from the
last accepted state, as often as needed, until the caller accepts it. That
matches tango's injection-enthalpy iteration, which re-solves each timestep
until the loop closes and then moves on:
solve()runs one trial for the current timestep. tango restores each component'sstatebefore every re-solve, and RAFT restarts every trial from its own accepted state, so a re-solve needs nothing restored on RAFT's side.accept()keeps the last trial.GroupedSubsurfaceComponent'saccept_timestepcalls it once per timestep, after the final solve.
RAFT works in pressure, temperature and mass flow; tango's streams carry
enthalpy. The wrapper converts with tango's own fluid properties
(FluidState, common.fluid_name/coolprop_backend), not with the
equation of state RAFT itself uses, which the template selects (RAFT's
theory.md, "Fluid Equation of State"). With the example template's
Boussinesq EOS (density: 1000: density and internal energy linearized
about a reference state, specific_heat: 4250), the loop's enthalpy
gain tango computes from RAFT's inlet and outlet states is 0.6-1.2% lower
than under RAFT's own EOS, and the heat extracted inherits that
difference. A template with RAFT's real-fluid EOS (density: 0) would
make the two agree.
Boundary conditions: RAFT gets the loop's inlet mass flow and temperature
(a flux and a temperature condition on the well's inlet group) and its
outlet pressure (a pressure condition on the outlet group), and returns the
inlet pressure, the outlet temperature and the outlet mass flow. The outlet
pressure is grouped_subsurface's target_extraction_pressure; the
inlet pressure RAFT solves for becomes the surface plant's injection
pressure (see tango_core.components.well.grouped_subsurface's "Boundary
conditions"). This is how RAFT's own template sets the well up, and it
keeps the injected mass rate under tango's control if RAFT later loses
fluid to storage or leak-off: a loss then shows up as a lower outlet flow.
The inlet temperature is converted from tango's enthalpy at the inlet
stream's pressure, the injection pressure from the previous pass;
SystemBCIteration iterates until that pressure stops changing, so the
converged pass is consistent. Mass flow is assumed constant around the loop
(a sealed well), and a RAFT result whose outlet flow strays from
the inlet's by more than RAFT's solver tolerance allows
(_MASS_RATE_REL_TOL) raises.
The raft: block of a tango config is this object. template names a
RAFT config file, made by hand together with its mesh (meshes are never
generated by tango). The template's rock properties, initial temperature
profile, fluid and well alignment are checked against the tango config
(they must agree; neither silently overrides the other). So are the well's
two coupling groups: the template must already give the inlet group a flux
and a temperature condition and the outlet group a pressure condition, all
with function: external (RAFT's own example template does); tango
never switches them (_check_coupling_groups). The wrapper then sets the
well diameter and roughness from the tango config and the output location.
RAFT's own output files (VTKs, flow logs) are kept only when asked for
with set_output_dir() (tango_core run --save-dir does this): RAFT
then writes them there, at the template's output_vtk and
output_frequency, once per tango timestep. Otherwise RAFT writes no
VTKs, and its run directory is temporary.
state/history record, per timestep, RAFT's raw values at the well
inlet and outlet, how much work the timestep took (trial solves, wall
time), RAFT's own timestepping statistics for the accepted trial
(RaftModel.solve_stats), and the accepted trial's profile along the
well (RaftModel.well_profiles()): pressure, temperature and enthalpy at
each node, and mass flow, Reynolds number and well-to-rock heat transfer
coefficient for each element.
Config keys¶
grouped_subsurface · numerical → NumericalGroupedSubsurface¶
| Key | Type | Default | Meaning |
|---|---|---|---|
component_idx |
int |
required | undocumented |
save_interval |
int \| None |
1 |
undocumented |
prev |
int |
required | undocumented |
next |
int |
required | undocumented |
Filled in automatically, not set in this block: common from the common: block, target_extraction_pressure from sim_config.target_extraction_pressure.
Nested blocks:
| Block | Keys | Meaning |
|---|---|---|
injection_well: |
the keys of injection_well · numerical |
undocumented |
horizontal_well: |
the keys of horizontal_well · numerical |
undocumented |
production_well: |
the keys of production_well · numerical |
undocumented |
grouped_subsurface · raft → RaftGroupedSubsurface¶
| Key | Type | Default | Meaning |
|---|---|---|---|
component_idx |
int |
required | undocumented |
save_interval |
int \| None |
1 |
undocumented |
prev |
int |
required | undocumented |
next |
int |
required | undocumented |
Filled in automatically, not set in this block: common from the common: block, target_extraction_pressure from sim_config.target_extraction_pressure.
Nested blocks:
| Block | Keys | Meaning |
|---|---|---|
injection_well: |
WellSegment keys, below |
undocumented |
horizontal_well: |
WellSegment keys, below |
undocumented |
production_well: |
WellSegment keys, below |
undocumented |
raft: |
RaftWrapper keys, below |
undocumented |
WellSegment (injection_well:, horizontal_well:, production_well:):
| Key | Type | Default | Meaning |
|---|---|---|---|
well_length |
float |
required | undocumented |
diameter |
float |
required | undocumented |
pipe_roughness |
float |
required | undocumented |
wellhead_depth |
float |
0.0 |
undocumented |
RaftWrapper (raft:):
| Key | Type | Default | Meaning |
|---|---|---|---|
template |
str |
required | undocumented |
verbosity |
Literal['quiet', 'lite', 'full'] |
'quiet' |
undocumented |
Outputs per timestep¶
Columns in <name>.smry.csv, where <name> is the component's key in the config.
RAFT's step sizes and its profile along the well are lists per timestep, so
they are in <stem>.results.yml, not the CSV.
With --save-dir, RAFT also keeps its own output in <stem>.raft/: the
matrix and well VTKs (at the template's output_vtk and output_frequency,
once per tango timestep, plus the initial state) and its flow log. Without
--save-dir, RAFT writes no VTKs and keeps nothing.
grouped_subsurface · numerical → NumericalGroupedSubsurface¶
| Column | Meaning |
|---|---|
<name>_h_inlet |
undocumented |
<name>_T_inlet |
undocumented |
<name>_P_inlet |
undocumented |
<name>_mass_rate |
undocumented |
<name>_h_outlet |
undocumented |
<name>_T_outlet |
undocumented |
<name>_P_outlet |
undocumented |
<name>_heat_extracted_watts |
undocumented |
Columns <name>.injection_well_<value>: the outputs of injection_well · numerical.
Columns <name>.horizontal_well_<value>: the outputs of horizontal_well · numerical.
Columns <name>.production_well_<value>: the outputs of production_well · numerical.
grouped_subsurface · raft → RaftGroupedSubsurface¶
| Column | Meaning |
|---|---|
<name>_h_inlet |
undocumented |
<name>_T_inlet |
undocumented |
<name>_P_inlet |
undocumented |
<name>_mass_rate |
undocumented |
<name>_h_outlet |
undocumented |
<name>_T_outlet |
undocumented |
<name>_P_outlet |
undocumented |
<name>_heat_extracted_watts |
undocumented |
raft: block (RaftWrapper):
| Column | Meaning |
|---|---|
<name>.raft_P_inlet |
undocumented |
<name>.raft_T_inlet |
undocumented |
<name>.raft_mass_rate_inlet |
undocumented |
<name>.raft_P_outlet |
undocumented |
<name>.raft_T_outlet |
undocumented |
<name>.raft_mass_rate_outlet |
undocumented |
<name>.raft_trial_solves |
undocumented |
<name>.raft_solve_seconds |
undocumented |
<name>.raft_accepted_steps |
undocumented |
<name>.raft_attempts |
undocumented |
<name>.raft_cut_extrapolation |
undocumented |
<name>.raft_cut_newton |
undocumented |
<name>.raft_constraint_switches |
undocumented |
<name>.raft_dt_min_proceeds |
undocumented |