Skip to content

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.

The RAFT template's loop and ORC plant. Purple ① and ② mark where tango and RAFT exchange boundary conditions each pass; the grey box shows how each timestep's passes converge.

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 (variant numerical): the three wells are NumericalWell segments marched in sequence, exactly as when they are configured as three separate components.
  • RaftGroupedSubsurface (variant raft): RAFT simulates the wells and the surrounding rock (see tango_core.external.raft_wrapper). Its segment blocks give only geometry (well_length, diameter, pipe_roughness), and a raft: 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 by SystemBCIteration).
  • Outlet, set by tango: the production wellhead pressure, target_extraction_pressure (from sim_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's state before 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's accept_timestep calls 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