python-crunchflow – A Python Library for Processing CrunchFlow Output

python-crunchflow is an open source python package designed for processing and visualizing output from the reactive transport model CrunchFlow. This library provides a set of tools for quickly plotting time series and geochemical output produced by CrunchFlow.

This library consists of three main modules:

  • output.tec. Class for working with CrunchFlow spatial_profile output, which include spatially-variable geochemical conditions and sediment properties at a given point in time.

  • output.timeseries. Class for working with CrunchFlow time_series output, which consists of temporally-variable aqueous concentrations at a specific node.

  • util. General utilities for parsing CrunchFlow input files and manipulating output.

Contents:

Spatial (tec) Output

output.tec.get_tec_metadata(file)[source]

Given a crunch .tec output file, read it in and return a list of the variables (e.g., ‘X-Perm’, ‘Y-Perm’, etc) included in the output file.

Parameters
filestr

Filename to read in

Returns
columnslist, str

ordered list of variables included in filename

titlestr

Value included in this file, as output by CrunchFlow

output.tec.get_tec_output_times(crunch_log, folder='.')[source]

Given a log of CrunchFlow terminal output, get the time steps associated with .tec file numbers. For example, during a model run, CrunchFlow will print progress to the screen, including blocks that look like:

>>> WRITING OUTPUT FILES
>>> Time (days) =  9.000E+00
>>> File number  =            2

This function combs through that terminal output to create a list of times at which .tec files were written.

Parameters
crunch_logstr

Filename of the crunchflow terminal output

folderstr

Folder in which ‘crunch_log’ is located.The default is the current directory

Returns
output_timeslist of float

Ordered list of the output times (in CrunchFlow time units) corresponding to each .tec file number.

class output.tec.tec(fileprefix, folder='.', output_times=None)[source]

This is the tec class for working with CrunchFlow .tec files.

Examples

>>> vol = tec('volume')
>>> print(vol.columns)
>>> vol.plot('Calcite')
>>> calcite = vol.extract('Calcite', time=2)
Attributes
timeslist of int

relative times at which .tec files were output, sorted

fileslist of str

ordered list of all files matching fileprefix

columnslist of str

list of all vars included within each .tec file

nxint

# of grid cells in the x direction

nyint

# of grid cells in the y direction

nzint

# of grid cells in the z direction

coordsndarray of float

(nx*ny*nz, 2) array of x, y coordinates of each node

griddedXndarray of float

(ny, nx) array of x coordinates; used for plotting

griddedYndarray of float

(ny, nx) array of y coordinates; used for plotting

Methods

plot(variable, time)

Plot .tec output from a single time step.

plot_series(variable)

Plot .tec output for a series of time steps.

extract(variable, time)

Return the spatial profile of var at the given time.

outline(variable, value, time)

Get line segments that outline all the regions equal to the provided value.

extract(var, time=1)[source]

Return the spatial profile of var at the given time.

Parameters
varstr

variable to return (e.g., ‘Porosity’)

timeint

time slice at which to return the profile

Returns
datandarray of float

(ny, nx) numpy array of var

outline(var, value=None, time=1)[source]

For a given .tec file, get line segments that outline all the regions equal to the provided value. Useful for generating outlines of a areas of a model domain sharing a single attribute (e.g., permeability) and later adding the outlines to a plot of a different variable.

Parameters
varstr

variable to outline (e.g., ‘Porosity’)

valuefloat

value to outline. The default is least-frequent value in array

timeint

time slice at which to create an outline

Returns
segmentsndarray of float

array of (x,y) coordinate pairs for each line segment that comprises the outline

Examples

>>> # Get stratigraphy from permeability map
>>> perm = tec('permeability')
>>> segments = perm.outline('X-Perm')
>>> 
>>> # Plot stratigraphy outlines on O2 map
>>> conc = tec('conc')
>>> fig, ax = conc.plot('O2(aq)')
>>> ax.plot(segments[:,0], segments[:,1])
plot(var, time=None, plot_type='image', figsize=(12, 3), **kwargs)[source]

Plot .tec output from a single time step.

Parameters
varstr

variable to plot (e.g., ‘H+’)

timeint

which time slice to show

figsizetuple of int

figure size; default (12, 3)

plot_typestr

whether to display an image (‘image’) or a color-filled contour plot (‘contourf’)

**kwargsdict

args passed on to matplotlib plot function (either contourf or imshow)

Returns
figpyplot object

matplotlib fig handle for the plot

axpyplot object

matplotlib ax handle for the plot

plot_series(var, times=None, plot_type='image', figsize=None, **kwargs)[source]

Plot .tec output for a series of time steps.

Parameters
varstr

variable to plot (e.g., ‘H+’)

timeslist

time steps to plot, must be either components of self.times or self.output_times; defaults to all time steps

plot_typestr

whether to display an image (‘image’) or a contour-filled contour plot (‘contourf’)

figsizetuple of int

figure size; default (12, 1.5 * # of timesteps)

**kwargsdict

args passed on to matplotlib’s imshow

Returns
figpyplot object

matplotlib fig handle for the plot

axeslist of pyplot objects

list of matplotlib axes handles for each subplot

Time Series Output

output.timeseries.get_ts_coords(tsfile)[source]

Given a CrunchFlow time series ouput file, return the coordinate at which that time series was output.

Parameters
tsfilestr

filename containing timeseries output

Returns
coordstuple of int

Coordinates of the form (x, y, z)

output.timeseries.get_ts_duplicates(tsfile)[source]

Find duplicate columns in a time series file. Useful when a user specifies time_series_print all in CrunchFlow; the time series file includes primary species printed twice.

Parameters
tsfilestr

path to the time series file

Returns
columnslist

list of column headings without duplicates

nondup_indiceslist

list of column indices without duplicates

class output.timeseries.timeseries(tsfile, folder='.')[source]

This is the timeseries class for working with CrunchFlow time series output files.

Examples

>>> ts = timeseries('Well1-1.txt')
>>> ts.convert_mgL()
>>> calcium = ts.df['Ca++']
>>> ts.plot('Ca++')
Attributes
coordstuple of int

x, y and z coordinates of the time series

timeunitstr

time unit used in the CrunchFlow input

unitstr

Concentration units included in the file. Automatically set to the default CrunchFlow concentration units (mol/kgw)

specieslist of str

list of aqueous species in the file

datandarray of float

Numpy array of all data. First col is the time step and remaining cols are species in the same order as self.species list

dfdataframe of float

Pandas dataframe of all data. Index is the time step and columns #are the aqueous species

Methods

convert_mgL(database=’datacom.dbs’, folder=’.’)

Convert time series concentrations from mol/kgw to mg/L (ppm).

plot(species, units=’mg/L’, **kwargs)

Plot the time series of one or more species.

convert_mgL(database='datacom.dbs', folder='.')[source]

Convert time series concentrations from mol/kgw to mg/L (ppm). Note that this assumes that 1 kg water = 1 L water.

Parameters
databasestr

name of the CrunchFlow database. The default is ‘datacom.dbs’

folderstr

path to the database. The default is current directory.

Returns
None. Modifies timeseries object in place.
plot(species, units='mg/L', **kwargs)[source]

Plot the time series of one or more species.

Parameters
speciesstr or list of str

Either single species or list of species to be plotted

unitsstr

Concentration units to use for plotting. The default is ‘mg/L’

**kwargsdict

keyword arguments passed to plt.subplots (e.g., figsize)

Returns
figpyplot object

figure handle for current plot

axpyplot object

axis handle for current plot

Utilities

util.correct_exponent(filename, folder='.', verbose='med')[source]

Correct triple digit exponents within a file. CrunchFlow has trouble outputting triple-digit exponents and omits the ‘E’. For example, ‘2.5582E-180’ prints as ‘2.5582-180’.

Parameters
filenamestr

name of the file to be processed

folderstr

folder containing the file, either relative or absolute path

verbose{‘med’, ‘high’, ‘low’}

Print each correction as it’s performed (‘high’), print total number of corrections (‘med’), or print nothing (‘low’). The default is ‘med’

Returns
None. Modifies the file in place.
util.crunch_input_block(line, block)[source]

While reading a CrunchFlow input file, return the input block to which the current line belongs.

Parameters
linestr

current line in the input file

blockstr

block to which the previous line belongs. Initialize as empty str

Returns
blockstr

one of the default CrunchFlow blocks (e.g., “RUNTIME”) or an empty string if between blocks. If within a geochemical condition block, returns the name of the geochemical condition.

Examples

>>> block = ""
>>> with open(input_file, "r") as f:
>>>     for line in f:
>>>         block = crunch_input_block(line, block)
>>>         
>>>         if block == "BOUNDARY_CONDITIONS":
>>>             print(line)

Indices and tables