fpost: FEHM output file manipulation

Processing simulation output data is as important as the generation of the data itself. PyFEHM contains a range of basic plotting tools to visualise FEHM output, all based on the matplotlib python library.

FEHM can output both time history data for specified variables at specified nodes () and contour data for specified variables at specified times. PyFEHM can read in any output data format, e.g., surfer, tecplot, so the user is not required to output in a specific format (although surfer format is likely to be the least buggy).

Contour output

Data are read from a list of FEHM output files corresponding to a particular time during a simulation. Depending on input specifications in fdata.cont, for each node, x, y, z data, pressure, temperature, permeability information is available.

Setting the target filename using wildcards will cause PyFEHM to read in multiple input files for different times. This format will accommodate FEHM’s distinction of scalar, vector and concentration output, e.g., information from run.0001_con_node.dat and run.0001_sca_node.data will be read into a single object.

This format also supports material property files, generally denoted with ‘mat_node’ in the title. This information, when parsed, is made available through the material attribute.

class fpost.fcontour(filename=None, latest=False, first=False, nearest=None)

Contour output information object.

Attributes

fcontour.times

(lst[fl64]) List of times (in seconds) for which output data are available.

fcontour.variables

(lst[str]) List of variables for which output data are available.

fcontour.user_variables

(lst[str]) List of user-defined variables for which output data are available.

fcontour.material

(dict[str]) Dictionary of material properties, keyed by property name, items indexed by node_number - 1. This attribute is empty if no material property file supplied.

fcontour.format

(str) Format of output file, options are ‘tec’, ‘surf’, ‘avs’ and ‘avsx’.

fcontour.filename

(str) Name of FEHM contour output file. Wildcards can be used to define multiple input files.

Grid attributes

fcontour.x

(lst[fl64]) Unique list of nodal x-coordinates for grid.

fcontour.y

(lst[fl64]) Unique list of nodal y-coordinates for grid.

fcontour.z

(lst[fl64]) Unique list of nodal z-coordinates for grid.

fcontour.xmin

(fl64) Minimum nodal x-coordinate for grid.

fcontour.xmax

(fl64) Maximum nodal x-coordinate for grid.

fcontour.ymin

(fl64) Minimum nodal y-coordinate for grid.

fcontour.ymax

(fl64) Maximum nodal y-coordinate for grid.

fcontour.zmin

(fl64) Minimum nodal z-coordinate for grid.

fcontour.zmax

(fl64) Maximum nodal z-coordinate for grid.

Methods

fcontour.read(filename, latest=False, first=False, nearest=[])

Read in FEHM contour output information.

Parameters:

• filename (str) – File name for output data, can include wildcards to define multiple output files.
• latest (bool) – Boolean indicating PyFEHM should read the latest entry in a wildcard search.
• first (bool) – Boolean indicating PyFEHM should read the first entry in a wildcard search.
• nearest (fl64,list) – Read in the file with date closest to the day supplied. List input will parse multiple output files.

fcontour.node(node, time=None, variable=None)

Returns all information for a specific node.

If time and variable not specified, a dictionary of time series is returned with variables as the dictionary keys.

If only time is specified, a dictionary of variable values at that time is returned, with variables as dictionary keys.

If only variable is specified, a time series vector is returned for that variable.

If both time and variable are specified, a single value is returned, corresponding to the variable value at that time, at that node.

Parameters:

• node (int) – Node index for which variable information required.
• time (fl64) – Time at which variable information required. If not specified, all output.
• variable (str) – Variable for which information requested. If not specified, all output.

fcontour.new_variable(name, time, data)

Creates a new variable, which is some combination of the available variables.

Parameters:

• name (str) – Name for the variable.
• time (fl64) – Time key which the variable should be associated with. Must be one of the existing keys, i.e., an item in fcontour.times.
• data (lst[fl64]) – Variable data, most likely some combination of the available parameters, e.g., pressure*temperature, pressure[t=10] - pressure[t=5]

fcontour.paraview(grid, stor=None, exe='paraview', filename='temp.vtk', show=None, diff=False, zscale=1.0, time_derivatives=False)

Launches an instance of Paraview that displays the contour object.

Parameters:

• grid (str) – Path to grid file associated with FEHM simulation that produced the contour output.
• stor (str) – Path to grid file associated with FEHM simulation that produced the contour output.
• exe (str) – Path to Paraview executable.
• filename (str) – Name of VTK file to be output.
• show (str) – Variable to show when Paraview starts up (default = first available variable in contour object).
• 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.
• time_derivatives (bool) – Calculate new fields for time derivatives of contour data. For precision reasons, derivatives are calculated with units of ‘per day’.

fcontour.what

(str) Print out information about the fcontour object.

Examples

Slice plots

fcontour.slice(variable, slice, divisions, time=None, method='nearest')

Returns mesh data for a specified slice orientation from 3-D contour output data.

Parameters:

• variable (str) – Output data variable, for example ‘P’ = pressure. Alternatively, variable can be a five element list, first element ‘cfs’, remaining elements fault azimuth (relative to x), dip, friction coefficient and cohesion. Will return coulomb failure stress.
• time (fl64) – Time for which output data is requested. Can be supplied via fcontour.times list. Default is most recently available data.
• slice (lst[str,fl64]) – List specifying orientation of output slice, e.g., [‘x’,200.] is a vertical slice at x = 200, [‘z’,-500.] is a horizontal slice at z = -500., [point1, point2] is a fixed limit vertical or horizontal domain corresponding to the bounding box defined by point1 and point2.
• divisions ([int,int]) – Resolution to supply mesh data.
• method (str:) – Method of interpolation, options are ‘nearest’, ‘linear’.

Returns:

X – x-coordinates of mesh data.

fcontour.slice_plot(variable=None, time=None, slice='', divisions=[20, 20], levels=10, cbar=False, xlims=[], ylims=[], colors='k', linestyle='-', save='', xlabel='x / m', ylabel='y / m', title='', font_size='medium', method='nearest', equal_axes=True, mesh_lines=None, perm_contrasts=None, scale=1.0)

Returns a filled plot of contour data. Invokes the slice() method to interpolate slice data for plotting.

Parameters:

• variable (str) – Output data variable, for example ‘P’ = pressure.
• time (fl64) – Time for which output data is requested. Can be supplied via fcontour.times list. Default is most recently available data. If a list of two times is passed, the difference between the first and last is plotted.
• slice (lst[str,fl64]) – List specifying orientation of output slice, e.g., [‘x’,200.] is a vertical slice at x = 200, [‘z’,-500.] is a horizontal slice at z = -500., [point1, point2] is a fixed limit vertical or horizontal domain corresponding to the bounding box defined by point1 and point2.
• 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 (bool) – Add colour bar to plot.
• xlims ([fl64, fl64]) – Plot limits on x-axis.
• ylims ([fl64, fl64]) – Plot limits on y-axis.
• colors (lst[str]) – Specify colour string for contour levels.
• linestyle (str) – Style of contour lines, e.g., ‘k-‘ = solid black line, ‘r:’ red dotted line.
• 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.
• mesh_lines (bool) – Superimpose mesh on the plot (line intersections correspond to node positions) according to specified linestyle, e.g., ‘k:’ is a dotted black line.
• perm_contrasts (bool) – Superimpose permeability contours on the plot according to specified linestyle, e.g., ‘k:’ is a dotted black line. A gradient method is used to pick out sharp changes in permeability.

fcontour.cutaway_plot(variable=None, time=None, divisions=[20, 20, 20], levels=10, cbar=False, angle=[45, 45], xlims=[], method='nearest', ylims=[], zlims=[], colors='k', linestyle='-', save='', xlabel='x / m', ylabel='y / m', zlabel='z / m', title='', font_size='medium', equal_axes=True, grid_lines=None)

Returns a filled plot of contour data on each of 3 planes in a cutaway plot. Invokes the slice() method to interpolate slice data for plotting.

Parameters:

• variable (str) – Output data variable, for example ‘P’ = pressure.
• time (fl64) – Time for which output data is requested. Can be supplied via fcontour.times list. Default is most recently available data. If a list of two times is passed, the difference between the first and last is plotted.
• divisions ([int,int,int]) – Resolution to supply mesh data in [x,y,z] coordinates.
• 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 (bool) – Include colour bar.
• 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.
• method (str) – Method of interpolation, options are ‘nearest’, ‘linear’.
• xlims ([fl64, fl64]) – Plot limits on x-axis.
• ylims ([fl64, fl64]) – Plot limits on y-axis.
• zlims ([fl64, fl64]) – Plot limits on z-axis.
• colors (lst[str]) – Specify colour string for contour levels.
• linestyle (str) – Style of contour lines, e.g., ‘k-‘ = solid black line, ‘r:’ red dotted line.
• 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.
• zlabel (str) – Label on z-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) – Force plotting with equal aspect ratios for all axes.
• grid_lines (bool) – Extend tick lines across plot according to specified linestyle, e.g., ‘k:’ is a dotted black line.

fcontour.slice_plot_line(variable=None, time=None, slice='', divisions=[20, 20], labels=False, label_size=10.0, levels=10, xlims=[], ylims=[], colors='k', linestyle='-', save='', xlabel='x / m', ylabel='y / m', title='', font_size='medium', method='nearest', equal_axes=True)

Returns a line plot of contour data. Invokes the slice() method to interpolate slice data for plotting.

Parameters:

• variable (str) – Output data variable, for example ‘P’ = pressure.
• time (fl64) – Time for which output data is requested. Can be supplied via fcontour.times list. Default is most recently available data. If a list of two times is passed, the difference between the first and last is plotted.
• slice (lst[str,fl64]) – List specifying orientation of output slice, e.g., [‘x’,200.] is a vertical slice at x = 200, [‘z’,-500.] is a horizontal slice at z = -500., [point1, point2] is a fixed limit vertical or horizontal domain corresponding to the bounding box defined by point1 and point2.
• divisions ([int,int]) – Resolution to supply mesh data.
• method (str) – Method of interpolation, options are ‘nearest’, ‘linear’.
• labels (bool) – Specify whether labels should be added to contour plot.
• label_size (str, int) – Specify text size of labels on contour plot, either as an integer or string, e.g., 10, ‘small’, ‘x-large’.
• levels (lst[fl64], int) – Contour levels to plot. Can specify specific levels in list form, or a single integer indicating automatic assignment of levels.
• xlims ([fl64, fl64]) – Plot limits on x-axis.
• ylims ([fl64, fl64]) – Plot limits on y-axis.
• linestyle (str) – Style of contour lines, e.g., ‘k-‘ = solid black line, ‘r:’ red dotted line.
• 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.

Profile plots

fcontour.profile(variable, profile, time=None, divisions=30, method='nearest')

Return variable data along the specified line in 3-D space. If only two points are supplied, the profile is assumed to be a straight line between them.

Parameters:

• variable (str, lst[str]) – Output data variable, for example ‘P’ = pressure. Can specify multiple variables with a list.
• time (fl64) – Time for which output data is requested. Can be supplied via fcontour.times list. Default is most recently available data.
• profile (ndarray) – Three column array with each row corresponding to a point in the profile.
• divisions (int) – Number of points in profile. Only relevant if straight line profile being constructed from two points.
• method (str) – Interpolation method, options are ‘nearest’ (default) and ‘linear’.

Returns:

Multi-column array. Columns are in order x, y and z coordinates of profile, followed by requested variables.

fcontour.profile_plot(variable=None, time=None, profile=[], divisions=30, xlims=[], ylims=[], color='k', marker='x-', save='', xlabel='distance / m', ylabel='', title='', font_size='medium', method='nearest', verticalPlot=False, elevationPlot=False)

Return a plot of the given variable along a specified profile. If the profile comprises two points, these are interpreted as the start and end points of a straight line profile.

Parameters:

• variable (str, lst[str]) – Output data variable, for example ‘P’ = pressure. Can specify multiple variables with a list.
• time (fl64) – Time for which output data is requested. Can be supplied via fcontour.times list. Default is most recently available data. If a list of two times is passed, the difference between the first and last is plotted.
• profile (ndarray) – Three column array with each row corresponding to a point in the profile.
• divisions (int) – Number of points in profile. Only relevant if straight line profile being constructed from two points.
• method (str) – Interpolation method, options are ‘nearest’ (default) and ‘linear’.
• xlims ([fl64, fl64]) – Plot limits on x-axis.
• ylims ([fl64, fl64]) – Plot limits on y-axis.
• color (str) – Colour of profile.
• marker (str) – Style of line, e.g., ‘x-‘ = solid line with crosses, ‘o:’ dotted line with circles.
• 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’.
• verticalPlot (bool) – Flag to plot variable against profile distance on the y-axis.
• elevationPlot (bool) – Flag to plot variable against elevation on the y-axis.

History output

Data are read from a list of FEHM output files corresponding to a particular variable during a simulation. Depending on input specifications in fdata.hist, for each requested node, time series data is available.

Setting the target filename using wildcards will cause PyFEHM to read in multiple input files for different times.

class fpost.fhistory(filename=None, verbose=True)

History output information object.

Zone fluxes

Zone flux information is parsed using the fzoneflux class, which is a derived class of fhistory. Where identical, methods and attributes are shown only for fhistory.

class fpost.fzoneflux(filename=None, verbose=True)

Zone flux history output information object.

Tracers

Tracer information is parsed using the ftracer class, which is a derived class of fhistory. Where identical, methods and attributes are shown only for fhistory.

class fpost.ftracer(filename=None, verbose=True)

Tracer history output information object.

Particle tracking

Particle tracking information is parsed using the fptrk class, which is a derived class of fhistory. Where identical, methods and attributes are shown only for fhistory.

class fpost.fptrk(filename=None, verbose=True)

Tracer history output information object.

Attributes

fhistory.times

(lst[fl64]) List of times (in seconds) for which output data are available.

fhistory.variables

(lst[str]) List of variables for which output data are available.

fhistory.nodes

(lst[fl64]) List of node indices for which output data are available.

fzoneflux.zones

(lst[int]) List of zone indices for which output data are available.

fhistory.format

(str) Format of output file, options are ‘tec’, ‘surf’, ‘avs’ and ‘avsx’.

fhistory.filename

(str) Name of FEHM contour output file. Wildcards can be used to define multiple input files.

Methods

fhistory.read(filename)

Read in FEHM history output information.

Parameters:filename (str) – File name for output data, can include wildcards to define multiple output files.

Time series plots

fhistory.time_plot(variable=None, node=0, t_lim=[], var_lim=[], marker='x-', color='k', save='', xlabel='', ylabel='', title='', font_size='medium', scale=1.0, scale_t=1.0)

Generate and save a time series plot of the history data.

Parameters:

• variable (str) – Variable to plot.
• node (int) – Node number to plot.
• t_lim (lst[fl64,fl64]) – Time limits on x axis.
• var_lim (lst[fl64,fl64]) – Variable limits on y axis.
• marker (str) – String denoting marker and linetype, e.g., ‘:s’, ‘o–’. Default is ‘x-‘ (solid line with crosses).
• color (str) – String denoting colour. Default is ‘k’ (black).
• save (str) – Name to save plot.
• xlabel (str) – Label on x axis.
• ylabel (str) – Label on y axis.
• title (str) – Title of plot.
• font_size (str) – Font size for axis labels.
• scale (fl64) – If a single number is given, then the output variable will be multiplied by this number. If a two element list is supplied then the output variable will be transformed according to y = scale[0]*x+scale[1]. Useful for transforming between coordinate systems.
• scale_t (fl64) – As for scale but applied to the time axis.

Node fluxes

Inter node flux information is parsed using the fnodeflux class. Time plotting functionality is not currently available for this class.

class fpost.fnodeflux(filename=None)

Internode flux information.

Can read either water or CO2 internode flux files.

The fnodeflux object is indexed first by node pair - represented as a tuple of node indices - and then by either the string ‘liquid’ or ‘vapor’. Data values are in time order, as given in the ‘times’ attribute.

Attributes

fnodeflux.times

(lst) times for which node flux information is reported.

fnodeflux.nodepairs

(lst) node pairs for which node flux information is available. Each node pair is represented as a two item tuple of node indices.

fnodeflux.filename

(str) filename target for internode flux file.

Methods

fnodeflux.read(filename)

Read in FEHM contour output information.

Parameters:filename (str) – File name for output data, can include wildcards to define multiple output files.

Multi document pdf

class fpost.multi_pdf(combineString='gswin64', save='multi_plot.pdf', files=[], delete_files=True)

Tool for making a single pdf document from multiple eps files.

Attributes

multi_pdf.save

(str) Name of the final pdf to output.

multi_pdf.files

(lst[str]) List of eps files to be assembled into pdf.

multi_pdf.combineString

(str) Command line command, with options, generate pdf from multiple eps files. See manual for further instructions.

Methods

multi_pdf.add(filename, pagenum=None)

Add a new page. If a page number is specified, the page will replace the current. Otherwise it will be appended to the end of the document.

Parameters:

• filename (str) – Name of .eps file to be added.
• pagenum (int) – Page number of file to be added.

multi_pdf.insert(filename, pagenum)

Insert a new page at the given page number.

Parameters:

• filename (str) – Name of .eps file to be inserted.
• pagenum (int) – Page number of file to be inserted.

multi_pdf.make()

Construct the pdf.

Examples