fdata: FEHM input file manipulation

This module contains classes and methods for the reading, writing, construction and manipulation of FEHM input files.

An FEHM input file corresponds in PyFEHM to a collection of zones (fzone), macros (fmacro), boundary conditions (fboun), initial conditions (fincon) and other objects. These are all linked together, along with an FEHM grid object (fgrid), to the central fdata structure. Within this framework, zones are linked to macros, nodes are linked to zones and initial conditions, etc. The user is permitted to, say, choose a node and establish which zones and macros it is linked to.

For the purposes of this manual, the variable dat will be assumed to refer to a previously defined fdata object.

Zones

Zone object, a tool for defining sets of nodes to which specific properties can be assigned via various macros. (see macro FEHM user manual macro ZONE or ZONN). For the purposes of this manual, the variable zn will be assumed to refer to a previously defined fzone object.

There are several ways to define a zone in FEHM. The default definition (here, assigned fzone.type = 'rect') is that of a box, edges aligned along the coordinate axes, that contains all nodes desired to be in that zone. Alternative definitions include listing those nodes to be included in the zone (type = 'nnum') or the coordinates of those nodes (type = 'list').

Zones are created and associated with an fdata object using fdata.add(). All zones added to the fdata object appear in fdata.zonelist and fdata.zone attributes. Zones in fdata.zone are accessed by either zone index or zone name, e.g., fdata.zone['xmin'] or fdata.zone[12].

class fdata.fzone(index=None, type='', points=[], nodelist=[], file='', name='')

FEHM Zone object.

Attributes

fzone.index

(int) Integer number denoting the zone.

fzone.type

(str) String denoting the zone type. Default is ‘rect’, alternatives are ‘list’, ‘nnum’

fzone.name

(str) Name of the zone. Will appear commented beside the zone definition in the input file. Can be used to index the fdata.zone attribute.

fzone.node

(dict[fnode]) Dictionary of nodes contained within the zone, indexed by node number.

fzone.nodelist

(lst[fnode]) List of nodes contained within the zone.

fzone.file

(str) File name if zone data is or is to be contained in a separate file. If file does not exist, it will be created and written to when the FEHM input file is being written out.

Material attributes

In assigning these attributes, macros corresponding to the zone object will be automatically created. For example, assigning a value to the permeability attribute will create the corresponding permeability macro.

fzone.permeability

(fl64,*lst*) Permeability properties of zone.

fzone.conductivity

(fl64,*lst*) Conductivity properties of zone.

fzone.density

(fl64) Density of zone.

fzone.specific_heat

(fl64) Specific heat of zone.

fzone.porosity

(fl64) Porosity of zone.

fzone.youngs_modulus

(fl64) Young’s modulus of zone.

fzone.poissons_ratio

(fl64) Poisson’s ratio of zone.

fzone.thermal_expansion

(fl64) Coefficient of thermal expansion of zone.

fzone.pressure_coupling

(fl64) Pressure coupling term of zone.

fzone.Pi

(fl64) Initial pressure in zone.

fzone.Ti

(fl64) Initial temperature in zone.

fzone.Si

(fl64) Initial saturation in zone.

Methods

fzone.rect(p1, p2)

Create a rectangular zone corresponding to the bounding box delimited by p1 and p2.

Parameters:
  • p1 (ndarray) – coordinate of first corner of the bounding box.
  • p2 (ndarray) – coordinate of the second corner of the bounding box.
fzone.fix_temperature(T, multiplier=10000000000.0, file=None)

Fixes temperatures at nodes within this zone. Temperatures fixed by adding an HFLX macro with high heat flow multiplier.

Parameters:
  • T (fl64) – Temperature to fix.
  • multiplier (fl64) – Multiplier for HFLX macro (default = 1.e10)
  • file (str) – Name of auxiliary file to save macro.
fzone.fix_pressure(P=0, T=30.0, impedance=1000000.0, file=None)

Fixes pressures at nodes within this zone. Pressures fixed by adding a FLOW macro with high impedance.

Parameters:
  • P (fl64) – Pressure to fix. Default is 0, corresponding to fixing initial pressure.
  • T (fl64) – Temperature to fix (default = 30 degC).
  • impedance (fl64) – Impedance for FLOW macro (default = 1.e6)
  • file (str) – Name of auxiliary file to save macro.
fzone.fix_displacement(direction, displacement, file=None)

Fixes displacement at nodes within this zone. Displacements fixed by adding a STRESSBOUN macro.

Parameters:
  • direction (str, int) – Direction in which displacement is fixed. Specify as string or integer, e.g., 1 = ‘x’, 2 = ‘y’, 3 = ‘z’.
  • displacement (fl64) – Fixed displacement
  • file (str) – Name of auxiliary file to save macro.
fzone.fix_stress(direction, stress, file=None)

Fixes displacement at nodes within this zone. Displacements fixed by adding a STRESSBOUN macro.

Parameters:
  • direction (str, int) – Direction in which stress is fixed. Specify as string or integer, e.g., 1 = ‘x’, 2 = ‘y’, 3 = ‘z’.
  • stress (fl64) – Fixed stress
  • file (str) – Name of auxiliary file to save macro.
fzone.roller(direction=None, file=None)

Assigns a roller boundary condition to the zone (zero displacement in normal direction).

Parameters:direction (str, int) – Normal of roller. Specify as string or integer, e.g., 1 = ‘x’, 2 = ‘y’, 3 = ‘z’. Defaults to zone normal for ‘XMIN’, ‘ZMAX’ etc.
fzone.free_surface(direction=None, file=None)

Assigns a free surface boundary condition to the zone (zero stress in normal direction).

Parameters:direction (str, int) – Normal of free surface. Specify as string or integer, e.g., 1 = ‘x’, 2 = ‘y’, 3 = ‘z’. Defaults to zone normal for ‘XMIN’, ‘ZMAX’ etc.
fzone.plot(save='', angle=[45, 45], color='k', connections=False, equal_axes=True, xlabel='x / m', ylabel='y / m', zlabel='z / m', title='', font_size='small')

Generates and saves a 3-D plot of the zone.

Parameters:
  • save (str) – Name of saved zone image.
  • angle ([fl64,fl64], str) – View angle of zone. First number is azimuth angle in degrees, second number is tilt. Alternatively, if angle is ‘x’, ‘y’, ‘z’, view is aligned along the corresponding axis.
  • color (str, [fl64,fl64,fl64]) – Colour of zone.
  • connections (bool) – Plot connections. If True all connections plotted. If between 0 and 1, random proportion plotted. If greater than 1, specified number plotted.
  • equal_axes (bool) – Force plotting with equal aspect ratios for all axes.
  • xlabel (str) – Label on x-axis.
  • ylabel (str) – Label on y-axis.
  • zlabel (str) – Label on z-axis.
  • title (str) – Title of plot.
  • font_size (str, int) – Size of text on plot.

Example:

zn.plot(save='myzone.png', angle = [45,45], xlabel = 'x / m', font_size = 'small', color = 'r')

fzone.topo(save='', cbar=True, equal_axes=True, method='nearest', divisions=[30, 30], xlims=[], ylims=[], clims=[], levels=10, clabel='', xlabel='x / m', ylabel='y / m', zlabel='z / m', title='', font_size='small')

Returns a contour plot of the top surface of the zone.

Parameters:
  • divisions ([int,int]) – Resolution to supply mesh data.
  • method (str) – Method of interpolation, options are ‘nearest’, ‘linear’.
  • levels (lst[fl64], int) – Contour levels to plot. Can specify specific levels in list form, or a single integer indicating automatic assignment of levels.
  • cbar – Add colour bar to plot.
  • type – bool
  • xlims ([fl64, fl64]) – Plot limits on x-axis.
  • ylims ([fl64, fl64]) – Plot limits on y-axis.
  • clims ([fl64,fl64]) – Colour limits.
  • save (str) – Name to save plot. Format specified extension (default .png if none give). Supported extensions: .png, .eps, .pdf.
  • xlabel (str) – Label on x-axis.
  • ylabel (str) – Label on y-axis.
  • title (str) – Plot title.
  • font_size (str, int) – Specify text size, either as an integer or string, e.g., 10, ‘small’, ‘x-large’.
  • equal_axes (bool) – Specify equal scales on axes.

Example:

dat.zone[2].topo('zoneDEMtopo.png',method = 'linear')

fzone.what

Print to screen information about the zone.

Examples

1. Create a rectangular zone that encompasses all nodes within a horizontal reservoir. Bounding box limits are used as inputs for rect().

zn = fzone( type ='rect', index = 5, name = 'res')

zn.rect([0.1,0.1,2200.],[5000.1,5000.1,2400.])

dat.add(zn)

2. Create a zone named injectors with index 10 and comprising two previously identified nodes. The zone information will be written out to the auxiliary file zones.macro. The zone is created and added to the dat in a single step.

nd1 = geo.node_nearest_point([100,200,-1500])

nd2 = geo.node_nearest_point([-500,400,-1500])

dat.add(fzone(index=10, type='nnum', name='injectors', nodelist=[nd1.index, nd2], file='zones.macro'))

  1. For the zone named ZMAX, fix its temperature to 90degC.
dat.zone['ZMAX'].fix_temperature(T=90.)
  1. Assign anisotropic permeability to the zone caprock
dat.zone['caprock'].permeability=[1.e-19,1.e-19,1.e-21]
  1. Assign PyFEHM defined zone XMIN as a roller boundary condition (zero displacement in x-direction)
dat.zone['XMIN'].roller()

Macros

The macro object, this is how the majority of FEHM’s text inputs are defined.

A macro is a way of telling FEHM to do something specific. It may be as simple as assigning a standard permeability value to every node in the grid. It may be as specific as assigning a stress boundary condition to one edge of the model, a source or sink to one or many nodes, or elastic and rock properties to a particular zone.

The attribute type is set when a new macro is created. Macro names in PyFEHM and FEHM are identical. Thus, to generate a macro object for permeability properties, one supplies the command fmacro('perm').

Macros are applied to a specific spatial domain. This may be the entire model, a previously defined zone, or a set of nodes. This spatial assignment occurs is defined in fmacro.zone.

The macro must be supplied with several pieces of information, informing its operation. E.g., the perm macro requires permeabilities, the rock macro requires density, porosity and specific heat, and the grad macro requires information about an initial gradient in some variable. These properties are set in fmacro.param, a dictionary with keys corresponding to the required pieces of information.

class fdata.fmacro(type='', zone=[], param=[], subtype='', file=None, write_one_macro=False)

FEHM macro object.

Attributes

fmacro.type

(str) Name of the macro. Macro names are identical to those invoked in FEHM.

fmacro.zone

(fzone, lst[fzone], tuple[int,int,int], zone key) The zone, zones or nodes to which the macro is assigned. Note, only permmodel and rlp can be assigned lists of zones. Optionally, a key (index or string) may be passed, in which case the zone will be retrieved when the macro is added to the model.

fmacro.param

(dict[fl64]) A dictionary of values defining the operation of the macro. See table below for macro-specific dictionary keys.

fmacro.subtype

(str) Macro subtype, required for STRESSBOUN or BODYFORCE macros.

fmacro.file

(str) File string where information about the macro is stored. If file does not currently exist, it will be created and written to when the FEHM input file is written.

Methods

fmacro.what

Return a summary of the macros function.

Macro parameter lists

The table below shows the parameter names available to be set for each macro. Parameters are accessed/set via the param attribute, e.g., to set the density property for a ROCK macro write

mcr = fmacro('rock')

mcr.param['density']=2500

Warnings will be printed if a parameter is not set when the FEHM data file is written.

Macro Parameters (Units) FEHM variable Notes
pres pressure (MPa) PHRD  
  temperature (degC) TIND  
  saturation IEOSD  
perm kx (m^2, log10(m^2)) PNXD  
  ky PNYD  
  kz PNZD  
cond cond_x (W/m/K) THXD  
  cond_y THYD  
  cond_z THZD  
flow rate (kg/s, MPa) SKD Fixed rate or pressure depending on AIPED.
  energy (MJ/kg, degC) EFLOW >0 = enthalpy, <0 = temperature.
  impedance AIPED Determine generator type.
rock density (kg/m^3) DENRD  
  specific_heat (J/kg/K) CPRD  
  porosity PSD Set negative to remove node from simulation.
grad reference_coord (m) CORDG  
  direction IDRG 1,2,3 = x,y,z
  variable IGRADF 1,2,3,9 = P,T,S,P_co2 / 4,5,6,10 = fixed boun P,T,S,P_co2
  reference_value (unit) VAR0  
  gradient (unit/m) GRAD1  
hflx heat_flow (MW) QFLUX  
  multiplier QFLXM  
biot thermal_expansion (/K) ALPHA  
  pressure_coupling PP_FAC  
elastic youngs_modulus (MPa) ELASIC_MOD  
  poissons_ratio POISSON  
co2frac water_rich_sat FW  
  co2_rich_sat FL Set non-zero at co2 injectors.
  co2_mass_frac YC  
  init_salt_conc (ppm) CSALT  
  override_flag INICO2FLG  
co2flow rate (kg/s, MPa) SKTMP  
  energy (MJ/kg, degC) ESKTMP  
  impedance AIPED Similar operation to flow.
  bc_flag IFLG_FLOWMAC  
co2diff diffusion DIFF  
  tortuosity TORTCO2  
co2pres pressure (MPa) PHICO2  
  temperature (degC) TCO2  
  phase ICES  
stressboun value (m, MPa, MPa/m) BOUNVAL Fixed displacement, force or stress gradient.
  direction KQ 1,2,3 = x,y,z displacement, -1,-2,-3 = x,y,z force.
  sdepth (m) SDEPTH Only used for subtype='lithograd'.
  gdepth (m) GDEPTH Only used for subtype='lithograd'.
bodyforce fx (MN, m/s^2) FX Body force in x-direction (acceleration if subtype='acceleration')
  fy (MN, m/s^2) FY Body force in y-direction.
  fz (MN, m/s^2) FZ Body force in z-direction.

Examples

  1. An initial conditions macro, PRES, is created, and assigned to the pre-existing zone 10. The macro is assigned parameters, found by looking up pres in the table above, and added to dat.

mcr=fmacro('pres')

mcr.zone=dat. zone[10]

mcr.param['pressure'] = 1.

mcr.param['temperature'] = 80.

mcr.param['saturation'] = 1.

dat.add(mcr)

  1. A rock properties macro, ROCK, is created, assigned zone 20 and properties, and added to dat.

mcr=fmacro('rock', zone=20, param=(('density',2500), ('porosity',0.1), ('specific_heat',800)))

dat.add(mcr)

  1. A mass source macro, FLOW, is created, assigned to the injection zone, assigned properties, and added to dat in a single command.
dat.add(fmacro('flow', zone='injection', param=(('rate',-2), ('energy',-50), ('impedance',100))))
  1. Creation of a lithograd stress boundary condition, STRESSBOUN.

mcr=fmacro('stressboun', zone='xmin', subtype='lithograd')

mcr.param['sdepth'] = 0.

mcr.param['gdepth'] = 0.

mcr.param['direction'] = 1

mcr.param['value'] = 0.03

  1. Specifying body forces corresponding to moon-strength gravitational acceleration.

mcr=fmacro('bodyforce', subtype='acceleration')

mcr.param['fx'] = 0.

mcr.param['fy'] = 0.

mcr.param['fz'] = -1.62

Models

The model object, this is how the some of FEHM’s text inputs are defined.

Models are similar to macros in function but are more flexible in their definition of physical behaviour. For example, the definition of thermal conductivity through the COND macro is rather narrow; constant values are supplied. However, by invoking the VCON macro, the user can choose between multiple models for thermal conductivity behaviour. The user can specify a model index - say 2, for square root variation of thermal conductivity with liquid saturation - and then pass the necessary parameters for the model.

Additional models exist to define relative permeability in terms of saturation (RLP), porosity in terms of fluid pressure (PPOR), or permeability in terms of stress (PERMMODEL).

class fdata.fmodel(type='', zonelist=[], param=[], index=None, file=None)

Model object, used in a variety of macro definitions.

Model objects should have:
  • a type for the macro
  • a list of zones to which the model is assigned.
  • an index for the specific model.
  • a dictionary of parameters for the model.

Attributes

fmodel.type

(str) Name of the macro for this model. Macro names are identical to those invoked in FEHM.

fmodel.zonelist

(list) A list of zones to which the model is applied.

fmodel.param

(dict[fl64]) A dictionary of values defining the operation of the macro. See table below for macro-specific dictionary keys.

fmodel.index

(int) Index of the model to be invoked.

fmodel.file

(**)

Available models

Currently, models are available for thermal conductivity, permeability, porosity and relative permeability. Information about the various models and their parameters is available through the fdata.help attribute.

Examples

  1. Adding a model in which thermal conductivity depends linearly upon temperature.

vcon=fmodel(type='vcon',index=1)

vcon.zonelist=dat.zone['salt']

vcon.param['T_ref']=30.

vcon.param['cond_ref']=2.

vcon.param['dcond_dT']=0.2

dat.add(bc)

  1. Creation of a relative permeability model number 2, RLP, for the entire model (default when zone is not specified). See appendix for model-specific rlp parameter names.
rlp=fmodel('rlp',index = 2, param=(('resid_liq_sat',0.2), ('resid_vap_sat',0.), ('cap_pres_zero_sat',1.e4), ('sat_zero_cap_pres',1.))
  1. Accessing help on all permeability models.
dat.help.permmodel()
  1. Accessing help on variable porosity model -1.
dat.help.pormodel(-1)

Boundary conditions

Boundary conditions are applied to zones, and involve fixing some variable according to supplied time-series data. In contrast to other macros, one boundary condition may be applied to multiple zones.

The fboun object is supplied a vector of times, corresponding to values of one or more variables. This defines the time evolution of the variable, with step-changes (fboun.type='ti') or linear interpolation (type='ti_linear') between elements in fboun.times.

The fboun.variable attribute comprises a list of variable vectors. Each variable vector first contains the FEHM boun variable keyword followed by the vector of values corresponding to fboun.times. For example, a fixed temperature sequence would be supplied variable= [['t',100,80,90],] (note the nesting of the lists).

class fdata.fboun(zone=[], type='ti', times=[], variable=[], file=None)

Boundary condition object.

Attributes

fboun.type

(str) Boundary condition type, ‘ti’ = step changes, ‘ti_linear’ = linear changes.

fboun.zone

(lst[fzone]) List of zones to which the boundary condition is to be applied.

fboun.variable

(lst[lst[str,fl64,...]]) List of lists of boundary data. Each list begins with a string denoting the boundary condition variable, and is followed by the time-series data, e.g., [‘sw’,0.2,0.5,0.8].

fboun.times

(lst[fl64]) Vector of times.

fboun.n_times

(int) Length of time-series.

Methods

fboun.what

Print information about the boundary condition object.

Examples

  1. Create a boundary condition for a fixed temperature sequence and add it to dat.

bc=fboun(type='ti')

bc.zone=dat.zone['base']

bc.times=[0,10,100,1000]

bc.variable= [['t',20,30,50,80]]

dat.add(bc)

  1. Create a boundary condition for both temperature and pressure. Use linear interpolation between times.
bc=fboun(type='ti_linear', zone=2, times=[0,10,20], variable=[['t',100,80,100], ['pw',15,10,15]])

History output

History output object, makes request for history data to be output (see macro HIST).

This data type outputs specified variables (e.g., temperature, permeability) for particular nodes and zones at specified times (one file = one variable). The data can be output in several formats (all of which are readable by PyFEHM) and at specified times.

Output requests for specific nodes and zones is supplied through the NODE and FLXZ macros. PyFEHM writes takes care of these macros within the scope of the fhist object.

class fdata.fhist(format='tec', timestep_interval=1, time_interval=1e+30, variables=[], nodelist=[], zonelist=[], zoneflux=[], azonelist=[])

FEHM history output object.

Attributes

fhist.format

(str) File format for contour output: ‘tecplot’, ‘csv’, ‘surfer’

fhist.time_interval

(flt) Time interval to output data.

fhist.timestep_interval

(int) Time step interval to output data.

fhist.variables

(lst[str])List of variables to write contour data for, e.g., [‘temperature’,’pressure’]

fhist.node

(dict[fnode]) Dictionary of nodes, indexed by node number, for which history output requested.

fhist.zone

(dict[fzone]) Dictionary of zones, indexed by number and name, for which history output is required.

fhist.zoneflux

(lst[fzone,int]) List of zone objects for which zone flux output required.

fhist.nodelist

(list[fnode]) list of node objects for which history output requested.

fhist.zonelist

(lst[fzone]) List of zone objects for which history output required.

Methods

fhist.options

Print out eligible variables for output.

fhist.what

Print out information about the attribute.

Examples

  1. Request temperature, pressure and flow history output for specific nodes at every time step.

dat.hist.variables.append(['temperature','pressure','flow'])

dat.hist.timestep_interval=1

dat.hist.nodelist.append([10, 15, 20])

nd = dat.grid.node_nearest_point([200,300,400])

dat.hist.nodelist.append(nd)

  1. Request CO2 and water source/sink history output for specific zones every 10 days.

dat.hist.variables.append(['cflz','zfl'])

dat.hist.time_interval=10

dat.hist.zoneflux.append(10)

dat.hist.nodelist.append(dat.zone['injection'])

Contour ouput

class fdata.fcont(format='surf', timestep_interval=1000, time_interval=1e+30, time_flag=True, variables=[], zones=[])

Contour output object, makes request for contour data to be output (see macro CONT).

This data type outputs specified variables (e.g., temperature, permeability) for x,y,z or node locations at fixed times (one file = one time). The data can be output in several formats (all of which are readable by PyFEHM) and at specified times.

Attributes

fcont.format

(str) File format for contour output: ‘tec’, ‘surf’, ‘avs’, ‘avsx’

fcont.time_interval

(flt) Time interval to output data.

fcont.timestep_interval

(int) Time step interval to output data.

fcont.variables

(lst[str])List of variables to write contour data for, e.g., [‘temperature’,’pressure’]

fcont.time_flag

(bool) Set to True to include in output title.

fcont.zones

(lst[fzone]) List of zone objects for which contour data is to be written - NOT FULLY SUPPORTED.

Methods

fcont.options

Print out eligible variables for output.

fcont.what

Print out information about the attribute.

Examples

  1. Request contour data to be output every 10 time steps, every 100 days, in surfer format.

dat.cont.timestep_interval=10

dat.cont.time_interval=100

dat.cont.format='surf'

dat.cont.variables.append(['temperature','permeability','displacement','co2'])

dat.cont.time_flag=True

  1. The user can force contour output to be printed at specific times by setting the :attr: .fdata.output_times attribute to a vector of times
dat.output_times=powspace(1.e1,1.e4,15,2.)

Data files

The fdata class is the central structure for collating and organising all information about a simulation. Grid information, zone definitions, boundary conditions and other macros are collected here. An fdata object is automatically created and populated when an existing input file is parsed using fdata.read(). Alternatively, an empty fdata object can be created and populated with an fgrid object, some fzone, fmacro and other objects to create a new simulation.

Just as each FEHM input file is associated with a grid file, each PyFEHM fdata object must be associated with an fgrid object. Failure to specify a grid file may lead to problems specifying other macros.

FEHM simulations can be initialised within the PyFEHM environment by writing out the fehmn.files control file and supplying a command line path to an FEHM executable. Information contained in the control file is accessed via the files attribute. The control file is automatically written out when invoking fdata.run().

PyFEHM also allows for simulation restarts from initial condition files dumped by FEHM, referred to here as incon files. An incon file is associated with the incon attribute and read in by fincon.read(). The user is permitted to read in incon files, make changes within PyFEHM, and write out a new incon file for a future simulation.

PyFEHM supports the use of FEHM’s stress and carbon dioxide modules via the strs and carb attributes, respectively.

class fdata.fdata(filename='', gridfilename='', inconfilename='', sticky_zones=True, associate=True, work_dir=None, full_connectivity=True, skip=[], keep_unknown=True)

Class for FEHM data file.

fdata.filename

(str) File name for reading and writing FEHM input text file.

fdata.gridfilename

(str) File name of FEHM grid file.

fdata.inconfilename

(str) File name of FEHM restart file.

Attributes: daughter structures

fdata.grid

(fgrid) Grid object associated with the model.

fdata.cont

(fcont) Contour output for the model.

fdata.hist

(fhist) History output for the model.

fdata.incon

(fincon) Initial conditions (restart file) associated with the model.

fdata.files

(files) Simulation execution object.

fdata.strs

(fstrs) Stress module object.

fdata.carb

(fcarb) CO2 module object.

fdata.trac

(ftrac) Species transport module object.

fdata.bounlist

(lst[fzone]) List of boundary condition objects in the model.

fdata.zone

(dict[fzone]) Dictionary of zone objects, indexed by zone number or name.

fdata.zonelist

(lst[fzone]) List of zone objects in the model.

fdata.help

(fhelp) Module for interactive assistance.

Attributes: macro lists

An FEHM simulation may contain multiple instances of the same macro, which allows assignment of differing material properties between regions, multiple regions of inflow and outflow via FLOW and BOUN, etc. Each set of macros is collected and made accessible via a list and a dictionary, denoted by fdata.macro_namelist and fdata.macro_name respectively. The list contains macros in which they were added to the fdata object or read from an input file. The dictionary is indexed by the zone number of name associated with each macro.

For example, to loop through all macros of the PERM type, one would use fdata.permlist

for perm in dat.permlist: perm.param['kx'] = 1.e-16

To access a specific ROCK macro assigned to zone 20, use the fdata.rock dictionary

dat.rock[20].param['porosity'] = -1

To access FLOW generators assigned to the previously defined ‘injection’ zone, use the fdata.flow dictionary

dat.flow['injection'].param['impedance'] = 100

For reference, the available macro lists and dictionaries are given below.

fdata.perm
fdata.permlist
fdata.pres
fdata.preslist
fdata.rock
fdata.rocklist
fdata.cond
fdata.condlist
fdata.grad
fdata.gradlist
fdata.flow
fdata.flowlist
fdata.hflx
fdata.hflxlist
fdata.biot
fdata.biotlist
fdata.elastic
fdata.elasticlist
fdata.co2frac
fdata.co2fraclist
fdata.co2flow
fdata.co2flowlist
fdata.co2pres
fdata.co2preslist
fdata.co2diff
fdata.co2difflist
fdata.stressboun
fdata.stressbounlist
fdata.permmodel
fdata.permmodellist
fdata.plasticmodel
fdata.plasticmodellist
fdata.rlp
fdata.rlplist
fdata.rlpm
fdata.rlpmlist
fdata.tpor
fdata.tporlist
fdata.vcon
fdata.vconlist
fdata.ppor
fdata.pporlist

Attributes: parameter dictionaries

FEHM provides the user with control over a variety of time stepping and solver parameters. In PyFEHM, these parameters are accessible via four dictionaries, which are automatically generated and populated with defaults when a new fdata object is created. A table of parameter names and default values is given with each of the four dictionaries below.

fdata.time

(dict[fl64,int]) Time stepping parameters (see macro TIME).

PyFEHM parameter FEHM equivalent Default value
initial_timestep_DAY DAY 1 (days)
max_time_TIMS TIMS 365 (days)
max_timestep_NSTEP NSTEP 200
print_interval_IPRTOUT IPRTOUT 1
initial_year_YEAR YEAR None
initial_month_MONTH MONTH None
initial_day_INITTIME INITTIME None
fdata.ctrl

(dict[fl64,int]) Control parameters (see macro CTRL).

PyFEHM parameter FEHM equivalent Default value
max_newton_iterations_MAXIT MAXIT 10
newton_cycle_tolerance_EPM EPM 1e-5
number_orthogonalizations_NORTH NORTH 8
max_solver_iterations_MAXSOLVE MAXSOLVE 24
acceleration_method_ACCM ACCM ‘gmre’
JA JA 1
JB JB 0
JC JC 0
order_gauss_elim_NAR NAR 2
implicitness_factor_AAW AAW 1
gravity_direction_AGRAV AGRAV 3
upstream_weighting_UPWGT UPWGT 1.0
max_multiply_iterations_IAMM IAMM 7
timestep_multiplier_AIAA AIAA 1.5
min_timestep_DAYMIN DAYMIN 1e-5 (days)
max_timestep_DAYMAX DAYMAX 30 (days)
geometry_ICNL ICNL 0
stor_file_LDA LDA 0
fdata.iter

(dict[fl64,int]) Iteration parameters (see macro ITER).

PyFEHM parameter FEHM equivalent Default value
linear_converge_NRmult_G1 G1 1e-5
quadratic_converge_NRmult_G2 G2 1e-5
stop_criteria_NRmult_G3 G3 1e-3
machine_tolerance_TMCH TMCH -1e-5
overrelaxation_factor_OVERF OVERF 1.1
reduced_dof_IRDOF IRDOF 0
reordering_param_ISLORD ISLORD 0
IRDOF_param_IBACK IBACK 0
number_SOR_iterations_ICOUPL ICOUPL 0
max_machine_time_RNMAX RNMAX 3600
fdata.sol

(dict[fl64,int]) Solution parameters (see macro SOL).

PyFEHM parameter FEHM equivalent Default value
coupling_NTT NTT 1
element_integration_INTG INTG -1

Attributes: time stepping shortcuts

Assigning final simulation time, maximum number of time steps, etc., via the dictionaries in ctrl and time involves cumbersome lookup of parameter names and then assignment. Therefore, some shortcut attributes are made available to bypass this process

fdata.ti

(fl64) Initial simulation time (shortcut), defaults to zero.

fdata.tf

(fl64) Final simulation time (shortcut).

fdata.dti

(fl64) Initial time step size (shortcut).

fdata.dtmin

(fl64) Minimum time step size (shortcut).

fdata.dtmax

(fl64) Maximum time step size (shortcut).

fdata.dtn

(int) Maximum number of time steps (shortcut).

fdata.dtx

(fl64) Time step multiplier, acceleration (shortcut).

fdata.output_times

(lst) List of times at which FEHM should produce output.

For example, writing

dat.tf=365.25*10.

dat.dti=1.

dat.dtn=500

dat.dtmax=365.25

will request the simulation to run for 10 years, with an initial time step of 1 day, a maximum time step of 1 year and to stop if it reaches 500 time steps.

The attribute output_times can be used to request output data at specific times during the simulation. Use of this attribute is incompatible with the change_timestepping method.

Attributes: flags

fdata.work_dir

(str) Directory in which to store files and run simulation.

fdata.verbose

(bool) Boolean signalling if simulation output to be printed to screen.

fdata.sticky_zones

(bool) If True zone definitions will be written to the input file immediately before they are used inside a macro.

fdata.nobr

(int) Boolean integer calling for no breaking of connections between boundary condition nodes.

fdata.nfinv

(int) Boolean integer calling for generation of finite element coefficients (not recommended, see macro NFINV).

Methods

fdata.read(filename='', gridfilename='', inconfilename='', full_connectivity=True, skip=[])

Read FEHM input file and construct fdata object.

Parameters:
  • filename (str) – Name of FEHM input file. Alternatively, supplying ‘fehmn.files’ will cause PyFEHM to query this file for input, grid and restart file names if they are available.
  • gridfilename (str) – Name of FEHM grid file.
  • inconfilename (str) – Name of FEHM restart file.
  • skip (list) – List of macro strings to ignore when reading an input file.
fdata.write(filename='', writeSubFiles=True)

Write fdata object to FEHM input file and fehmn.files file.

Parameters:
  • filename (str) – Name of FEHM input file to write to.
  • writeSubFiles (bool) – Boolean indicating whether macro and zone information, designated as contained within other input files, should be written out, regardless of its existence. Non-existant files will always be written out.
fdata.run(input='', grid='', incon='', exe='c:\path\to\fehm\fehm.exe', files=['outp', 'hist', 'check'], verbose=None, until=None, autorestart=0, use_paths=False, write_files_only=False, diagnostic=False, clean=False)

Run an fehm simulation. This command first writes out the input file, fehmn.files and this incon file if changes have been made. A command line call is then made to the FEHM executable at the specified path (defaults to fehm.exe in the working directory if not specified).

Parameters:
  • input (str) – Name of input file. This will be written out.
  • grid (str) – Name of grid file. This will be written out.
  • incon (str) – Name of restart file.
  • exe (str) – Path to FEHM executable.
  • files (lst[str]) – List of additional files to output. Options include ‘check’, ‘hist’ and ‘outp’.
  • until (func) – Name of a function defined inside the script. The function returns a boolean indicating the simulation should be halted. See tutorial 4 for usage.
  • autorestart (int) – Number of times FEHM should restart itself in attempting to find a solution.
  • use_paths (bool) – Flag to indicate that PyFEHM should favour full paths in fehmn.files rather than duplication of source files.
  • write_files_only (bool) – Flag to indicate the PyFEHM should write out input, incon, grid, fehmn.files, etc. but should not execute a simulation.
  • diagnostic (bool) – Flag to indicate PyFEHM should flash up a diagnostic window to monitor the simulation.
  • clean (bool) – Delete files after simulation ‘nop.temp’
fdata.paraview(exe='paraview', filename='temp.vtk', contour=None, history=None, show='kx', zones='none', diff=True, zscale=1.0, spatial_derivatives=False, time_derivatives=False, nodes=False, wells=None)

Exports the model object to VTK and loads in paraview.

Parameters:
  • exe (str) – Path to Paraview executable.
  • filename (str) – Name of VTK file to be output.
  • contour (fcontour) – Contout output data object loaded using fcontour().
  • history (fhistory) – History output data object loaded using fhistory().
  • show (str) – Variable to show when Paraview starts up (default = ‘kx’).
  • zones (str) – Zones to plot: ‘user’ = user-defined zones, ‘all’ = all zones except zone[0], ‘none’ (default), or list of zone objects.
  • diff (bool) – Flag to request PyFEHM to also plot differences of contour variables (from initial state) with time.
  • zscale (fl64) – Factor by which to scale z-axis. Useful for visualising laterally extensive flow systems.
  • spatial_derivatives (bool) – Calculate new fields for spatial derivatives of contour data.
  • time_derivatives (bool) – Calculate new fields for time derivatives of contour data. For precision reasons, derivatives are calculated with units of ‘per day’.
  • nodes (bool) – Show node locations (default False).
  • wells (dict) – Dictionary of well tracks ([x,y,z] column list), keyed by name.
fdata.picklable()

Call before multi-processing simulations in Windows to ensure fdata is picklable.

fdata.write_vtk(filename='temp.vtk', contour=None, diff=True, zscale=1.0, spatial_derivatives=False, time_derivatives=False)

Exports the model object to VTK.

Parameters:
  • filename (str) – Name of VTK file to be output.
  • contour (fcontour) – Contout output data object loaded using fcontour().
  • diff (bool) – Flag to request PyFEHM to also plot differences of contour variables (from initial state) with time.
  • zscale (fl64) – Factor by which to scale z-axis. Useful for visualising laterally extensive flow systems.
  • spatial_derivatives (bool) – Calculate new fields for spatial derivatives of contour data.
  • time_derivatives (bool) – Calculate new fields for time derivatives of contour data. For precision reasons, derivatives are calculated with units of ‘per day’.
fdata.add(obj, overwrite=False)

Attach a zone, boundary condition or macro object to the data file.

Parameters:
  • obj (fzone, fmacro, fmodel, fboun) – Object to be added to the data file.
  • overwrite (bool) – Flag to overwrite macro if already exists for a particular zone.
fdata.delete(obj)

Delete a zone, boundary condition or macro object from the data file.

Parameters:obj (fzone, fmacro, fmodel, fboun, list) – Object to be deleted from the data file. Can be a list of objects.
fdata.change_timestepping(at_time, new_dti=None, new_dtmax=None, new_dtx=None, new_implicitness=None, new_print_out=None)

Change timestepping during a simulation. Note, if time stepping arguments are omitted, FEHM will force output to be written at the change time. The default for all optional arguments is no change.

Parameters:
  • at_time (fl64) – Simulation time to change time stepping behaviour.
  • new_dti (fl64) – Initial time step at change time.
  • new_dtmax (fl64) – New maximum time step after change time.
  • new_dtx (fl64) – New time step multiplier at change time.
  • new_implicitness (fl64) – New implicitness factor at change time.
  • new_print_out (int) – New time step interval at which to print information.
fdata.new_zone(index=None, name=None, rect=None, nodelist=None, file=None, from_file=None, permeability=None, conductivity=None, density=None, specific_heat=None, porosity=None, youngs_modulus=None, poissons_ratio=None, thermal_expansion=None, pressure_coupling=None, Pi=None, Ti=None, Si=None, overwrite=False)

Create and assign a new zone. Material properties are optionally specified, new macros will be created if required.

Parameters:
  • index (int) – Zone index.
  • name (str) – Zone name.
  • rect (lst) – Two item list. Each item is itself a three item (or two for 2D) list containing [x,y,z] coordinates of zone bounding box.
  • nodelist (lst) – List of node objects or indices of zone. Only one of rect or nodelist should be specified (rect will be taken if both given).
  • file (str) – Name of auxiliary file for zone
  • from_file (str) – Name of auxiliary file in which to find zone information.
  • permeability (fl64, list) – Permeability of zone. One float for isotropic, three item list [x,y,z] for anisotropic.
  • conductivity (fl64, list) – Conductivity of zone. One float for isotropic, three item list [x,y,z] for anisotropic.
  • density (fl64) – Density of zone. If not specified, defaults will be used for specific heat and porosity.
  • specific_heat (fl64) – Specific heat of zone. If not specified, defaults will be used for density and porosity.
  • porosity (fl64) – Porosity of zone. If not specified, defaults will be used for density and specific heat.
  • youngs_modulus (fl64) – Young’s modulus of zone. If not specified, default will be used for Poisson’s ratio.
  • poissons_ratio (fl64) – Poisson’s ratio of zone. If not specified, default will be used for Young’s modulus.
  • thermal_expansion (fl64) – Coefficient of thermal expansion for zone. If not specified, default will be used for pressure coupling term.
  • pressure_coupling (fl64) – Pressure coupling term for zone. If not specified, default will be used for coefficient of thermal expansion.
  • Pi (fl64) – Initial pressure in the zone. If not specified, default will be used for initial temperature and saturation calculated.
  • Ti (fl64) – Initial temperature in the zone. If not specified, default will be used for initial pressure and saturation calculated.
  • Si (fl64) – Initial saturation in the zone. If not specified, default will be used for initial pressure and the saturation temperature calculated.
  • overwrite (bool) – If zone already exists, delete it and create the new one.
fdata.temperature_gradient(filename, offset=0.0, first_zone=100, auxiliary_file=None, hydrostatic=0, flip_depth_sign=False)

Assign initial temperature distribution to model based on supplied temperature profile.

Parameters:
  • filename (str) – Name of a file containing temperature gradient data. File should be two columns, comma or space separated, with elevation in the first column and temperature (degC) in the second.
  • offset (fl64) – Vertical offset added to the elevation in temperature gradient data. Useful if model limits don’t correspond to data.
  • first_zone (int) – Index of first zone created. Zone index will be incremented by 1 thereafter.
  • auxiliary_file (str) – Name of auxiliary file in which to store PRES macros.
  • hydrostatic (fl64) – Pressure at top of well profile. PyFEHM will calculate hydrostatic pressures consistent with the temperature profile. If left blank, default pressures will be used.
  • flip_depth_sign (bool) – If sign of depths in file does not match z coordinate in simulation, flip the sign.
fdata.what
fdata.print_ctrl()

Display contents of CTRL macro.

fdata.print_iter()

Display contents of ITER macro.

fdata.print_time()

Display contents of TIME macro.

Examples

Examples given here are limited to the usage of fdata methods. More in depth explanations of FEHM simulation within the PyFEHM framework is given in the tutorial section of this guide.

  1. Read an FEHM input file into PyFEHM.
dat=fdata(filename='myInput.dat', gridfilename='myGrid.inp')
  1. Read in an FEHM input file with initial conditions.
dat=fdata('myInput.dat', 'myGrid.inp', 'myIncon.ini')
  1. Write out FEHM input deck.
dat.write('myInput2.dat')
  1. Delete a previously defined flow macro, assigned to the zone ‘injection, from the input file.
dat.delete(dat.fdata.flow['injection'])
  1. Run an FEHM simulation through PyFEHM.
dat.run(input='myInput.dat', grid='myGrid.inp', exe='C:\\path\\to\\FEHM\\source', files = ['hist', 'check', 'outp'])
  1. Create a new zone called reservoir and assign it permeability and elastic properties.
dat.zone['zmax'].new_zone(index=10, name='reservoir', rect=[[-0.1,-0.1,800.], [10000.1,10000.1,900.]], permeability=1.e-14, youngs_modulus=2.5e4)

FEHM control files

Information written to the fehmn.files control file is collated and modified within this object.

The control file can be written independently using files.write(), but in general should be written automatically when a PyFEHM simulation is run using fdata.run().

Some attributes of files will be written automatically when certain actions are taken within PyFEHM. For example, reading a new grid using fdata.grid.read('myGrid.inp') will cause fdata.files.grid='myGrid.inp'.

class fdata.files(root='', input='', grid='', incon='', rsto='', outp='', check='', hist='', co2in='', stor='', exe='fehm.exe', co2_inj_time=None)

Class containing information necessary to write out fehmn.files.

Attributes

files.input

(str) Name of input file. This is set automatically when reading an input file in PyFEHM or when running a simulation.

files.grid

(str) Name of grid file. This is set automatically when reading an grid file in PyFEHM.

files.incon

(str) Name of restart file to read in (initial condition). This is set automatically when reading an incon file in PyFEHM.

files.root

(str) Default file name string. If not already specified, this is set automatically when running a simulation.

files.rsto

(str) Name of restart file to write out.

files.outp

(str) Name of output file.

files.check

(str) Name of check file.

files.co2in

(str) Name or path to co2 properties file

files.hist

(str) Name of history file.

files.stor

(str) Name of store file.

files.exe

(str) Path to FEHM executable. Default is ‘fehm.exe’.

Methods

files.write(use_paths=False)

Write out fehmn.files.

Initial conditions/simulation restart

Initial conditions, or restart, files can be parsed, modified and rewritten in PyFEHM.

Reading of incon files occurs during model initialisation, e.g., fdata('myInput.dat','myGrid.inp', 'myIncon.ini'), or later by invoking fincon.read().

If changes are made to any of the restart variables, care should be taken to rewrite in the incon file using fincon.write() before running a simulation.

Tools are available for user modification of restart files. At present, these include the construction of critically-stressed lithostatic stress gradients using fincon.stressgrad() and fincon.critical_stress().

class fdata.fincon(inconfilename='')

Initial conditions object. Also called a restart file.

Reading one of these files associates the temperature, pressure, saturation etc. data with grid nodes and sets up fehmn.files to use the file for restarting.

Attributes: general

fincon.filename

(str) Name of restart file (initial conditions)

fincon.source

(str) Name of input file that generated the restart.

fincon.time

(fl64) Time stamp of initial conditions file (end time of simulation that produced this file).

Attributes: variables

When an incon file is parsed in PyFEHM, that information is made available through variable list attributes. Changes can be made to these variables and a new incon file written out using the write() method. For obvious reasons, some variables are only available if the relevant modules are being used, e.g., fincon.disp_x returns an empty list unless the FEHM stress module is being used.

Note that, because python indexing begins at 0, the variable associated with a node is accessed at the list position one less than the node index, e.g., the pressure at node 100 is accessed via fincon.P[99].

fincon.P

(lst[fl64]) Initial node pressures, ordered by node index.

fincon.T

(lst[fl64]) Initial node temperatures, ordered by node index.

fincon.S

(lst[fl64]) Initial node water saturations, ordered by node index.

fincon.S_co2l

(lst[fl64]) Initial node co2 liquid/super-critical saturations, ordered by node index.

fincon.S_co2g

(lst[fl64]) Initial node co2 gas saturations, ordered by node index.

fincon.co2aq

(lst[fl64]) Initial node dissolved co2 concentrations, ordered by node index.

fincon.eos

(lst[fl64]) Initial node water equation of state indices, ordered by node index.

fincon.co2_eos

(lst[fl64]) Initial node co2 equation of state indices, ordered by node index.

fincon.co2_eos

(lst[fl64]) Initial node co2 equation of state indices, ordered by node index.

fincon.disp_x

(lst[fl64]) Initial node x displacement, ordered by node index

fincon.disp_y

(lst[fl64]) Initial node y displacement, ordered by node index

fincon.disp_z

(lst[fl64]) Initial node z displacement, ordered by node index

fincon.strs_xx

(lst[fl64]) Initial node x stress, ordered by node index

fincon.strs_yy

(lst[fl64]) Initial node y stress, ordered by node index

fincon.strs_zz

(lst[fl64]) Initial node z stress, ordered by node index

fincon.strs_xy

(lst[fl64]) Initial node xy stress, ordered by node index

fincon.strs_xz

(lst[fl64]) Initial node xz stress, ordered by node index

fincon.strs_yz

(lst[fl64]) Initial node yz stress, ordered by node index

Methods

fincon.read(inconfilename='', if_new=False)

Parse a restart file for variable information.

Parameters:inconfilename (str) – Name of restart file.
fincon.write(inconfilename='')

Write out a restart file.

Parameters:inconfilename (str) – Name of restart file to write out.
fincon.stressgrad(xgrad, ygrad, zgrad, xygrad=0.0, xzgrad=0.0, yzgrad=0.0, calculate_vertical=False, vertical_fraction=False)

Construct initial stress state with vertical stress gradients.

Parameters:
  • xgrad (fl64, list[fl64,fl64]) – Vertical gradient in x stress (MPa/m), assumed intercept at [0,0]. If a two element list is given, the first value is interpreted as the gradient, and the second value as the elevation where stress is zero (i.e., the intercept with the z-axis).
  • ygrad (fl64, list[fl64,fl64]) – Vertical gradient in y stress (MPa/m), format as for xgrad.
  • zgrad (fl64, list[fl64,fl64]) – Vertical gradient in z stress (MPa/m), format as for xgrad.
  • xygrad (fl64, list[fl64,fl64]) – Vertical gradient in xy stress (MPa/m), default is 0, format as for xgrad.
  • xzgrad (fl64, list[fl64,fl64]) – Vertical gradient in xz stress (MPa/m), default is 0, format as for xgrad.
  • yzgrad (fl64, list[fl64,fl64]) – Vertical gradient in yz stress (MPa/m), default is 0, format as for xgrad.
  • calculate_vertical (bool) – Vertical stress calculated by integrating density. If true, then zgrad specifies the overburden.
  • vertical_fraction (bool) – Horizontal stresses calculated as a fraction of the vertical. If true, xgrad and ygrad are interpreted as fractions.
fincon.critical_stress(regime=1, horiz_stress='x', mu=0.6, cohesion=0, proximity=0.0, overburden=0.0)

Construct initial stress state near Mohr-Coulomb failure. The vertical stress is calculated using the assigned density. Minimum or maximum horizontal stress calculated using the specified friction coefficient. Intermediate principal stress is assumed to be the average of the other two.

Parameters:
  • regime (bool int) – Stress regime, 0 = compression, 1 = extension (default).
  • horiz_stress (str) – Horizontal coordinate direction (‘x’ or ‘y’) to assign the minimum or maximum principal stress (depending on stress regime).
  • mu (fl64) – Friction coefficient for Mohr-Coulomb failure (default = 0.6).
  • cohesion (fl64) – Cohesion for Mohr-Coulomb failure (default = 0).
  • proximity (fl64) – A negative quantity indicating how close the minimum principal stress is to Mohr-Coulomb failure (MPa, default = 0).
  • overburden (fl64) – Overburden at top of model (MPa, default = 0).

Examples

  1. Read in an incon file, increase all temperatures by 10degC and write out the new incon file.

dat.incon.read('myIncon.ini')

for i in len(range(dat.incon.T)): dat.incon.T[i] += 10

dat.incon.write('myNewIncon.ini')

  1. Read in an incon file and create vertical gradients in the stress field.

dat.incon.read('noStress.ini')

dat.incon.stressgrad(zgrad=0.02, xgrad = [0.015,-100], ygrad = [0.018, -100])

dat.incon.write('withStress.ini')

  1. Read in an incon file and create a critical stress state.

dat.incon.read('noStress.ini')

dat.incon.critical_stress(regime=1, horiz_stress = 'x', mu = 0.8, cohesion = 1, proximity = 0.5, overburden = 10)

dat.incon.write('withStress.ini')

Relative permeability

Relative permeability models in FEHM can be defined through either the RLP or RLPM macro. In PyFEHM, RLP macros are defined via the ordinary fmodel('rlp') object, whereas RLPM is defined within the specialised frlpm class detailed here.

For each phase present in the model, the user defines a relperm model. The user can additionally define capillary pressure models for phase pairs. The following phases can have relative permeability and capillary pressure models defined: water, air, co2_liquid, co2_gas, vapor.

Parameters for the available relative permeability models are given in the table below.

Relative permeability model Parameter name Default
constant None N/A
linear minimum_saturation 0
  maximum_saturation 1
exponential minimum_saturation 0
  maximum_saturation 1
  exponent 1
  maximum_relperm 1
corey minimum_saturation 0
  maximum_saturation 1
brooks-corey minimum_saturation 0
  maximum_saturation 1
  exponent 1
vg maximum_saturation 0
  maximum_saturation 1
  air_entry_head 1
  exponent 1

Parameters for the available capillary pressure models are given in the table below.

Capillary pressure model Parameter name Default
linear_cap cap_at_zero_sat None
  sat_at_zero_cap None
brooks-corey_cap minimum_saturation 0
  maximum_saturation 1
  exponent 1
  capillary_entry_presure 0.01
  low_saturation_fitting None
  cutoff_saturation None
vg_cap minimum_saturation 0
  maximum_saturation 1
  air_entry_head 1
  exponent 1
  low_saturation_fitting None
  cutoff_saturation None
class fdata.frlpm(zone=[], group=None, relperm=[], capillary=[])

Relative permeability model.

Relative permeability models are applied to zones. Each model assigns the relative permeability characteristics for a particular phase (in attribute relperm) and capillary pressure relationships between phases (in attribute capillary). In contrast to other macros, one relative permeability model may be applied to multiple zones.

Attributes

frlpm.group

(int) Group assignment for the relative permeability model.

frlpm.zone

(fzone) Zone or list of zones to which the relative permeability model is assigned.

frlpm.relperm

(dict) Dictionary of relative permeability models for each phase, indexed by phase name, e.g., ‘water’. Each relperm model has a model type, and set of parameters for that type.

frlpm.capillary

(dict) Dictionary of capillary pressure models, indexed by a tuple phase name pair, e.g., (‘water/air’). Each capillary pressure model has a model type, and set of parameters for that type.

Methods

frlpm.add_relperm(phase, type, param=[])

Add a new relative permeability model for a given phase.

Parameters:
  • phase (str) – Phase for which the relperm model is being defined, e.g., ‘air’,’water’,’co2_liquid’,’co2_gas’,’vapor’.
  • type (str) – Type of model being assigned for that phase, e.g., ‘constant’,’linear’,’exponential’,’corey’,’brooks-corey’,’vg’ (Van Genuchten).
  • param (list) – List of parameters for the specified model. See table above for a list of parameter names for each model.
frlpm.add_capillary(phase, type, param=[])

Add a new capillary pressure relationship between two phases.

Parameters:
  • phase (list, tuple) – List or tuple of two phases for which the relationship is defined, e.g., [‘air’,’water’].
  • type (str) – Type of model being assigned for that phase pair, e.g., ‘linear_cap’,’vg_cap’,’brooks-corey_cap’.
  • param (list) – List of parameters for the specified model. See table above for a list of parameter names for each model.
frlpm.delete(model)

Delete a previously defined relative permeability or capillary pressure model.

Examples

In the following example, a relative permeability and capillary pressure model is added for a water/co2 mixture.

rlpm=frlpm(group=1,zone=dat.zone[0])

rlpm.add_relperm ('water','exponential',[0.2,1.,3.1,1.])

rlpm.add_relperm ('co2_liquid','exponential',[0.2,1.,3.1,0.8])

rlpm.add_capillary (('water','co2_liquid'),'vg_cap',[0,0.87,.0015,3.5,7,0.])

dat.add (rlpm)

Stress module

FEHM contains an additional module that allows for coupled thermo-hydro-mechanical modelling. In PyFEHM, the stress module is invoked via the fstrs class.

For a well formed coupled flow-stress problem, the user will need to specify elastic material properties via fmacro('elastic') and some fixed displacement stress boundary conditions to prevent the model block from flying off into space (fmacro('stressboun')).

Additional complexity can be included, e.g.:

  1. gravitational bodyforces (fstrs.bodyforce)
  2. stress-permeability models (fmodel('permmodel'))
  3. thermal and poroelastic coupling between flow and stress (fmacro('biot'))
  4. stress restarts and critical stress states (fincon.critical_stress())

The stress module is off by default when a new data file is created. It is turned on via the fdata.strs.on() method.

class fdata.fstrs(initcalc=True, fem=True, bodyforce=True, tolerance=-0.01, param={}, parent=None)

Stress module object, sets properties for execution of FEHM stress module (see macro STRS).

Attributes

fstrs.param

(dict[flt]) Dictionary of stress parameters: ‘IHMS’ - coupling parameter, ‘ISTRS’ - type of stress solution.

fstrs.bodyforce

(bool) Boolean calling for body force calculations (gravity). Default is True.

fstrs.initcalc

(bool) Boolean signalling if initial stress calculations should be performed. Default is True.

fstrs.fem

(bool) Boolean signalling use of finite element modules for calculating stress and displacement. Default is True.

fstrs.tolerance

(flt) Tolerance of stress calculations.

fstrs.excess_she

Dictionary of excess shear parameters:

Methods

fstrs.on()

Set parameters to turn stress calculations ON.

fstrs.off()

Set param to turn stress calculations OFF.

Examples

Switch on the stress module, turn off bodyforce calculations (important if doing a restart from a simulation that previously contained gravity).

dat.strs.on()

dat.strs.bodyforce=False

Add some elastic material properties and a stress boundary condition.

dat.add (fmacro('elastic', param=(('youngs_modulus',1e4), ('poissons_ratio',0.25))))

dat.add (fmacro('stressboun', zone='xmin', subtype='fixed', param=(('direction',1),('value',0))))

Carbon dioxide module

Mixtures of water and gaseous, liquid and super-critical carbon dioxide are modelled in FEHM using the CARB macro. In PyFEHM this module is loaded using the fcarb class.

As with water, a CO2 simulation should contain CO2 sinks or sources (fmacro('co2flow')) and may include conditions for any CO2 initially present (fmacro('co2pres')) and fmacro('co2frac')).

When using the CO2 module, a relative permeability model for water/CO2 mixtures should be specified, either via fmodel('rlp') or frlpm.

The CO2 module is off by default when a new data file is created. It is turned on via fcarb.on().

class fdata.fcarb(iprtype=1, brine=False, parent=None)

CO2 module object, sets properties for execution of FEHM CO2 module (see macro CARB).

Attributes

fcarb.iprtype

(int) Integer indicating type of simulation.

fcarb.brine

(bool) Boolean signalling calculation of brine in simulation.

Methods

fcarb.on(iprtype=3)

Set parameters to turn CO2 calculations ON.

Parameters:iprtype (int) – Integer denoting type of simulation (1 = water only, 2 = CO2 only, 3 = water+CO2, no solubility, 4 = water+CO2, with solubility, 5 = water+CO2+air, with solubility)
fcarb.off()

Set parameters to turn CO2 calculations OFF.

fcarb.what

Return a summary of the CO2 module.

Examples

Switch on the CO2 module and specify that CO2 dissolution in water should be modelled.

dat.carb.on(iprtype = 4)

Add a CO2 injection source and assign the injection block to initially have non-zero CO2 fraction. This is important, as relative permeability effects may not permit the source to flow.

dat.add (fmacro('co2flow', zone='injection', param=(('rate',10), ('energy',-40), ('impedance',1.e-2), ('bc_flag',1))))

dat.add (fmacro('co2frac', zone='injection', param=(('water_rich_sat',0.5), ('co2_rich_sat',0.5), ('co2_mass_frac',0.), ('init_salt_conc',0.), ('override_flag',1))))

Species transport module

Support of FEHM’s trac macro is currently at ‘stupid’ level. The user supplies a list of zones required by the macro and a file path to an auxiliary text file which contains the macro definition verbatim.

class fdata.ftrac(parent=None, ldsp=False)

Chemistry module object, sets properties for execution of FEHM chemistry module (see macro TRAC).

ftrac attributes

ftrac.zonelist

(lst[fzone]) A list of zones to be written before the trac macro, for the situation that trac is used in ‘stupid’ model, i.e., the file attribute has been set to an auxiliary file.

ftrac.file

(str) Path of auxiliary file containing trac information. PyFEHM will copy the contents of this file into the input file verbatim. Setting this variable will cause PyFEHM to use trac in ‘stupid’ mode.

FEHM screen output

FEHM prints output information to the screen and to an output ‘*.outp’ file. These output files can be parsed for information using foutput objects. Optional information such as FEHM input and grid file paths may be required.

class fdata.foutput(filename=None, input=None, grid=None, hide=True, silent=True, write=False)

Methods

foutput.what

(str) Print out information about the fcontour object.

foutput attributes

foutput.node

(dict) Dictionary of node output, keyed first on component (‘water’,’gas’,’tracer1’), then on node number, then on variable.

foutput.times

(ndarray) Vector of output times.

foutput.variables

(lst) List of variables available for the various components.

foutput.components

(lst) Component names for which nodal information available

foutput.filename

(str) Name of output file

Examples

Read an FEHM output file

out=foutput('fehm.outp',input='fehmn.dat',grid='fehmn.grid')