A finite element method (FEM) simulator for coupled subsurface fluid flow and heat transport in geothermal reservoirs, specifically developed for native coupling with TANGO.
Physical processes include:
- Fluid flow
- Darcy flow
- Compressible equations of state:
- Linearized Boussinesq approximation
- Full EOS via CoolProp for water, super-critical CO2, etc.
- Fracture flow and leak-off
- Volumetric poroelastic effects
- Heat flow
- Diffusion
- Advection
- Fracture heat transfer with conductive and advective leak-off
- Getting Started
- Running the simulation
- Coupling API
- Theory
- Configuration Parameters
- Mesh generation
- Project Structure
- Developers
- Citation
- License
- Python version specified in
.python-version - uv (if not installed: install uv )
RAFT is published on PyPI as geg-raft:
pip install geg-raft
and imported as:
import geg_raft as raftFor development:
- navigate to the repository directory and run
uv sync - execute a script via:
uv run some_script.py
uv sync --group docsuv run just docs- open
docs/_build/html/index.htmlin a browser
This builds the Sphinx HTML docs (including this README and theory.md) from source.
Run a simulation by passing a config file name:
uv run -m geg_raft **config file name** **options**
For example, to run the example config with one progress line per timestep:
uv run -m geg_raft config_example --verbosity lite
The config name may be given with or without its .yaml extension, and is looked up in the config/ directory unless --config-dir points elsewhere. The mesh file named under mesh: file: is read from the same directory. Running without a config name prints the help.
| Option | Effect |
|---|---|
config |
Config file name, with or without .yaml, e.g. config_example |
--config-dir DIR |
Directory holding the config and its mesh (default: config/ in the repository) |
--verbosity {quiet,lite,full} |
Console output (default: full), see below |
--quiet |
Same as --verbosity quiet |
--test |
Run the test suite instead of a simulation (same as uv run pytest) |
-h, --help |
List the options |
Console output levels:
full: everything, from the config parameters and defaults applied, through initial conditions, to every timestep's solver iterations and timestep changes.lite: one line per timestep attempt, with its step number, time, timestep size and progress. A step that is cut and retried prints a line for each attempt, so time lost to cuts stands out from steps that are simply slow.quiet: nothing.
The run exits with status 0 when it completes, and status 1 if a timestep fails to converge at timestep_min.
Results are written to outputs/<config name>/, or to <output_directory>/<config name>/ if output_directory is set:
domain.vtk(anddomain_wells.vtkwith wells): material properties and boundary condition nodes, written once at the start.Matrix.vtk.<n>, plusFracture.vtk.<n>andWell.vtk.<n>when fractures or wells exist: solution fields at output stepn, ifoutput_vtkis on. View them in Paraview.outflow.log: time, pressure, flow rate and temperature of each labeled boundary condition group, at every output step.run.log: the console output, ifoutput_logis on. It is written at the chosen verbosity.
Output steps are every output_frequency accepted timesteps, starting from the initial condition (step 0).
Meshes are made with Gmsh, by hand or with the generator described under Mesh generation, and must be exported as .msh files in Version 2 ASCII format. Gmsh requires a separate download and installation.
RAFT idealizes the subsurface as a continuous, fully-saturated, single-phase porous medium and solves a coupled thermo-hydraulic (pressure/temperature) finite element problem with a compressible, pressure- and temperature-dependent fluid equation of state. The governing equations, fluid EOS, finite element discretization, fracture coupling, mesh cutting algorithm, stabilization, and time-integration schemes are documented in theory.md.
The simulator uses a YAML configuration file to define simulation options, material properties, initial conditions, boundary conditions, and numerical controls. Below is the list of parameters and their options.
file(string, default:"box3D.msh"): Name or relative path to the Gmsh.mshfile (Version 2.x format). Meshes may be either B8 or T4 elements in 3D or Q4 or T3 in 2D. Meshes can consist of any combination of elements, so long as the element boundaries form a continuous approximation.dimensions(integer, default:3): Spatial dimensions of the analysis (2or3).regions(subcategories): See theregionssection for specifying regions, or specify the subcategory"list":(str) and provide the path to a .txt file with a list of corresponding region for each element.fractures(subcategories): See thefracturessection for specifications.domain(subcategories, optional): Outer boundary of the geometry, used only by the mesh generator (see Mesh generation). Ignored by the solver, which takes its domain from the mesh file.sizing(subcategories, optional): Element sizes for the mesh generator (see Mesh generation). Ignored by the solver.
Regions allow you to assign different material properties to different sections of your domain. Each region is defined by a geometric shape which assign the region number to all elements whose centroids fall within the shape. Region numbers correspond to indices in the material property lists. Regions are an independent definition that does not rely on the mesh or domain, but conforming mesh boundaries are encouraged for more accurate results.
If regions are not defined, homogeneity is assumed (all elements are assigned to region 0).
Region Definition: Each region specification requires three fields:
shape(string): Type of geometric boundary. Supported shapes:"sphere""cylinder""polyhedron"
values(list): Shape-dependent parameters (see below).region_number(integer): Region ID assigned to elements within the shape. Must correspond to a valid index in your material property lists.
Shape-Specific Parameters:
- Sphere:
- shape: "sphere"
values: [[center_x, center_y, center_z], radius]
region_number: 1- Center (list of 3 floats): Coordinates of sphere center. Note that this can be outside the domain.
- Radius (float): Sphere radius.
- Cylinder:
- shape: "cylinder"
values: [[center_x, center_y, center_z], radius, [axis_x, axis_y, axis_z], height]
region_number: 1- Center (list of 3 floats): Coordinates of cylinder axis origin. Note that this can be outside the domain.
- Radius (float): Cylinder radius.
- Axis direction (list of 3 floats): Unit vector along cylinder axis (will be normalized automatically).
- Height (float, optional): Cylinder half-height along axis direction. The cylinder extends equally in both directions from the center point. If omitted, height is unbounded.
- Polyhedron:
- shape: "polyhedron"
values: [[x1, y1, z1], [x2, y2, z2], ..., [xn, yn, zn]]
region_number: 1- Vertex list (list of lists): Coordinates of polyhedron vertices. A convex hull is computed from these points to define the region. Assignment Rules:
- Regions are processed in the order specified in the config file.
- If an element centroid falls within multiple regions, it is assigned to the last (highest-priority) region that contains it.
- All elements are initially assigned to region 0; unassigned elements remain in region 0.
- Material properties are indexed by region number, so ensure your material lists have entries for each region used.
- Multiple shape definitions can be assigned the same region numbers.
Fractures use a conforming mesh approach and cut through the existing mesh, creating conforming nodes around them; see Fracture Coupling for the underlying physics. These cuts may lead to poorly conditioned elements, so care should be taken when examining results. Mesh refinement around fractures is often necessary.
Current limitation: Fractures are only supported in 2D analyses (
dimensions: 2). 3D fracture support is not yet implemented (a warning is printed and the mesh is returned unmodified).
Fracture Definition: Each fracture specification requires three fields:
-
shape(string): Type of geometric boundary. These shapes are only used in 3D, in 2D all fractures are represented as lines. Supported shapes:"ellipse""rectangle"
-
values(list):$[[x_c, y_c, z_c ], [a,b], [\theta_x, \theta_y, \theta_z]]$ -
$[x_c, y_c, z_c ]$ (list[float], no default): coordinates of the plane center. In 2D analysis, only$x_c$ and$y_c$ are considered. -
$[a,b]$ (list[float], no default): extents. For the ellipse,$a$ = major axis distance,$b$ = minor axis distance. For the rectangle,$a$ = half-length,$b$ = half-width. In 2D,$a$ is taken as the fracture half-length. -
$[\theta_x, \theta_y, \theta_z]$ (list[float], no default): plane angles in degrees.$\theta_x$ = plane angle with respect to the x-axis,$\theta_y$ = plane angle with respect to the y-axis, ,$\theta_z$ = plane angle with respect to the z-axis. In 2D, only$\theta_x$ and$\theta_y$ are considered.
-
Hydraulic and thermal properties (aperture, heat_transfer_factor) are not specified here; they are defined per-fracture under material.fracture (see the material section below and Fracture Coupling for their role in the governing equations).
IMPORTANT NOTE FOR FRACTURE SPECIFICATIONS: The fracture mesh cutting algorithm can fail! Always check the quality of the cut elements in
domain.vtk. If the algorithm fails, it can usually be solved by refining the mesh around fractures and/or junctions.
Wells carry fluid from the surface into the rock mass and interact with the surrounding rock mass before the fluid reaches the injection point. Wells always interact thermally and may interact hydraulically in an open perforation interval. See Well Coupling for the underlying physics. Mesh refinement around wells is often necessary.
Current limitation: Wells are currently only supported in 3D analyses (
dimensions: 3). This will be extended to support axisymmetric analyses in 2D in the future.
Well Definition: Each well specification requires two fields:
alignment(list of list of floats as [start, end] point pairs): Each pair defines a line segment (points matching the spatial dimensions).- The nodes and connectivity are found by snapping to the path of existing mesh edges closest to that segment. Lines may extend beyond the reservoir boundary.
- If the exact path does not exist among the element edges, the line snaps to the shortest edge path connecting the start and end node. This throws a warning and reports the true vs. prescribed line lengths.
dL_max(float, default: L/10): Maximum element length for sections of the well which exceed the reservoir boundaries.
Wells that share physical nodes in the mesh are automatically connected. Thus, perforation intervals or branching wells can be specified by having the wells share start or end points.
Mesh sizing: when the mesh is built with raft_to_geo, mesh.sizing.well sets the element size around the wells, in the same profile form as frac and bc:
mesh:
sizing:
outer: 25
well: [[5, 10], [5, 50]] # 5 at the well, growing to 10 over 5 m, then to `outer` over 50 mWell alignments are discretized in the mesh, so element edges follow them and wells sharing a start or end point share the node that connects them. Alignments extending past the reservoir are clipped to mesh: domain for meshing, with a warning naming the well; dL_max applies to those outside sections and so does not affect the mesh.
Hydraulic and thermal properties (diameter, perforation_conductance, heat_transfer_factor, roughness) are not specified here; they are defined per-well under material.wells (see the material section below and Well Coupling for their role in the governing equations).
CONSISTENT UNITS: In general, RAFT does not require any specific units, so long as the units are internally consistent. For example, lengths can be specified in feet, timesteps in months, temperature in Farenheit, and energy in J, so long as the thermal conductivity is then specified in J/ft/month/F. The exception this comes when using the real equation of state for the fluid or the viscosity correlations, in which case standard SI units of m, s, kg, J, K, and Pa must be used.
-
solid: Rock mass properties. Rock mass properties are defined per region. If regions are defined, RAFT expects a list with a number of entries equal to the number of regions. Region numbers correspond to property indices.-
bulk_mod(float, default:20.0e9): Solid bulk modulus in Pascals ($\text{Pa}$ ). -
density(float, default:2600.0): Rock density in$\text{kg/m}^3$ . -
therm_cond(float or list, default:3.0): Rock thermal conductivity in$\text{W/m}\cdot\text{K}$ . Can be a scalar for isotropic conductivity, or a list of length equal to the dimensions for anisotropic conductivity (e.g.[3.0, 2.0, 0.1]). For anisotropic properties, the list corresponds to the local x, y, z axes which can be rotated withrotation_x/y/z. -
specific_heat(float, default:800.0): Rock specific heat capacity in$\text{J/kg}\cdot\text{K}$ . -
therm_expansion(float, default:12.0e-6): Rock volumetric linear thermal expansion coefficient in$1/\text{K}$ . -
porosity(float, default:0.01): Reservoir porosity (dimensionless fraction). -
biot_coeff(float, default:0.5): Biot-Willis coefficient (dimensionless). -
permeability(float or list, default:1.0e-16): Permeability in$\text{m}^2$ . Can be a scalar for isotropic permeability, or a list of length equal to the dimensions for anisotropic permeability (e.g.[1.0e-13, 1.0e-11, 1.0e-12]). For anisotropic properties, the list corresponds to the local x, y, z axes which can be rotated withrotation_x/y/z. -
rotation_x(float, default:0.0): Rotation angle of the local coordinate system around the x-axis in degrees. -
rotation_y(float, default:0.0): Rotation angle of the local coordinate system around the y-axis in degrees. -
rotation_z(float, default:0.0): Rotation angle of the local coordinate system around the z-axis in degrees.
-
These rotation parameters define a 3D rotation matrix
-
fluid: Fluid phase properties.-
fluid_type(string, default:"WATER"): Only required for a real fluid EOS. Set the working fluid in the reservoir. Required when using nonlinear properties, as it controls the property lookup in CoolProp. E.g."WATER"for water or"CO2"for supercritical CO2. -
density(float, default:1000.0): Density determines whether to use the Boussinesq approximation or a real EOS.-
density: 0- Indicates to use the real EOS. All other fluid properties are ignored except forviscosity,therm_cond, andfluid_type. -
density: non-zero float- sets reference density$\rho_0$ in$\text{kg/m}^3$ at reference state$p_0, T_0$ .
-
-
reference_temperature(float, default:293.0): Reference temperature$T_0$ for the Boussinesq approximation in$\text{K}$ . Not used when nonlinear density is specified. -
reference_pressure(float, default:1.0e5): Reference pressure$p_0$ for the Boussiesq approximation in$\text{Pa}$ . Not used when nonlinear density is specified. -
bulk_mod(float, default:2.0e9): Fluid bulk modulus in Pascals ($\text{Pa}$ ). Used by Boussinesq approximation, ignored when using real EOS. -
therm_expansion(float, default:200.0e-6): Fluid volumetric thermal expansion coefficient in$\text{K}^{-1}$ . Used by Boussinesq approximation, ignored when using real EOS. -
specific_heat(float, default:4180.0): Fluid specific heat capacity in$\text{J/kg}\cdot\text{K}$ . Used by Boussinesq approximation, ignored when using real EOS. -
therm_cond(float, default:0.6): Fluid thermal conductivity in$\text{W/m}\cdot\text{K}$ . -
viscosity(float, default:1.0e-3): Fluid dynamic viscosity in$\text{Pa}\cdot\text{s}$ .- Default behaviour: Viscosity is a constant set to the specific float value. Recommended for cases with small variations in pressure or temperature.
-
True behaviour: Set to
0to instead use a temperature- and pressure-dependent, real-fluid viscosity looked up from CoolProp for the configuredfluid_type. Recommended for super-critical CO2. -
Pure thermal behabiour: Set to
-1to instead use a temperature-dependent viscosity with the form$\mu = A e^{-B/T + CT + DT^2}$ . Curently only works for water. For water, $ A = 1.856·10^{−11} \text{mPa}\cdot \text{s}, B = 4209 \text{K}, C = 0.04527 \text{K}^{-1}$ and$D = -3.376\times 10^{-5} \text{K}^{-2}$ .
-
IMPORTANT NOTE FOR NONLINEAR FLUID PROPERTIES: When using non-linear material properties, the magnitude of pressure and temperature matter. Temperature must be specified in Kelvin, while pressure boundary conditions should be specified above the fluid's saturation point. Temperature and pressure are clipped to
$274$ –$1900,\text{K}$ and$0.1$ –$700,\text{MPa}$ before the lookup, to keep unconverged solver iterates within CoolProp's valid range; pressures should stay comfortably above the lower bound, since it sits close to water's saturation curve at higher temperatures.
-
fracture(required iffracturesare defined inmesh): Hydraulic and thermal properties of the fracture(s), used in the fracture governing equations. Each property is a list indexed the same way as fractures are listed undermesh.fractures.-
aperture(list[float], no default): Hydraulic aperture of the fracture,$w$ , used in the cubic-law in-plane flow and leak-off terms. -
heat_transfer_factor(list[float], no default): Multiplier,$F$ , on the fracture-matrix heat transfer coefficient, which assumes laminar flow between parallel plates. Use 1 for the standard laminar value, values below 1 to reduce heat exchange (0 is perfectly insulated), and large values to approach local thermal equilibrium between fracture and matrix.
-
-
wells(required ifwellsare defined inmesh): Hydraulic and thermal properties of the well(s), used in the well governing equations. Each property is a list indexed the same way as wells are listed undermesh.wells.-
diameter(list[float], no default): Hydraulic diameter of the well,$D$ , which determines frictional resistance. -
roughness(list[float], no default): Roughness (units of length) used to calculate friction in turbulent flow. -
perforation_conductance(list[float], no default): Conductance from the well to the reservoir in ($m^2/m$ ). The pressure drop out of the well is typically a function of the skin effect and perforation radius, as well as damaged zones. A value of 0 is an unperforated well. A value of 1 typically large enough to hydraullically link the well and the reservoir while neglecting the pressure drop caused by perforations and skin effects. -
heat_transfer_factor(list[float], no default): Multiplier,$F$ , on the well-rock heat transfer coefficient. The coefficient follows the flow regime: constant in laminar flow (Re < 2000), the Gnielinski correlation in turbulent flow (Re > 2300, including the effect ofroughness), and interpolated between. Use 1 for an uninsulated well, values below 1 for insulated sections (0 is perfectly insulated); values above 1 are permitted.
-
Injecting and Producing via Wells: For the well to interact hydraulically with the reservoir (i.e. inject or produce fluid), the connected well chain must have at least one interval with non-zero perforation conductance.
-
assignment(string, default:"constant"): determine how initial conditions are assigned.-
"constant": Uniform conditions assumed throughout for pressure and temperature. Inputs required underinitial_conditions:-
T_ini(float, default:20.0): Initial temperature in$^\circ\text{C}$ . -
p_ini(float, default:1.0e5): Initial pressure in$\text{Pa}$ .
-
-
"gradient": A gradient is applied in the direction of a reference vector. Not that this may not be at equilibrium in the case of heterogeneous properties. Inputs required underinitial_conditions:-
T_ini(float, default:20.0): Reference temperature at minimum point along gradient vector in domain in$^\circ\text{C}$ . -
p_ini(float, default:1.0e5): Reference pressure at minimum point along gradient vector in domain in$\text{Pa}$ . -
T_grad(float, default:0.0): Temperature gradient along the gradient vector in$^\circ\text{C/m}$ . -
p_grad(float, default:0.0): Pressure gradient along the gradient vector in$\text{Pa/m}$ . -
grad_direction_T(list[float], default:[0,0,-1]): Vector in the direction of the temperature gradient. Automatically normalized. -
grad_direction_p(list[float], default:[0,0,-1]): Vector in the direction of the pressure gradient. Automatically normalized.
-
-
"BC_compatible": Solve the non-linear transport problem for the steady-state conditions within the domain under the boundary conditions applied at time$t=t_0$ . The solved pressure and temperature fields are applied as initial conditions and reference conditions. Invokes the appropriate solver based on input material properties, regardless of user timestep solver specification.- The steady state describes the unperturbed formation: wells, boundary conditions on well nodes, and
"external"boundary conditions are left out of this solve. - Wells then take the temperature of the rock they pass through; outside the domain, they take the temperature of the nearest well node inside it. Well pressure is hydrostatic along each well, starting from
p_iniat the well head (the first alignment point). Connected wells share the head of the lowest-numbered well.
- The steady state describes the unperturbed formation: wells, boundary conditions on well nodes, and
-
boundary_conditions is a list of groups at the root of the config. Each group applies to one geometry feature (specified using one of four geometric methods: node indices, coordinate proximity, named faces, or lines), and can carry a hydraulics block specifying pressure or fluid flux, a thermal block specifying temperature or heat flux, or both.
Sample boundary condition group
- coords: [[x1, y1, z1], [x2, y2, z2]] (geometry specification - required)
label: "inlet" (label - optional)
hydraulics: (field)
type: "flux" (type - required)
values: [[0, 0.001], 100] (values - required)
function: "ramp" (function - optional)
constraints: (constraints - optional)
maximum_pressure: 16.0e+6
minimum_pressure: 1.0e+4
thermal: (field)
type: "temperature" (type - required)
values: [[0, 0.001], 100] (values - required)
function: "ramp" (function - optional)Geometry Specification (Required): Each boundary condition group must specify nodes using one or a combination of the following methods:
-
nodes(list of integers, or string): Direct node IDs where the boundary condition is applied. The string"all"is also accepted to fix all nodes in the mesh, or"matrix"to fix all nodes in the reservoir while leaving fracture and wellbore nodes unconstrained. -
coords(list of coordinates): List of coordinate points; the mesh node closest to each point will be selected. Each coordinate should be a list matching the spatial dimensions (e.g.,[x, y, z]for 3D,[x, y]for 2D). -
faces(list of strings): Named boundary faces from preprocessing. Supported face identifiers:"x_min","x_max","y_min","y_max","z_min","z_max". All nodes on the specified faces will be included. Fluxes are integrated over the face.- Fluid fluxes: Specify
valuesas mass flux in$(\text{kg}/\text{s})/\text{m}^2$ . - Temperature fluxes: Specify
valuesin$\text{W} / \text{m}^2$ .
- Fluid fluxes: Specify
-
lines(list of float[start, end]point pairs): Each pair defines a line segment (points matching the spatial dimensions, as incoords). The nodes and connectivity are found by snapping to the path of existing mesh edges closest to that segment. The line is snipped to the domain boundaries. If the exact path does not exist among the element edges, the line snaps to the shortest edge path connecting the start and end node. This throws a warning and reports the true vs. prescribed line lengths. You can view the nodes withlineboundary conditions indomain.vtkunder theline_BC_nodesfield. Fluxes are integrated over the prescribed line.- Fluid fluxes: Specify
valuesas mass flux in$(\text{kg}/\text{s})/\text{m}$ . - Temperature fluxes: Specify
valuesin$\text{W} / \text{m}$ .
- Fluid fluxes: Specify
-
well(list[index (int), location (string)]): Specify conditions on a well, only valid ifwellsis specified in the mesh. The well boundary condition specification takes the index of the well (corresponding to its 0-indexed position as specified inmesh) and the location as a string. Location only acceptsinletoroutletand respectively map to the first and last coordinate specified by the well alignment.
Field Blocks (At least one required):
hydraulics: controls fluid pressure/flux at this group.type: "pressure": Dirichlet condition (fixed pressure).type: "flux": Neumann condition (fixed fluid flux).
thermal: controls temperature/heat flux at this group.type: "temperature": Dirichlet condition (fixed temperature).type: "flux": Neumann condition (fixed heat flux).
A group with only hydraulics affects pressure alone; a group with only thermal affects temperature alone; a group with both applies both conditions over the same geometry. Each block carries its own function/values (and, for hydraulics, an optional constraints block — see Constraints below).
Value (Required) and Function (Optional) Specification:
The function applied to the nodes is determined by the field function. Each group should contain a field named "values" which depends on the type of function being applied.
-
function:"constant"- Constant value. Default if function not specified.
-
values:[specified value]Single value float applied to all nodes in the group.
-
function:"linear"- Linearly changing with time.
-
values:[slope, intercept]defines$y(t) = \text{slope} \cdot t + \text{intercept}$ .
-
function:"gradient"- Linearly changing in space following
$y = y_0 + m (g - \min(g))$ . -
values:[direction, reference value, slope]-
direction: 3x1 list of floats defining a vector in the gradient direction,$\vec{s}$ . Automatically normalized. Defines local coordinate system$g = \vec{X}\cdot \vec{s}$ . -
reference value: The reference value of the gradient at the minimum of$g$ within the specified nodes,$y_0$ . -
slope: gradient$m$ along$g$ .
-
- Linearly changing in space following
-
function:"ramp"- Linear increase to a value
$y_{ramp}$ over time period$t_{ramp}$ . -
values:[[y0, y1], t_ramp]defines:$\quad y(t) = y_0 + \frac{t}{t_{ramp}}(y_1 -y_0)\quad \forall t<t_{ramp}$ $\quad y(t) = y_1 \quad \forall t\geq t_{ramp}$ .
- Linear increase to a value
-
function:"table"- Accepts a series of times and values, linearly interpolating between them. 0 is assumed before the first listed time. The function is assumed constant beyond the final time listed in the table.
-
values:[[t_0, t_1, ... , t_n], [y_0, y_1, ... , y_n]]in which$t_i$ are a list of increasing times and$y_i$ are the corresponding value at that time. - RAFT indexes all times
$t_i$ to ensure that timesteps occur at those specific times and the timestepping code does not step over them.
-
function:"external"- The value is set by an external simulator at each coupling step through the Coupling API.
- Requires a
label, unique among all labeled groups. Allowed types:hydraulics"pressure"or"flux", andthermal"temperature".constraintsare allowed on a"flux"group. - A flow rate is given to the API as a total for the group in kg/s and spread over the group's nodes, line or face.
-
interpolation(string, default:"step"):"step"holds the new value over the whole coupling step;"linear"ramps from the last accepted value to the new one. The first coupling step is always stepwise. -
valuesis optional; if given, it is used as a constant when the config is run directly withuv run -m geg_raft.
Label Specification (Optional):
Flow boundary condition groups can optionally be marked with a label: "groupname" entry. If they are marked with a label, the group pressure, flow, and temperatures will be output to outflow.log in the output directory. Outputs from each group are summarized as:
- groupname_pressure: arithmetic mean of pressure over the group nodes. Note that this mean is not weighted by nodal area, and thus caution should be used when examining this value over pressure faces with non-uniform meshes.
- groupname_flow: sum of flow rates over the group nodes.
- groupname_temperature: flow-weighted average temperature over the group nodes.
Constraints
Constraints are limits placed on a hydraulics block with type: "flux". A block with constraints cannot use the "gradient" function.
maximum_pressure/minimum_pressure(float, optional): Pressure limits at the wellbore nodes. Either may be omitted to leave that side unbounded.
The group follows its specified fluid flux until any node's pressure reaches maximum_pressure or minimum_pressure, at which point the group switches to a fixed-pressure condition according to which bound was violated. It switches back to the original flux condition once the flux implied by holding that pressure would exceed the originally specified flux target. Each group is evaluated collectively - any one pressure node exceeding the constraints triggers the swap. For fluid flux constraints, line and face geometry types are integrated over the line/face and the prescribed integrated total flux is compared against the current integrated total flux.
Only one switch is permitted per timestep to avoid oscillation between the two states, so tighten the timestep if a run needs faster response at the switch point. Wellbore groups are included when labeling groups for outflow.log.
Physics switches for each domain: matrix, fractures, and wells. Fractures and wells inherit any field not set for them from matrix, so a block is only needed where a domain differs.
physics:
matrix: # frozen pressure field, conduction only
flow: off
heat: transient
advection: off
wells:
flow: steady
advection: onflow(string, default:"transient"): Pressure equation mode,"off","steady"or"transient".heat(string, default:"transient"): Temperature equation mode,"off","steady"or"transient".advection(on/off, default:off): Heat advection. Enthalpy outflow at fluid boundaries without a thermal BC only applies on nodes in domains with advection on.
An off field holds its initial values in that domain, and its equations are not assembled, so it costs no solver time. Its values still enter property evaluations (e.g. density), so advection with flow: off transports heat with the Darcy flux of the frozen pressure field. A field that is off in every domain skips its solve entirely, giving a single-physics solver.
Fracture/well-matrix coupling is assembled for a field if either side solves it, and includes advective exchange if either side has advection on.
Simulation controls
t_start(float, default:0.0): Start time of the simulation.t_end(float, default:100.0): End time of the simulation.timestep(float, default:1.0): Simulation timestep.timestep_min(float, default:1.0): Minimum allowed timestep.timestep_max(float, default:1.0): Maximum allowed timestep.
Output Controls
-
output_frequency(integer, default:1): Controls how often outputs are written (every$N$ timesteps). -
output_vtk(integer/boolean, default:0): If set to1, enables writing mesh and solution fields to.vtkfiles for visualization. -
output_viscosity(integer/boolean, default:0): If set to1, enables output of fluid viscosity fields. -
output_log(integer/boolean, default:0): If set to1, logs console output to a file in the output directory. -
output_directory(string, optional): Custom output directory path. Defaults tooutputs/under the repository root.
Physical controls
-
rate_order(integer, default:1): The approximation order of rate of change. Accepts1for a 1st order backwards Euler approximation, or2for a 2nd order backwards Euler approximation. -
gravity(float, default:0.0): Set the magnitude of the acceleration due to gravity in$\text{m}/\text{s}^2$ , typically-9.81. Gravity is assumed to act in the z-axis in 3D and the y-axis in 2D. -
axisymmetric_on(integer/boolean, default:0): Set to1to solve the axisymmetric case. Only valid in 2D analysis.
Numerical solver controls
-
solver_type(string, default:"operator_split"): Type of time integration solver. Options are"operator_split"or"monolithic". Themonolithicsolver solves pressure and temperature together in a single coupled system for the current timestep. Theoperator_splitsolver uses an operator splitting scheme, extrapolating temperature to the current timestep, solving pressure with the extrapolated temperature, then updating temperature with the new pressure. See Time Discretization and Solution Scheme for more details. -
rel_error_T(float, default:1.0e-2): Relative error tolerance used for temperature extrapolation checks ("operator_split"solver only). -
iterative_controls(dictionary): Non-linear Newton-Raphson solver settings. Because fluid properties are nonlinear functions of pressure and temperature, both solver types use these controls:"monolithic"for its single coupled solve, and"operator_split"for each of its two per-field (pressure, then temperature) sub-solves.-
NR_tol(float, default:1.0e-6): Newton-Raphson residual tolerance. -
iter_max(integer, default:100): Maximum number of iterations per timestep. -
aitken_relaxation(integer/boolean, default:1): Turn on (1) or off (0) Aitken's$\Delta^2$ relaxation for non-linear convergence. -
NR_step(float, default:1.0): Newton-Raphson step/line-search size; scales each iteration's solution update before any Aitken relaxation is applied.
-
raft.RaftModel couples RAFT to an external simulator running in the same Python process that sets the boundary conditions. The RaftModel relies on the external simulator to determine when a coupling timestep is converged and requires an explicit call to accept the trial state and proceed to the next timestep. Every solve restarts from the last accepted state, so it can be repeated as often as needed.
import geg_raft as raft
model = raft.RaftModel("config_example_AGS_coupled.yaml", t_start=0.0)
for t_start, t_end in coupling_steps:
while not converged:
bcs = {"inlet": {"p": p_in, "T": T_in, "q": q_in}, "outlet": {"p": p_out, "T": T_out, "q": q_out}}
results = model.solve(t_start, t_end, bcs)
... # update the plant from results["outlet"]["T"], etc.
model.get_fresh() # accept the step and write its outputRaftModel(config_name, t_start, config_dir=None, verbosity="full"): preprocesses the config, assigns initial conditions att_startand writes output frame 0. The config'st_startis replaced and itst_endis unused.verbositytakes"quiet","lite"or"full", as for--verbosity.solve(t_start, t_end, bcs): advances from the last accepted state to exactlyt_endand returns the boundary values there.t_startmust equal the last accepted time.bcsmust contain every label of a group with an"external"field, and only those. Each entry givesp(Pa),T(K) andq(kg/s, positive into the domain); RAFT uses the ones matching the group's types and ignores the rest.- Returns, for each label,
pandT(arithmetic mean over the group's nodes, not flow-weighted),q(summed over the nodes, kg/s, positive into the domain) andmode, the active hydraulic condition:"flux","pressure"(for a pressure group, or a flux group held at a pressure constraint) or"none"for a thermal-only group. - If the solver fails at
timestep_min,solveraisesraft.subsurface.TimestepErrorand the accepted state is unchanged, so the step can be retried, for example with a shorter coupling step.
get_fresh(): accepts the lastsolveand writes one output frame at its end time, sooutput_frequencycounts coupling steps. Calling it without a newsolveraises an error.solve_stats: what the lastsolvedid internally, asraft.subsurface.StepStats:accepted_stepsanddt_accepted: the number and sizes of the internal timesteps taken.attempts: every timestep solve, including rejected ones;cut_extrapolationandcut_newtoncount rejections for temperature extrapolation error and Newton–Raphson failure.constraint_switches: extra solves after a wellbore constraint switched.dt_min_proceeds: steps accepted attimestep_mindespite an error above tolerance.wall_time: seconds spent in thesolve.
well_profiles(): oneWellProfileper well, for the pending trial, or else the last accepted step. Nodes run from the well's first alignment point:s(distance along the well),coords,p,Tandinside(whether the node lies in the rock domain). Element values sit ats_mid:q(mass flow rate in the direction of increasings, kg/s),reynoldsandheat_transfer_coefficient(well to rock). These are the same values written toWell.vtk.
Notes:
- RAFT chooses its own timesteps inside each coupling step and lands exactly on
t_end. A coupling step longer than the internal timestep takes several internal steps, and eachsolverepeats all of them, so the iteration cost grows with the number of internal steps per coupling step. run.logis written only while RAFT's own calls run; anything the external simulator prints is not captured.scripts/coupling_example.pyruns the AGS example against a simple plant heat exchanger:uv run python scripts/coupling_example.py.
Gmsh is not a part of RAFT, but to simplify mesh generation the script scripts/raft_to_geo.py is provided which generates a Gmsh .geo and .msh files. Gmsh is not provided with raft and requires separate download and installation. Meshing by hand or from another source is still supported, this script is provided as a convenient option to keep the mesh and config files synchronized. The script raft_to_geo.py reads the config file and generates corresponding files to ensure that the mesh contains discretized boundary condition geometries, fractures, and region boundaries:
- nodes are placed exactly where
coordsboundary conditions exist - element edges are placed exactly along the specifications of
lines, fracture lines and faces in 2D and 3D respectively, well alignments in 3D, and region boundary edge lines and faces in 2D and 3D respectively
Explicit discretization of these features reduces the error introduced by the mesh and ensures consistency as the mesh is refined.
Running the script:
uv run just geo **config file name** **options**Example:
uv run just geo config_example_2D -o 2D_generated
This generates config/2D_generated.geo and the matching .msh using the specifications from config_example_2D. The file name defaults to the name specified in mesh: file, unless an alternative name is passed with the flag -o **alternative name**. Existing files are never overwritten without -f flag.
The just geo recipe runs uv run --with Gmsh scripts/raft_to_geo.py <config> --mesh, which pulls in Gmsh for that command only, and passes any extra flags through. Script names default to config/<config name>.yaml. The .msh output is Version 2.2 ASCII with T3 triangles in 2D and tetrahedra in 3D. Quadrilateral Q4 elements can be specified in 2D with --quads. raft_to_geo.py does not support meshing arbitrary hexahedral B8 elements, but they are supported by RAFT if supplied by custom meshing.
The outer boundary, required by the script. box takes two opposite corners; polyhedron, sphere and cylinder take the same values as the equivalent region shapes.
mesh:
domain:
shape: "box"
values: [[-51, 0], [102, 75]] # [[xmin, ymin, zmin], [xmax, ymax, zmax]]; drop z in 2DElement sizes, each overridable from the command line. Only outer is required.
mesh:
sizing:
outer: 10 # size far from any feature
frac: [[0.05, 0.05, 1, 10], [0.2, 5, 5, 5]] # size profile off the fractures
bc: 0.5 # a bare number is one stage over `transition`
well: [[5, 10], [5, 50]] # size profile off the wells (3D only)
transition: 25 # stage length for bare-number profiles (default: 5*outer)
region_max: 3 # coarsest size on a region boundary
boundary_growth: 0.25 # how strongly region boundaries follow nearby features
quads: false # Q4 elements instead of T3 (2D only)A profile outer over outer over the 5 m after that. frac, bc and well are independent, so fractures may be finer than boundary conditions or wells, or the other way around.
Region boundaries are refined according to their proximity to fractures, wells and boundary conditions, so an interface near a fracture is resolved more finely than one far away. region_max caps that refinement and boundary_growth sets how strongly it follows the nearby feature. Stretches of a region boundary that lie on the domain boundary are left at outer.
| Option | Effect |
|---|---|
config |
Config file; a bare name resolves to config/<name>.yaml |
-o, --output |
Output .geo; a bare name resolves into config/ (default: the stem of mesh.file) |
--mesh |
Also run Gmsh and write the .msh |
-f, --force |
Overwrite existing output files |
--size-outer |
Overrides sizing.outer |
--size-frac, --dist-frac |
Fracture sizes and stage lengths, comma separated (e.g. --size-frac 0.05,0.05,1,10 --dist-frac 0.2,5,5,5) |
--size-bc, --dist-bc |
The same for point and line boundary conditions |
--size-well, --dist-well |
The same for wells |
--transition |
Stage length when only sizes are given |
--size-region-max |
Overrides sizing.region_max |
--boundary-growth |
Overrides sizing.boundary_growth |
--quads |
Q4 elements instead of T3 (2D only) |
└── tango-reservoir-simulator
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── theory.md
├── pyproject.toml
├── justfile
├── .gitignore
├── .python-version
├── .pre-commit-config.yaml
├── .gitlab-ci.yml
├── config/
├── outputs/
├── scripts/
│ ├── coupling_example.py
│ ├── debug_fracture_angles.py
│ ├── raft_to_geo.py
│ ├── plot_fluid_props.py
│ └── plot_fluid_props_functionofpressure.py
├── src/
│ └── geg_raft/
│ ├── __init__.py
│ ├── __main__.py
│ ├── api.py
│ ├── logging_utils.py
│ ├── matprops.py
│ ├── matrixassembly.py
│ ├── meshprocessing.py
│ ├── parseboundaryconditions.py
│ ├── postprocessing.py
│ ├── preprocessing.py
│ ├── py.typed
│ ├── shapefunctions.py
│ ├── solvers.py
│ ├── spyder_runfile.py
│ ├── subsurface.py
│ └── writevtk.py
├── tests/
│ ├── __init__.py
│ ├── test_simulation.py
│ ├── test_checks.py
│ ├── test_wellbore.py
│ ├── test_configs/
│ └── test_demo.py
└── uv.lock
View CONTRIBUTING.md and install the git hooks: uv run prek install and uv run prek install --hook-type pre-push
-
Tests:
uv run pytest -
Linting:
uv run ruff check . -
Formatting:
uv run ruff format .(use--checkto verify without modifying) -
Type checking:
uv run mypy .
If RAFT contributes to your work, please cite it using the metadata in CITATION.cff; GitHub shows a "Cite this repository" button for it.
Copyright © 2026 ETH Zurich. Author: Bruce Gee, Geothermal Energy and Geofluids (GEG) group, Department of Earth and Planetary Sciences. Maintainer: Chad Baker.
RAFT is licensed under the Apache License, Version 2.0; see LICENSE.