flopy.utils.binaryfile Module

Module to read MODFLOW binary output files. The module contains three important classes that can be accessed by the user.

  • HeadFile (Binary head file. Can also be used for drawdown)
  • UcnFile (Binary concentration file from MT3DMS)
  • CellBudgetFile (Binary cell-by-cell flow file)
class flopy.utils.binaryfile.HeadFile(filename, text='head', precision='auto', verbose=False, **kwargs)

HeadFile Class.

Parameters:

filename : string

Name of the concentration file

text : string

Name of the text string in the head file. Default is ‘head’

precision : string

‘auto’, ‘single’ or ‘double’. Default is ‘auto’.

verbose : bool

Write information to the screen. Default is False.

Notes

The HeadFile class provides simple ways to retrieve 2d and 3d head arrays from a MODFLOW binary head file and time series arrays for one or more cells.

The BinaryLayerFile class is built on a record array consisting of headers, which are record arrays of the modflow header information (kstp, kper, pertim, totim, text, nrow, ncol, ilay) and long integers, which are pointers to first bytes of data for the corresponding data array.

Examples

>>> import flopy.utils.binaryfile as bf
>>> hdobj = bf.HeadFile('model.hds', precision='single')
>>> hdobj.list_records()
>>> rec = hdobj.get_data(kstpkper=(1, 50))
>>> ddnobj = bf.HeadFile('model.ddn', text='drawdown', precision='single')
>>> ddnobj.list_records()
>>> rec = ddnobj.get_data(totim=100.)
close()

Close the file handle.

get_alldata(mflay=None, nodata=-9999)

Get all of the data from the file.

Parameters:

mflay : integer

MODFLOW zero-based layer number to return. If None, then all all layers will be included. (Default is None.)

nodata : float

The nodata value in the data array. All array values that have the nodata value will be assigned np.nan.

Returns:

data : numpy array

Array has size (ntimes, nlay, nrow, ncol) if mflay is None or it has size (ntimes, nrow, ncol) if mlay is specified.

get_data(kstpkper=None, idx=None, totim=None, mflay=None)

Get data from the file for the specified conditions.

Parameters:

idx : int

The zero-based record number. The first record is record 0.

kstpkper : tuple of ints

A tuple containing the time step and stress period (kstp, kper). These are zero-based kstp and kper values.

totim : float

The simulation time.

mflay : integer

MODFLOW zero-based layer number to return. If None, then all all layers will be included. (Default is None.)

Returns:

data : numpy array

Array has size (nlay, nrow, ncol) if mflay is None or it has size (nrow, ncol) if mlay is specified.

Notes

if both kstpkper and totim are None, will return the last entry Examples ——–

get_kstpkper()

Get a list of unique stress periods and time steps in the file

Returns:

out : list of (kstp, kper) tuples

List of unique kstp, kper combinations in binary file. kstp and kper values are presently zero-based.

get_times()

Get a list of unique times in the file

Returns:

out : list of floats

List contains unique simulation times (totim) in binary file.

get_ts(idx)

Get a time series from the binary file.

Parameters:

idx : tuple of ints, or a list of a tuple of ints

idx can be (layer, row, column) or it can be a list in the form [(layer, row, column), (layer, row, column), ...]. The layer, row, and column values must be zero based.

Returns:

out : numpy array

Array has size (ntimes, ncells + 1). The first column in the data array will contain time (totim).

Notes

The layer, row, and column values must be zero-based, and must be within the following ranges: 0 <= k < nlay; 0 <= i < nrow; 0 <= j < ncol

list_records()

Print a list of all of the records in the file obj.list_records()

plot(axes=None, kstpkper=None, totim=None, mflay=None, filename_base=None, **kwargs)

Plot 3-D model output data in a specific location in LayerFile instance

Parameters:

axes : list of matplotlib.pyplot.axis

List of matplotlib.pyplot.axis that will be used to plot data for each layer. If axes=None axes will be generated. (default is None)

kstpkper : tuple of ints

A tuple containing the time step and stress period (kstp, kper). These are zero-based kstp and kper values.

totim : float

The simulation time.

mflay : int

MODFLOW zero-based layer number to return. If None, then all all layers will be included. (default is None)

filename_base : str

Base file name that will be used to automatically generate file names for output image files. Plots will be exported as image files if file_name_base is not None. (default is None)

**kwargs : dict

pcolor
: bool

Boolean used to determine if matplotlib.pyplot.pcolormesh plot will be plotted. (default is True)

colorbar
: bool

Boolean used to determine if a color bar will be added to the matplotlib.pyplot.pcolormesh. Only used if pcolor=True. (default is False)

contour
: bool

Boolean used to determine if matplotlib.pyplot.contour plot will be plotted. (default is False)

clabel
: bool

Boolean used to determine if matplotlib.pyplot.clabel will be plotted. Only used if contour=True. (default is False)

grid
: bool

Boolean used to determine if the model grid will be plotted on the figure. (default is False)

masked_values
: list

List of unique values to be excluded from the plot.

file_extension
: str

Valid matplotlib.pyplot file extension for savefig(). Only used if filename_base is not None. (default is ‘png’)

Returns:

None

Examples

>>> import flopy
>>> hdobj = flopy.utils.HeadFile('test.hds')
>>> times = hdobj.get_times()
>>> hdobj.plot(totim=times[-1])
to_shapefile(filename, kstpkper=None, totim=None, mflay=None, attrib_name='lf_data')
Export model output data to a shapefile at a specific location
in LayerFile instance.
Parameters:

filename : str

Shapefile name to write

kstpkper : tuple of ints

A tuple containing the time step and stress period (kstp, kper). These are zero-based kstp and kper values.

totim : float

The simulation time.

mflay : integer

MODFLOW zero-based layer number to return. If None, then layer 1 will be written

attrib_name : str

Base name of attribute columns. (default is ‘lf_data’)

Returns:

None

Examples

>>> import flopy
>>> hdobj = flopy.utils.HeadFile('test.hds')
>>> times = hdobj.get_times()
>>> hdobj.to_shapefile('test_heads_sp6.shp', totim=times[-1])
class flopy.utils.binaryfile.UcnFile(filename, text='concentration', precision='auto', verbose=False, **kwargs)

UcnFile Class.

Parameters:

filename : string

Name of the concentration file

text : string

Name of the text string in the ucn file. Default is ‘CONCENTRATION’

precision : string

‘auto’, ‘single’ or ‘double’. Default is ‘auto’.

verbose : bool

Write information to the screen. Default is False.

Notes

The UcnFile class provides simple ways to retrieve 2d and 3d concentration arrays from a MT3D binary head file and time series arrays for one or more cells.

The BinaryLayerFile class is built on a record array consisting of headers, which are record arrays of the modflow header information (kstp, kper, pertim, totim, text, nrow, ncol, ilay) and long integers, which are pointers to first bytes of data for the corresponding data array.

Examples

>>> import flopy.utils.binaryfile as bf
>>> ucnobj = bf.UcnFile('MT3D001.UCN', precision='single')
>>> ucnobj.list_records()
>>> rec = ucnobj.get_data(kstpkper=(1,1))
close()

Close the file handle.

get_alldata(mflay=None, nodata=-9999)

Get all of the data from the file.

Parameters:

mflay : integer

MODFLOW zero-based layer number to return. If None, then all all layers will be included. (Default is None.)

nodata : float

The nodata value in the data array. All array values that have the nodata value will be assigned np.nan.

Returns:

data : numpy array

Array has size (ntimes, nlay, nrow, ncol) if mflay is None or it has size (ntimes, nrow, ncol) if mlay is specified.

get_data(kstpkper=None, idx=None, totim=None, mflay=None)

Get data from the file for the specified conditions.

Parameters:

idx : int

The zero-based record number. The first record is record 0.

kstpkper : tuple of ints

A tuple containing the time step and stress period (kstp, kper). These are zero-based kstp and kper values.

totim : float

The simulation time.

mflay : integer

MODFLOW zero-based layer number to return. If None, then all all layers will be included. (Default is None.)

Returns:

data : numpy array

Array has size (nlay, nrow, ncol) if mflay is None or it has size (nrow, ncol) if mlay is specified.

Notes

if both kstpkper and totim are None, will return the last entry Examples ——–

get_kstpkper()

Get a list of unique stress periods and time steps in the file

Returns:

out : list of (kstp, kper) tuples

List of unique kstp, kper combinations in binary file. kstp and kper values are presently zero-based.

get_times()

Get a list of unique times in the file

Returns:

out : list of floats

List contains unique simulation times (totim) in binary file.

get_ts(idx)

Get a time series from the binary file.

Parameters:

idx : tuple of ints, or a list of a tuple of ints

idx can be (layer, row, column) or it can be a list in the form [(layer, row, column), (layer, row, column), ...]. The layer, row, and column values must be zero based.

Returns:

out : numpy array

Array has size (ntimes, ncells + 1). The first column in the data array will contain time (totim).

Notes

The layer, row, and column values must be zero-based, and must be within the following ranges: 0 <= k < nlay; 0 <= i < nrow; 0 <= j < ncol

list_records()

Print a list of all of the records in the file obj.list_records()

plot(axes=None, kstpkper=None, totim=None, mflay=None, filename_base=None, **kwargs)

Plot 3-D model output data in a specific location in LayerFile instance

Parameters:

axes : list of matplotlib.pyplot.axis

List of matplotlib.pyplot.axis that will be used to plot data for each layer. If axes=None axes will be generated. (default is None)

kstpkper : tuple of ints

A tuple containing the time step and stress period (kstp, kper). These are zero-based kstp and kper values.

totim : float

The simulation time.

mflay : int

MODFLOW zero-based layer number to return. If None, then all all layers will be included. (default is None)

filename_base : str

Base file name that will be used to automatically generate file names for output image files. Plots will be exported as image files if file_name_base is not None. (default is None)

**kwargs : dict

pcolor
: bool

Boolean used to determine if matplotlib.pyplot.pcolormesh plot will be plotted. (default is True)

colorbar
: bool

Boolean used to determine if a color bar will be added to the matplotlib.pyplot.pcolormesh. Only used if pcolor=True. (default is False)

contour
: bool

Boolean used to determine if matplotlib.pyplot.contour plot will be plotted. (default is False)

clabel
: bool

Boolean used to determine if matplotlib.pyplot.clabel will be plotted. Only used if contour=True. (default is False)

grid
: bool

Boolean used to determine if the model grid will be plotted on the figure. (default is False)

masked_values
: list

List of unique values to be excluded from the plot.

file_extension
: str

Valid matplotlib.pyplot file extension for savefig(). Only used if filename_base is not None. (default is ‘png’)

Returns:

None

Examples

>>> import flopy
>>> hdobj = flopy.utils.HeadFile('test.hds')
>>> times = hdobj.get_times()
>>> hdobj.plot(totim=times[-1])
to_shapefile(filename, kstpkper=None, totim=None, mflay=None, attrib_name='lf_data')
Export model output data to a shapefile at a specific location
in LayerFile instance.
Parameters:

filename : str

Shapefile name to write

kstpkper : tuple of ints

A tuple containing the time step and stress period (kstp, kper). These are zero-based kstp and kper values.

totim : float

The simulation time.

mflay : integer

MODFLOW zero-based layer number to return. If None, then layer 1 will be written

attrib_name : str

Base name of attribute columns. (default is ‘lf_data’)

Returns:

None

Examples

>>> import flopy
>>> hdobj = flopy.utils.HeadFile('test.hds')
>>> times = hdobj.get_times()
>>> hdobj.to_shapefile('test_heads_sp6.shp', totim=times[-1])
class flopy.utils.binaryfile.CellBudgetFile(filename, precision='single', verbose=False, **kwargs)

CellBudgetFile Class.

Parameters:

filename : string

Name of the cell budget file

precision : string

‘single’ or ‘double’. Default is ‘single’.

verbose : bool

Write information to the screen. Default is False.

Examples

>>> import flopy.utils.binaryfile as bf
>>> cbb = bf.CellBudgetFile('mymodel.cbb')
>>> cbb.list_records()
>>> rec = cbb.get_data(kstpkper=(0,0), text='RIVER LEAKAGE')
close()

Close the file handle

create3D(data, nlay, nrow, ncol)

Convert a dictionary of {node: q, ...} into a numpy masked array. In most cases this should not be called directly by the user unless you know what you’re doing. Instead, it is used as part of the full3D keyword for get_data.

Parameters:

data : dictionary

Dictionary with node keywords and flows (q) items.

nlay, nrow, ncol : int

Number of layers, rows, and columns of the model grid.

Returns:

out : numpy masked array

List contains unique simulation times (totim) in binary file.

get_data(idx=None, kstpkper=None, totim=None, text=None, paknam=None, full3D=False)

get data from the budget file.

Parameters:

idx : int

The zero-based record number. The first record is record 0.

kstpkper : tuple of ints

A tuple containing the time step and stress period (kstp, kper). The kstp and kper values are zero based.

totim : float

The simulation time.

text : str

The text identifier for the record. Examples include ‘RIVER LEAKAGE’, ‘STORAGE’, ‘FLOW RIGHT FACE’, etc.

full3D : boolean

If true, then return the record as a three dimensional numpy array, even for those list-style records writen as part of a ‘COMPACT BUDGET’ MODFLOW budget file. (Default is False.)

Returns:

recordlist : list of records

A list of budget objects. The structure of the returned object depends on the structure of the data in the cbb file.

If full3D is True, then this method will return a numpy masked array of size (nlay, nrow, ncol) for those list-style ‘COMPACT BUDGET’ records written by MODFLOW.

get_indices(text=None)

Get a list of indices for a selected record name

Returns:

out : tuple

indices of selected record name in budget file.

get_kstpkper()

Get a list of unique stress periods and time steps in the file

Returns:

out : list of (kstp, kper) tuples

List of unique kstp, kper combinations in binary file. kstp and kper values are zero-based.

get_nrecords()

Return the number of records in the file

Returns:

out : int

Number of records in the file.

get_record(idx, full3D=False)

Get a single data record from the budget file.

Parameters:

idx : int

The zero-based record number. The first record is record 0.

full3D : boolean

If true, then return the record as a three dimensional numpy array, even for those list-style records writen as part of a ‘COMPACT BUDGET’ MODFLOW budget file. (Default is False.)

Returns:

record : a single data record

The structure of the returned object depends on the structure of the data in the cbb file. Compact list data are returned as

If full3D is True, then this method will return a numpy masked array of size (nlay, nrow, ncol) for those list-style ‘COMPACT BUDGET’ records written by MODFLOW.

get_times()

Get a list of unique times in the file

Returns:

out : list of floats

List contains unique simulation times (totim) in binary file.

get_unique_package_names()

Get a list of unique package names in the file

Returns:

out : list of strings

List of unique package names in the binary file.

get_unique_record_names()

Get a list of unique record names in the file

Returns:

out : list of strings

List of unique text names in the binary file.

list_records()

Print a list of all of the records in the file

list_unique_packages()

Print a list of unique package names

list_unique_records()

Print a list of unique record names