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.
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].
fdata.fzone(index=None, type='', points=[], nodelist=[], file='', name='')[source]¶FEHM Zone object.
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.
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.
fzone.rect(p1, p2)[source]¶Create a rectangular zone corresponding to the bounding box delimited by p1 and p2.
| Parameters: |
|
|---|
fzone.fix_temperature(T, multiplier=10000000000.0, file=None)[source]¶Fixes temperatures at nodes within this zone. Temperatures fixed by adding an HFLX macro with high heat flow multiplier.
| Parameters: |
|
|---|
fzone.fix_pressure(P=0, T=30.0, impedance=1000000.0, file=None)[source]¶Fixes pressures at nodes within this zone. Pressures fixed by adding a FLOW macro with high impedance.
| Parameters: |
|
|---|
fzone.fix_displacement(direction, displacement, file=None)[source]¶Fixes displacement at nodes within this zone. Displacements fixed by adding a STRESSBOUN macro.
| Parameters: |
|
|---|
fzone.fix_stress(direction, stress, file=None)[source]¶Fixes displacement at nodes within this zone. Displacements fixed by adding a STRESSBOUN macro.
| Parameters: |
|
|---|
fzone.roller(direction=None, file=None)[source]¶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)[source]¶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')[source]¶Generates and saves a 3-D plot of the zone.
| Parameters: |
|
|---|
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')[source]¶Returns a contour plot of the top surface of the zone.
| Parameters: |
|
|---|
Example:
dat.zone[2].topo('zoneDEMtopo.png',method = 'linear')
fzone.what¶Print to screen information about the zone.
1. Create a rectangular zone that encompasses all nodes within a horizontal reservoir. Bounding box limits
are used as inputs for rect().
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'))
ZMAX, fix its temperature to 90degC.caprockXMIN as a roller boundary condition (zero displacement in x-direction)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.
fdata.fmacro(type='', zone=[], param=[], subtype='', file=None, write_one_macro=False)[source]¶FEHM macro object.
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.
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
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.
dat.dat.dat in a single command.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).
fdata.fmodel(type='', zonelist=[], param=[], index=None, file=None)[source]¶Model object, used in a variety of macro definitions.
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¶(**)
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.
dat.help.permmodel()
dat.help.pormodel(-1)
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).
fdata.fboun(zone=[], type='ti', times=[], variable=[], file=None)[source]¶Boundary condition object.
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.
dat.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.
fdata.fhist(format='tec', timestep_interval=1, time_interval=1e+30, variables=[], nodelist=[], zonelist=[], zoneflux=[], azonelist=[])[source]¶FEHM history output object.
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.
fhist.options¶Print out eligible variables for output.
fhist.what¶Print out information about the attribute.
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])
fdata.fcont(format='surf', timestep_interval=1000, time_interval=1e+30, time_flag=True, variables=[], zones=[])[source]¶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.
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.
fcont.options¶Print out eligible variables for output.
fcont.what¶Print out information about the attribute.
dat.cont.timestep_interval=10
dat.cont.time_interval=100
dat.cont.variables.append(['temperature','permeability','displacement','co2'])
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.
fdata.fdata(filename='', gridfilename='', inconfilename='', sticky_zones=True, associate=True, work_dir=None, full_connectivity=True, skip=[], keep_unknown=True)[source]¶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.
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.
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
To access a specific ROCK macro assigned to zone 20, use the fdata.rock dictionary
To access FLOW generators assigned to the previously defined ‘injection’ zone, use the fdata.flow dictionary
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¶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 |
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.
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).
fdata.read(filename='', gridfilename='', inconfilename='', full_connectivity=True, skip=[])[source]¶Read FEHM input file and construct fdata object.
| Parameters: |
|
|---|
fdata.write(filename='', writeSubFiles=True)[source]¶Write fdata object to FEHM input file and fehmn.files file.
| Parameters: |
|
|---|
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, no_paths=False, write_files_only=False, diagnostic=False, clean=False, writeSubFiles=True)[source]¶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: |
|
|---|
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)[source]¶Exports the model object to VTK and loads in paraview.
| Parameters: |
|
|---|
fdata.picklable()[source]¶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)[source]¶Exports the model object to VTK.
| Parameters: |
|
|---|
fdata.add(obj, overwrite=False)[source]¶Attach a zone, boundary condition or macro object to the data file.
| Parameters: |
|---|
fdata.delete(obj)[source]¶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)[source]¶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: |
|
|---|
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)[source]¶Create and assign a new zone. Material properties are optionally specified, new macros will be created if required.
| Parameters: |
|
|---|
fdata.temperature_gradient(filename, offset=0.0, first_zone=100, auxiliary_file=None, hydrostatic=0, flip_depth_sign=False)[source]¶Assign initial temperature distribution to model based on supplied temperature profile.
| Parameters: |
|
|---|
fdata.what¶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.
dat.run(input='myInput.dat', grid='myGrid.inp', exe='C:\\path\\to\\FEHM\\source', files = ['hist', 'check', 'outp'])
reservoir and assign it permeability and elastic properties.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'.
fdata.files(root='', input='', grid='', incon='', rsto='', outp='', check='', hist='', co2in='', stor='', exe='fehm.exe', co2_inj_time=None)[source]¶Class containing information necessary to write out fehmn.files.
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’.
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().
fdata.fincon(inconfilename='')[source]¶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.
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).
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
fincon.read(inconfilename='', if_new=False)[source]¶Parse a restart file for variable information.
| Parameters: | inconfilename (str) – Name of restart file. |
|---|
fincon.write(inconfilename='')[source]¶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)[source]¶Construct initial stress state with vertical stress gradients.
| Parameters: |
|
|---|
fincon.critical_stress(regime=1, horiz_stress='x', mu=0.6, cohesion=0, proximity=0.0, overburden=0.0)[source]¶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: |
|
|---|
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
fdata.frlpm(zone=[], group=None, relperm=[], capillary=[])[source]¶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.
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.
frlpm.add_relperm(phase, type, param=[])[source]¶Add a new relative permeability model for a given phase.
| Parameters: |
|
|---|
frlpm.add_capillary(phase, type, param=[])[source]¶Add a new capillary pressure relationship between two phases.
| Parameters: |
|
|---|
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)
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.:
fstrs.bodyforce)fmodel('permmodel'))fmacro('biot'))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.
fdata.fstrs(initcalc=True, fem=True, bodyforce=True, tolerance=-0.01, param={}, parent=None)[source]¶Stress module object, sets properties for execution of FEHM stress module (see macro STRS).
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:
Switch on the stress module, turn off bodyforce calculations (important if doing a restart from a simulation that previously contained gravity).
Add some elastic material properties and a stress boundary condition.
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().
fdata.fcarb(iprtype=0, brine=False, parent=None)[source]¶CO2 module object, sets properties for execution of FEHM CO2 module (see macro CARB).
fcarb.iprtype¶(int) Integer indicating type of simulation.
fcarb.brine¶(bool) Boolean signalling calculation of brine in simulation.
fcarb.on(iprtype=3)[source]¶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.what¶Return a summary of the CO2 module.
Switch on the CO2 module and specify that CO2 dissolution in water should be modelled.
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.
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.
fdata.ftrac(parent=None, ldsp=False)[source]¶Chemistry module object, sets properties for execution of FEHM chemistry module (see macro TRAC).
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 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.
fdata.foutput(filename=None, input=None, grid=None, hide=True, silent=True, write=False)[source]¶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