flopy.utils.binaryfile module¶

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

HeadFile (Binary head file. Can also be used for drawdown)
HeadUFile (Binary MODFLOW-USG unstructured head file)
UcnFile (Binary concentration file from MT3DMS)
CellBudgetFile (Binary cell-by-cell flow file)

class BinaryHeader(bintype=None, precision='single')[source]¶

Bases: flopy.utils.datafile.Header

The binary_header class is a class to create headers for MODFLOW binary files.

Parameters

bintype (str) – is the type of file being opened (head and ucn file currently supported)
precision (str) – is the precision of the floating point data in the file

static create(bintype=None, precision='single', **kwargs)[source]¶: Create a binary header

static set_dtype(bintype=None, precision='single')[source]¶: Set the dtype

set_values(**kwargs)[source]¶: Set values using kwargs

class BinaryLayerFile(filename, precision, verbose, kwargs)[source]¶

Bases: flopy.utils.datafile.LayerFile

The BinaryLayerFile class is the super class from which specific derived classes are formed. This class should not be instantiated directly

get_databytes(header)[source]¶

Parameters: header (datafile.Header) – header object
Returns: databytes – size of the data array, in bytes, following the header
Return type: int

get_ts(idx)[source]¶

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 – Array has size (ntimes, ncells + 1). The first column in the data array will contain time (totim).
Return type: numpy array

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

Examples

exception BudgetIndexError[source]¶: Bases: Exception

class CellBudgetFile(filename, precision='auto', verbose=False, **kwargs)[source]¶

Bases: object

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.

Notes

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()[source]¶: Close the file handle

get_data(idx=None, kstpkper=None, totim=None, text=None, paknam=None, full3D=False)[source]¶

Get data from the binary budget file.

Parameters

idx (int or list) – 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 written as part of a ‘COMPACT BUDGET’ MODFLOW budget file. (Default is False.)

Returns

recordlist – 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.

Return type

list of records

Notes

Examples

get_indices(text=None)[source]¶

Get a list of indices for a selected record name

Parameters: text (str) – The text identifier for the record. Examples include ‘RIVER LEAKAGE’, ‘STORAGE’, ‘FLOW RIGHT FACE’, etc.
Returns: out – indices of selected record name in budget file.
Return type: tuple

get_kstpkper()[source]¶

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

Returns: out – List of unique kstp, kper combinations in binary file. kstp and kper values are zero-based.
Return type: list of (kstp, kper) tuples

get_nrecords()[source]¶

Return the number of records in the file

Returns: out – Number of records in the file.
Return type: int

get_position(idx, header=False)[source]¶

Get the starting position of the data or header for a specified record number in the binary budget file.

Parameters

idx (int) – The zero-based record number. The first record is record 0.
header (bool) – If True, the position of the start of the header data is returned. If False, the position of the start of the data is returned (default is False).

Returns

ipos – The position of the start of the data in the cell budget file or the start of the header.

Return type

int64

get_record(idx, full3D=False)[source]¶

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 written as part of a ‘COMPACT BUDGET’ MODFLOW budget file. (Default is False.)

Returns

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.

Return type

a single data record

Notes

Examples

get_residual(totim, scaled=False)[source]¶

Return an array the size of the model grid containing the flow residual calculated from the budget terms. Residual will not be correct unless all flow terms are written to the budget file.

Parameters

totim (float) – Simulation time for which to calculate the residual. This value must be precise, so it is best to get it from the get_times method.
scaled (bool) – If True, then divide the residual by the total cell inflow

Returns

residual – The flow residual for the cell of shape (nlay, nrow, ncol)

Return type

np.ndarray

get_times()[source]¶

Get a list of unique times in the file

Returns: out – List contains unique simulation times (totim) in binary file.
Return type: list of floats

get_ts(idx, text=None, times=None)[source]¶

Get a time series from the binary budget 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.
text (str) – The text identifier for the record. Examples include ‘RIVER LEAKAGE’, ‘STORAGE’, ‘FLOW RIGHT FACE’, etc.
times (iterable of floats) – List of times to from which to get time series.

Returns

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

Return type

numpy array

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

Examples

get_unique_package_names(decode=False)[source]¶

Get a list of unique package names in the file

Parameters: decode (bool) – Optional boolean used to decode byte strings (default is False).
Returns: names – List of unique package names in the binary file.
Return type: list of strings

get_unique_record_names(decode=False)[source]¶

Get a list of unique record names in the file

Parameters: decode (bool) – Optional boolean used to decode byte strings (default is False).
Returns: names – List of unique text names in the binary file.
Return type: list of strings

list_records()[source]¶: Print a list of all of the records in the file

list_unique_packages()[source]¶: Print a list of unique package names

list_unique_records()[source]¶: Print a list of unique record names

class HeadFile(filename, text='head', precision='auto', verbose=False, **kwargs)[source]¶

Bases: flopy.utils.binaryfile.BinaryLayerFile

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.)

class HeadUFile(filename, text='headu', precision='auto', verbose=False, **kwargs)[source]¶

Bases: flopy.utils.binaryfile.BinaryLayerFile

Unstructured MODFLOW-USG HeadUFile Class.

Parameters

filename (string) – Name of the concentration file
text (string) – Name of the text string in the head file. Default is ‘headu’
precision (string) – ‘auto’, ‘single’ or ‘double’. Default is ‘auto’.
verbose (bool) – Write information to the screen. Default is False.

Notes

The HeadUFile class provides simple ways to retrieve a list of head arrays from a MODFLOW-USG 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. For unstructured grids, nrow and ncol are the starting and ending node numbers for layer, ilay. This class overrides methods in the parent class so that the proper sized arrays are created.

When the get_data method is called for this class, a list of one-dimensional arrays will be returned, where each array is the head array for a layer. If the heads for a layer were not saved, then None will be returned for that layer.

Examples

>>> import flopy.utils.binaryfile as bf
>>> hdobj = bf.HeadUFile('model.hds')
>>> hdobj.list_records()
>>> usgheads = hdobj.get_data(kstpkper=(1, 50))

get_databytes(header)[source]¶

Parameters: header (datafile.Header) – header object
Returns: databytes – size of the data array, in bytes, following the header
Return type: int

get_ts(idx)[source]¶

Get a time series from the binary HeadUFile

Parameters: idx (int or list of ints) – idx can be nodenumber or it can be a list in the form [nodenumber, nodenumber, …]. The nodenumber, values must be zero based.
Returns: out – Array has size (ntimes, ncells + 1). The first column in the data array will contain time (totim).
Return type: numpy array

class UcnFile(filename, text='concentration', precision='auto', verbose=False, **kwargs)[source]¶

Bases: flopy.utils.binaryfile.BinaryLayerFile

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))

binaryread(file, vartype, shape=(1,), charlen=16)[source]¶

Uses numpy to read from binary file. This was found to be faster than the: struct approach and is used as the default.

binaryread_struct(file, vartype, shape=(1,), charlen=16)[source]¶

Read text, a scalar value, or an array of values from a binary file.

filefile object
is an open file object

vartypetype
is the return variable type: str, numpy.int32, numpy.float32, or numpy.float64

shapetuple
is the shape of the returned array (shape(1, ) returns a single value) for example, shape = (nlay, nrow, ncol)

charlenint
is the length of the text string. Note that string arrays cannot be returned, only multi-character strings. Shape has no affect on strings.

get_headfile_precision(filename)[source]¶

Determine precision of a MODFLOW head file.

Parameters

filename (str) –
precision. (Name of binary MODFLOW file to determine) –

Returns

result (str)
Result will be unknown, single, or double

join_struct_arrays(arrays)[source]¶: Simple function that can join two numpy structured arrays.