fgrid: FEHM grid manipulation

This module contains classes and methods for the manipulation of FEHM grid files. Typically, usage will be limited to reading and writing of grid files, and the use of the spatial and connectivity information provided.

PyFEHM can parse unstructured or structured grids in FEHM format. PyFEHM can construct orthogonal grids of arbitrary complexity using the fmake class or by calling fgrid.make().

For the purposes of this manual, the variable geo will be assumed to refer to a previously defined instance of the fgrid class.

Nodes

The smallest quantum of the finite element grid. Node objects and associated connectivity information are automatically created when a grid file is parsed (fgrid.read()).

In FEHM, a node is associated with a position in space and a control volume - the region of space uniquely associated with the node. It is connected to other nodes, forming elements and the finite element grid.

When a grid is loaded and associated with an FEHM input file, material properties and zone information are mapped back onto the nodes. For example, if the ROCK macro has been assigned in an input file, then density information for a given node is accessed through its density attribute, fnode.density.

class fgrid.fnode(index, position)

FEHM grid node object.

Geometry attributes

fnode.index

(int) Integer number denoting the node.

fnode.position

(lst[fl64]) List of the node’s coordinates in 2- or 3-D space.

fnode.vol

(fl64) Control volume associated with the node. This information only available if volumes() method called from grid attribute.

fnode.connected_nodes

(lst[fnode]) List of node objects connected to this node. This information only available if full_connectivity=True passed to fgrid.read()

fnode.connections

(lst[fconn]) List of connection objects of which the node is a member.

fnode.elements

(lst[felem]) List of element objects of which the node is a member.

Material property attributes

fnode.permeability

(list) permeability values at node.

fnode.conductivity

(list) conductivity values at node.

fnode.density

(fl64) density at node.

fnode.specific_heat

(fl64) specific heat at node.

fnode.porosity

(fl64) porosity at node.

fnode.youngs_modulus

(fl64) Youngs modulus at node.

fnode.poissons_ratio

(fl64) Poissons ratio at node.

fnode.thermal_expansion

(fl64) Coefficient of thermal expansion at node.

fnode.pressure_coupling

(fl64) Biot pressure coupling coefficient at node.

fnode.rlpmodel

(int) index of relative permeability model assigned to node

fnode.permmodel

(int) index of stress-permeability model assigned to node.

fnode.pormodel

(int) index of variable porosity model assigned to node.

fnode.condmodel

(int) index of variable conductivity model assigned to node.

State attributes

fnode.Pi

(fl64) initial pressure at node.

fnode.Ti

(fl64) initial temperature at node.

fnode.Si

(fl64) initial water saturation at node.

fnode.S_co2gi

(fl64) initial gaseous CO2 saturation at node.

fnode.S_co2li

(fl64) initial liquid CO2 saturation at node.

fnode.co2aqi

(fl64) initial dissolved CO2 concentration at node.

fnode.strsi

(fl64) initial stresses at node.

fnode.dispi

(fl64) initial displacements at node.

fnode.P

(fl64) pressure at node during a simulation.

fnode.T

(fl64) temperature at node.

fnode.S

(fl64) water saturation at node.

fnode.S_co2g

(fl64) gaseous CO2 saturation at node.

fnode.S_co2l

(fl64) liquid CO2 saturation at node.

fnode.co2aq

(fl64) dissolved CO2 concentration at node.

fnode.strs

(list) stresses at node ([xx,yy,xy] for 2D, [xx,yy,zz,xy,yz,xz] for 3D).

fnode.disp

(list) displacements at node ([x,y] for 2D, [x,y,z] for 3D).

Other attributes

fnode.zone

(dict) Dictionary of zones to which the node belongs.

fnode.zonelist

(lst[fzone]) List of zones of which the node is a member

fnode.generator

(dict) Dictionary of generator properties associated with node.

Methods

fnode.what

Print to screen information about the node.

Connections

class fgrid.fconn(nodes)

Connection object, comprising two connected nodes, separated by some distance.

A connection is associated with a distance between the two nodes.

Attributes

fconn.nodes

(lst[fnode]) List of node objects (fnode()) that define the connection.

fconn.distance

(fl64) Distance between the two connected nodes.

Elements

class fgrid.felem(index=None, nodes=[])

Finite element object, comprising a set of connected nodes.

A finite element is associated with an element centre and an element volume.

Attributes

felem.index

(int) Integer number denoting the element.

felem.nodes

(lst[fnode]) List of node objects that define the element.

felem.centre

(ndarray) Coordinates of the element centroid.

Methods

felem.what

Print to screen information about the element.

Grids

The fgrid object contains all information about the finite element grid.

The grid object corresponds to an FEHM grid file and comprises an assembly of fnode, fconn and felem objects. This assembly is constructed by reading an existing FEHM grid files (fgrid.read()) or by creating an empty fgrid object and creating a new mesh using the fgrid.make() command. Read and write support for FEHM stor files is supported.

class fgrid.fgrid(full_connectivity=True)

FEHM grid object.

Attributes: object lists

fgrid.node

(dict[fnode]) Dictionary of grid nodes, indexed by node integer.

fgrid.nodelist

(lst[fnode]) List of all node objects in the grid.

fgrid.conn

(dict[fconn]) Dictionary of connections, indexed by a two element tuple of the member node integers.

fgrid.connlist

(lst[fconn]) List of all connection objects in the grid.

fgrid.elem

(dict[felem]) Dictionary of elements, indexed by element integer.

fgrid.elemlist

(lst[felem]) List of all element objects in the grid.

Attributes: grid properties

fgrid.xmin

Minimum x-coordinate for all nodes.

fgrid.xmax

Maximum x-coordinate for all nodes.

fgrid.ymin

Minimum y-coordinate for all nodes.

fgrid.ymax

Maximum y-coordinate for all nodes.

fgrid.zmin

Minimum z-coordinate for all nodes.

fgrid.zmax

Maximum z-coordinate for all nodes.

fgrid.dimensions

(int) Dimensions of the grid.

fgrid.number_nodes

Number of nodes in grid.

fgrid.number_elems

Number of elements in grid.

Methods

fgrid.read(gridfilename, full_connectivity=True, octree=False, storfilename=None)

Read data from an FEHM or AVS grid file. If an AVS grid is specified, PyFEHM will write out the corresponding FEHM grid file.

Parameters:

• gridfilename (str) – name of grid file, including path specification.
• full_connectivity (bool) – read element and connection data and construct corresponding objects. Defaults to False. Use if access to connectivity information will be useful.
• octree (bool) – flag to use octree search algorithm for finding node locations (default = False).
• storfilename (bool) – name of optional stor file, including path specification.

fgrid.write(filename=None, format='fehm', remove_duplicates=True, recalculate_coefficients=True, compress_eps=1e-05)

Write grid object to a grid file (FEHM, AVS STOR file formats supported). Stor file support only for orthogonal hexahedral grids.

Parameters:

• filename (str) – name of FEHM grid file to write to, including path specification, e.g. c:pathfile_out.inp
• format (str) – FEHM grid file format (‘fehm’,’avs’,’stor’). Defaults to ‘fehm’ unless filename is passed with extension ‘.avs’ or ‘.stor’.
• remove_duplicates (bool) – Remove duplicate entries in the stor file. Improves simulation run time, particularly for structured grids.
• compress_eps (fl64) – Float used to determine geometric coefficients to remove (Coefficients less than max(geom_coef)*compress_eps will be removed)
• keepcons (lst(connection keys)) – List of connections to keep in stor file no matter what

fgrid.node_nearest_point(pos=[])

Return node object nearest to position in space. Method uses octree structure for speed up if available.

Parameters:pos (list) – Coordinates, e.g. [2300., -134.8, 0.]. Returns:fnode() – node object closest to position.

fgrid.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', cutaway=[], zones=[])

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

Parameters:

• save (str) – Name of saved zone image.
• angle ([fl64,fl64], str) – View angle of zone. First number is tilt angle in degrees, second number is azimuth. 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.
• cutaway ([fl64,fl64,fl64], str) – Coordinate from which cutaway begins. Alternatively, specifying ‘middle’,’centre’ with choose the centre of the grid as the cutaway point.
• zones (int, str) – List of zone indices or names. If these are defined then nodes contained in those zones are highlighted in the output plot. Maximum of six zones.

fgrid.make(gridfilename, x, y, z, full_connectivity=True, octree=False, radial=False)

Generates an orthogonal mesh for input node positions.

The mesh is constructed using the fgrid.fmake object and an FEHM grid file is written for the mesh.

Parameters:

• gridfilename (str) – Name to which to save the grid file.
• x (list[fl64]) – Unique set of x-coordinates.
• y (list[fl64]) – Unique set of y-coordinates.
• z (list[fl64]) – Unique set of z-coordinates.
• full_connectivity (bool) – read element and connection data and construct corresponding objects. Defaults to False. Use if access to connectivity information will be useful.
• radial (bool) – Creates a radial grid (ignores z coordinate)

fgrid.lagrit_stor(grid=None, stor=None, exe='c:\path\to\lagrit\lagrit.exe', overwrite=False)

Uses LaGriT to create a stor file for the simulation, this will be used in subsequent runs. To create the stor file, LaGriT will convert a mesh comprised of hexahedral elements into one comprising only tetrahedrals. Therefore, a new FEHM grid file will be created and parsed, reflecting the modified element structure.

Parameters:

• grid (str) – Name of grid file to be created. Destination directory supported.
• stor (str) – Name of stor file to be created. Destination directory supported.
• exe (str) – Path to lagrit executable (default, fdflt.lagrit_path, in environment file ‘fdflt.py’).
• overwrite (bool) – Flag to request that the new FEHM grid file overwrites the old one.

fgrid.volumes(volumefilename)

Reads a lagrit generated file containing control volume information.

Parameters:volumefilename (str) – Name of lagrit output file containing control volume information.

fgrid.remove_zeros(tolerance=1e-08, keepcons=[])

Removes node connections with geometric coefficients smaller than a supplied tolerance.

Parameters:

• tolerance (fl64) – Relative tolerance below which connections will be removed (default = 1.e-8).
• keepcons (lst(connection keys) or lst(connections)) – List of connections to keep in stor file ignoring tolerance.

fgrid.what

Print to screen information about the grid.

Examples

1. Create an fgrid object and read an existing FEHM grid file.

geo=fgrid()

geo.read('c:\\path\\to\\old_GRID.inp')

or

geo=fgrid('c:\\path\\to\\old_GRID.inp')

2. Plot a view of the grid looking down the x-axis, with gridlines coloured blue.

geo.plot('FEHMgrid1.png',color='r',angle='x')

3. Plot a view of the grid looking along the axis x=y=z, gridlines coloured red, with a cutaway beginning at the centre.

geo.plot('FEHMgrid2.png',color='b',angle=[45,45],cutaway='middle')

Image produced by example 3.

4. Make changes to an fgrid object and write out the changes to a new FEHM grid file.

for nd in geo.nodelist: nd.position[2]+=1000.

geo.write('new_GRID.inp')

5. Find the node nearest a given location in space.

nd=geo.node_nearest_point([225,1600,-356])

6. Create a new grid using the fgrid.make() command.

geo.make('mygrid.inp', x=[0,1,2,3], y=[-10,-20,-30], z=[0.1,0.3,0.8])

7. For an existing grid, use lagrit_stor() method to instruct LaGriT to create a stor file.

geo.lagrit_stor(overwrite=True, stor='stor\\geo.stor', exe='c:\\bin\\lagrit.exe')