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

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

Create a binary header

static set_dtype(bintype=None, precision='single')

Set the dtype

set_values(**kwargs)

Set values using kwargs

class BinaryLayerFile(filename: str | PathLike, precision, verbose, kwargs)

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

Parameters:

header (datafile.Header) – header object

Returns:

databytes – size of the data array, in bytes, following the header

Return type:

int

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

Bases: Exception

class CellBudgetFile(filename: str | PathLike, precision='auto', verbose=False, **kwargs)

Bases: object

CellBudgetFile Class.

Parameters:

• filename (str or PathLike) – Path 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()

Close the file handle

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

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)

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

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

Return the number of records in the file

Returns:

out – Number of records in the file.

Return type:

int

get_position(idx, header=False)

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)

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)

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

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)

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)

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)

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

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

class HeadFile(filename: str | PathLike, text='head', precision='auto', verbose=False, **kwargs)

Bases: BinaryLayerFile

HeadFile Class.

Parameters:

• filename (str or PathLike) – Path 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: str | PathLike, text='headu', precision='auto', verbose=False, **kwargs)

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

Parameters:

header (datafile.Header) – header object

Returns:

databytes – size of the data array, in bytes, following the header

Return type:

int

get_ts(idx)

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)

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

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)

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: str | PathLike)

Determine precision of a MODFLOW head file.

Parameters:

• filename (str or PathLike) –

• precision. (Path of binary MODFLOW file to determine) –

Returns:

• result (str)

• Result will be unknown, single, or double

join_struct_arrays(arrays)

Simple function that can join two numpy structured arrays.

write_budget(fbin, data, kstp=1, kper=1, text='    FLOW-JA-FACE', imeth=1, delt=1.0, pertim=1.0, totim=1.0, text1id1='           GWF-1', text2id1='           GWF-1', text1id2='           GWF-1', text2id2='             NPF')

write_head(fbin, data, kstp=1, kper=1, pertim=1.0, totim=1.0, text='            HEAD', ilay=1)