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 CrunchFlowspatial_profile
output, which include spatially-variable geochemical conditions and sediment properties at a given point in time.output.timeseries
. Class for working with CrunchFlowtime_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)