flopy.utils.binaryfile package

Submodules

Module contents

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: Header

Represents data headers for binary output files.

Parameters:

  • bintype (str, default None) – Type of file being opened. Accepted values are ‘head’ and ‘ucn’.

  • precision (str, default 'single') – Precision of 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: str | PathLike, precision, verbose, **kwargs)[source]

Bases: LayerFile

The BinaryLayerFile class is a parent class from which concrete classes inherit. This class should not be instantiated directly.

Notes

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 ints pointing to the 1st byte of data for the corresponding data arrays.

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 (int, tuple of ints, or list of such) –

Acceptable values depend on grid type:

  • Structured grids (DIS): (layer, row, column) or list of such

  • Vertex grids (DISV): (layer, cellid) or list of such

  • Unstructured grids (DISU): node number or list of such

All indices must be zero-based.

For backwards compatibility, DISV and DISU grids also accept the old 3-tuple format with dummy values: (layer, dummy, cellid) for DISV and (dummy, dummy, node) for DISU.

Returns:

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

Return type:

numpy array

Notes

Index ranges (zero-based):

  • DIS: 0 <= layer < nlay, 0 <= row < nrow, 0 <= col < ncol

  • DISV: 0 <= layer < nlay, 0 <= cellid < ncpl

  • DISU: 0 <= node < nnodes

Examples

>>> # DIS grid: layer 0, row 5, column 5
>>> ts = hds.get_ts(idx=(0, 5, 5))

>>> # DISV grid: layer 0, cell 12
>>> ts = hds.get_ts(idx=(0, 12))

>>> # DISU grid: node 10
>>> ts = hds.get_ts(idx=10)
exception BudgetIndexError[source]

Bases: Exception

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

Bases: object

The CellBudgetFile class provides convenient ways to retrieve and manipulate budget data from a binary cell budget file. A utility method is also provided to reverse the budget records for particle tracking simulations in which particles are tracked backwards from terminating to release locations (e.g., to compute capture zones).

Parameters:

  • filename (str or PathLike) – Path of the cell budget file.

  • precision (string) – Precision of floating point budget data in the file. Accepted values are ‘single’ or ‘double’. Default is ‘single’.

  • verbose (bool) – Toggle logging output. Default is False.

Examples

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

Close the file handle

export(filename: str | PathLike, kstpkper: list | None = None, text: str | list | None = None, **kwargs)[source]

Export budget data to a binary file.

Parameters:

  • filename (str or PathLike) – Path to output budget file

  • kstpkper (list of tuples, optional) – Subset of (kstp, kper) tuples to export. If None, exports all time steps.

  • text (str or list of str, optional) – Budget term(s) to export. If None, exports all terms. Examples: ‘FLOW-JA-FACE’, [‘STORAGE’, ‘CONSTANT HEAD’]

  • **kwargs – Additional keyword arguments: - precision : str, ‘single’ or ‘double’ (default is the file’s precision) - verbose : bool, print progress messages

Examples

>>> cbc = CellBudgetFile('input.cbc')
>>> # Export all data
>>> cbc.export('output.cbc')
>>> # Export specific time steps
>>> cbc.export('output.cbc', kstpkper=[(1, 0), (1, 1)])
>>> # Export specific budget terms
>>> cbc.export('output.cbc', text='FLOW-JA-FACE')
>>> # Export specific terms and time steps
>>> cbc.export(
...     'output.cbc', kstpkper=[(1, 0)], text=['STORAGE', 'FLOW-JA-FACE']
... )
get_data(idx=None, kstpkper=None, totim=None, text=None, paknam=None, paknam2=None, full3D=False) → list | ndarray[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.

  • paknam (str) – The from package name for the record.

  • paknam2 (str) – The to package name for the record. This argument can be useful for MODFLOW 6 budget files if multiple packages of the same type are specified. The paknam2 argument can be specified as the package name (not the package type) in order to retrieve budget data for a specific named package.

  • 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 tuples (stress period, time step) in the file. Indices are 0-based, use the kstpkper attribute for 1-based.

Returns:

List of unique combinations of stress period & time step indices (0-based) in the binary file

Return type:

list of (kstp, kper) tuples

get_nrecords()[source]

Return the number of records in the file

Returns:

  • int – Number of records in the file.

  • .. deprecated:: 3.8.0 – Use len() instead.

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, variable='q')[source]

Get a time series from the binary budget file.

Parameters:

  • idx (int, tuple of ints, or list of such) –

    Acceptable values depend on grid type:

    • Structured grids (DIS): (layer, row, column) or list of such

    • Vertex grids (DISV): (layer, cellid) or list of such

    • Unstructured grids (DISU): node number or list of such

    All indices must be zero-based.

    For backwards compatibility, DISV and DISU grids also accept the old 3-tuple format with dummy values: (layer, dummy, cellid) for DISV and (dummy, dummy, node) for DISU.

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

  • variable (str, optional) – Variable name to extract from the budget record. Default is ‘q’. For records with auxiliary variables (e.g., ‘DATA-SPDIS’, ‘DATA-SAT’), this can be used to access auxiliary data. Examples include ‘qx’, ‘qy’, ‘qz’ for specific discharge components.

Returns:

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

Return type:

numpy array

Notes

Index ranges (zero-based):

  • DIS: 0 <= layer < nlay, 0 <= row < nrow, 0 <= col < ncol

  • DISV: 0 <= layer < nlay, 0 <= cellid < ncpl

  • DISU: 0 <= node < nnodes

Examples

>>> # DIS grid: layer 0, row 5, column 5
>>> ts = cbb.get_ts(idx=(0, 5, 5), text='DATA-SPDIS', variable='qx')

>>> # DISV grid: layer 0, cell 12
>>> ts = cbb.get_ts(idx=(0, 12), text='DATA-SPDIS', variable='qx')

>>> # DISU grid: node 10
>>> ts = cbb.get_ts(idx=10, text='FLOW-JA-FACE')
get_unique_package_names(decode=False, to=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

Deprecated since version 3.8.0: Use headers instead.

list_unique_packages(to=False)[source]

Print a list of unique package names

Deprecated since version 3.8.0: Use headers.paknam.drop_duplicates() or headers.paknam2.drop_duplicates() instead.

list_unique_records()[source]

Print a list of unique record names

Deprecated since version 3.8.0: Use headers[[“text”, “imeth”]].drop_duplicates() instead.

property nrecords

Return the number of records (headers) in the file.

Deprecated since version 3.8.0: Use len() instead.

reverse(filename: PathLike | None = None)[source]

Reverse the time order and signs of the currently loaded binary cell budget file. If a file name is not provided or if the provided name is the same as the existing filename, the file will be overwritten and reloaded.

Notes

While HeadFile.reverse() reverses only the temporal order of head data, this method must reverse not only the order but also the sign (direction) of the model’s intercell flows.

filenamestr or PathLike, optional

Path of the reversed binary cell budget file.

to_geodataframe(gdf=None, modelgrid=None, idx=None, kstpkper=None, totim=None, text=None)[source]
classmethod write(filename, data, text='FLOW-JA-FACE', imeth=1, precision='double', delt=1.0, pertim=None, totim=None, nlay=None, nrow=None, ncol=None, ncpl=None, nnodes=None, kstpkper=None, verbose=False)[source]

Write budget data directly to a binary file.

This classmethod writes budget data arrays to a binary cell budget file and returns a CellBudgetFile instance with the file open.

Parameters:

  • filename (str or PathLike) – Path for the output file

  • data (ndarray, dict, or list) –

    Budget data in one of three formats:

    1. Array with time dimension: - Shape (ntimes, nlay, nrow, ncol) or (ntimes, …) for grid data - First dimension is time, creates one record per time step - Requires kstpkper parameter or uses sequential (1,1), (1,2), (1,3), …

    2. Dict mapping (kstp, kper) tuples to arrays: {(kstp, kper): array, …} - For imeth=1: arrays should be 1D (flattened cell-by-cell data)

    3. List of dicts with full metadata: [{‘data’: array, ‘kstp’: int, ‘kper’: int, ‘text’: str (optional),

      ’totim’: float (optional), ‘pertim’: float (optional), ‘delt’: float (optional), ‘imeth’: int (optional)}, …]

      • Allows per-record customization of all parameters

  • text (str or list, default "FLOW-JA-FACE") – Budget text identifier (will be padded to 16 characters). If list, must match length of data records.

  • imeth (int, default 1) – Method code: - 1: Full 3D array (most common) - 6: List-based budget (for MF6 advanced packages)

  • precision (str, default "double") – Precision of floating point data: ‘single’ or ‘double’

  • delt (float or dict, default 1.0) – Time step length. Can be: - float/int: Use same value for all records - dict: Maps (kstp, kper) to delt values

  • pertim (float or dict, optional) –

    Period time. Can be: - float/int: Use same value for all records (only valid with

    single timestep)

    • dict: Maps (kstp, kper) to pertim values

    • None: Defaults to totim

  • totim (float or dict, optional) –

    Total simulation time. Can be: - float/int: Use same value for all records (only valid with

    single timestep)

    • dict: Maps (kstp, kper) to totim values

    • None: Defaults to sequential counter (1.0, 2.0, 3.0, …)

  • nlay (int, optional) – Number of layers (DIS, DISV). Inferred if None.

  • nrow (int, optional) – Number of rows (DIS only). Inferred if None.

  • ncol (int, optional) – Number of columns (DIS only). Inferred if None.

  • ncpl (int, optional) – Number of cells per layer (DISV only). Inferred if None.

  • nnodes (int, optional) – Total number of nodes (DISU only). Inferred if None.

  • kstpkper (list of tuples, optional) – Time step/period mapping for array data with time dimension. List of (kstp, kper) tuples, one per time step. If None, uses sequential numbering: (1,1), (1,2), (1,3), … Ignored if data is dict or list format.

  • verbose (bool, default False) – Print progress messages

Returns:

Instance with the written file open

Return type:

CellBudgetFile

Notes

Discretization types are determined by which parameters are provided: - DIS (structured): nlay, nrow, ncol - DISV (vertically staggered): nlay, ncpl - DISU (unstructured): nnodes

If no dimensions are provided, they will be inferred from array shapes.

Examples

>>> import numpy as np
>>> from flopy.utils import CellBudgetFile
>>>
>>> # Write budget data for two time steps
>>> flow1 = np.random.rand(6000)
>>> flow2 = np.random.rand(6000)
>>> data = {
...     (1, 1): flow1,
...     (1, 2): flow2,
... }
>>> cbb = CellBudgetFile.write(
...     'output.cbc', data, text='FLOW-JA-FACE', nlay=3, nrow=10, ncol=20
... )
>>>
>>> # Or with list of records (dicts)
>>> CellBudgetFile.write('output.cbc', [
...     {'data': flow1, 'kstp': 1, 'kper': 1, 'totim': 10.0,
...      'text': 'FLOW-JA-FACE'},
...     {'data': flow2, 'kstp': 1, 'kper': 2, 'totim': 20.0,
...      'text': 'FLOW-JA-FACE'},
... ], nlay=3, nrow=10, ncol=20)
class HeadFile(filename: str | PathLike, text='head', precision='auto', verbose=False, **kwargs)[source]

Bases: BinaryLayerFile

The HeadFile class provides simple ways to retrieve and manipulate 2D or 3D head arrays, or time series arrays for one or more cells, from a binary head output file. A utility method is also provided to reverse the order of head data, for use with particle tracking simulations in which particles are tracked backwards in time from terminating to release locations (e.g., to compute capture zones).

Parameters:

  • filename (str or PathLike) – Path of the head file.

  • text (string) – Name of the text string in the head file. Default is ‘head’.

  • precision (string) – Precision of floating point head data in the value. Accepted values are ‘auto’, ‘single’ or ‘double’. Default is ‘auto’, which enables automatic detection of precision.

  • verbose (bool) – Toggle logging output. Default is False.

Examples

>>> import flopy.utils.binaryfile as bf
>>> hdobj = bf.HeadFile('model.hds', precision='single')
>>> hdobj.headers
>>> rec = hdobj.get_data(kstpkper=(0, 49))

>>> ddnobj = bf.HeadFile('model.ddn', text='drawdown', precision='single')
>>> ddnobj.headers
>>> rec = ddnobj.get_data(totim=100.)
export(filename: str | PathLike, kstpkper: list | None = None, **kwargs)[source]

Export head data to a binary file.

Parameters:

  • filename (str or PathLike) – Path to output head file

  • kstpkper (list of tuples, optional) – Subset of (kstp, kper) tuples to export. If None, exports all time steps.

  • **kwargs – Additional keyword arguments: - text : str, identifier for head data (default uses current file’s text) - precision : str, ‘single’ or ‘double’ (default is the file’s precision) - verbose : bool, print progress messages

Examples

>>> hds = HeadFile('input.hds')
>>> # Export all time steps
>>> hds.export('output.hds')
>>> # Export specific time steps
>>> hds.export('output.hds', kstpkper=[(1, 0), (1, 1)])
reverse(filename: PathLike | None = None)[source]

Reverse the time order of the currently loaded binary head file. If a head file name is not provided or the provided name is the same as the existing filename, the file will be overwritten and reloaded.

Parameters:

filename (str or PathLike, optional) – Path of the reversed binary head file.

classmethod write(filename, data, nrow=None, ncol=None, nlay=None, ncpl=None, nnodes=None, text='head', precision='double', totim=None, pertim=None, kstpkper=None, verbose=False)[source]

Write head data directly to a binary file.

This classmethod writes head data arrays to a binary head file and returns a HeadFile instance with the file open.

Parameters:

  • filename (str or PathLike) – Path for the output file

  • data (ndarray, dict, or list) –

    Head data in one of three formats:

    1. Array with time dimension: - Shape (ntimes, nlay, nrow, ncol) or (ntimes, nrow, ncol) - First dimension is time, creates one record per time step - Requires kstpkper parameter or uses sequential (1,1), (1,2), (1,3), …

    2. Dict mapping (kstp, kper) tuples to arrays: {(kstp, kper): array, …} - Arrays should be 2D (nrow, ncol) or 3D (nlay, nrow, ncol)

    3. List of dicts with full metadata: [{‘data’: array, ‘kstp’: int, ‘kper’: int,

      ’totim’: float, ‘pertim’: float, ‘ilay’: int (optional)}, …]

      • Each dict represents one layer at one timestep

      • ilay defaults to 1 if not provided

  • nrow (int, optional) – Number of rows (DIS only). Inferred if None.

  • ncol (int, optional) – Number of columns (DIS only). Inferred if None.

  • nlay (int, optional) – Number of layers (DIS, DISV). Inferred if None.

  • ncpl (int, optional) – Number of cells per layer (DISV only). Inferred if None.

  • nnodes (int, optional) – Total number of nodes (DISU only). Inferred if None.

  • text (str, default "head") – Text identifier for the head data (will be padded to 16 characters)

  • precision (str, default "double") – Precision of floating point data: ‘single’ or ‘double’

  • totim (float, dict, or list, optional) –

    Total time values. Can be: - float/int: Use same value for all records (only valid with

    single timestep)

    • dict: Maps (kstp, kper) to totim values

    • list: Should match order of data

    • None: Defaults to sequential counter (1.0, 2.0, 3.0, …)

  • pertim (float, dict, or list, optional) –

    Period time values. Can be: - float/int: Use same value for all records (only valid with

    single timestep)

    • dict: Maps (kstp, kper) to pertim values

    • list: Should match order of data

    • None: Defaults to totim

  • kstpkper (list of tuples, optional) – Time step/period mapping for array data with time dimension. List of (kstp, kper) tuples, one per time step. If None, uses sequential numbering: (1,1), (1,2), (1,3), … Ignored if data is dict or list format.

  • verbose (bool, default False) – Print progress messages

Returns:

Instance with the written file open

Return type:

HeadFile

Notes

Discretization types are determined by which parameters are provided: - DIS (structured): nlay, nrow, ncol - DISV (vertically staggered): nlay, ncpl - DISU (unstructured): nnodes

Examples

>>> import numpy as np
>>> from flopy.utils import HeadFile
>>>
>>> # Write head data for two time steps
>>> head1 = np.random.rand(3, 10, 20)  # 3 layers, 10 rows, 20 cols
>>> head2 = np.random.rand(3, 10, 20)
>>> data = {
...     (1, 1): head1,
...     (1, 2): head2,
... }
>>> hds = HeadFile.write('output.hds', data)
>>> hds.get_times()
[1.0, 2.0]
>>>
>>> # Or with explicit time values
>>> data_with_times = [
...     {'data': head1, 'kstp': 1, 'kper': 1, 'totim': 10.0, 'pertim': 10.0},
...     {'data': head2, 'kstp': 1, 'kper': 2, 'totim': 20.0, 'pertim': 10.0},
... ]
>>> HeadFile.write('output.hds', data_with_times)
class HeadUFile(filename: str | PathLike, text='headu', precision='auto', verbose=False, **kwargs)[source]

Bases: BinaryLayerFile

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.

Parameters:

  • filename (str or PathLike) – Path of the head file

  • text (string) – Name of the text string in the head file. Default is ‘headu’.

  • precision (string) – Precision of the floating point head data in the file. Accepted values are ‘auto’, ‘single’ or ‘double’. Default is ‘auto’, which enables precision to be automatically detected.

  • verbose (bool) – Toggle logging output. Default is False.

Notes

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 ints pointing to the 1st byte of data for the corresponding data arrays. This class overrides methods in the parent class so that the proper sized arrays are created: for unstructured grids, nrow and ncol are the starting and ending node numbers for layer, ilay.

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.headers
>>> usgheads = hdobj.get_data(kstpkper=(0, 49))
get_alldata(mflay=None, nodata=-9999)[source]

Get all data from the USG head file.

Parameters:

  • mflay (integer) – MODFLOW zero-based layer number to return. For USG files, this parameter is required (cannot be None). (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 – Array has size (ntimes, ncells_in_layer) when mflay is specified.

Return type:

numpy array

Raises:

NotImplementedError – Raised when mflay=None. USG head files contain ragged arrays with variable-sized data per layer, which cannot be converted to a uniform numpy array when retrieving all layers.

Notes

For MODFLOW-USG files, the mflay parameter must be specified to retrieve data for a single layer across all timesteps. To get all layers for a specific timestep, use get_data() instead.

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: 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.headers
>>> rec = ucnobj.get_data(kstpkper=(0, 0))
binaryread(file, vartype, shape=(1,), charlen=16)[source]

Read character bytes, scalar or array values from a binary file.

Parameters:

  • file (file object) – is an open file object

  • vartype (type) – is the return variable type: bytes, numpy.int32, numpy.float32, or numpy.float64. Using str is deprecated since bytes is preferred.

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

  • charlen (int, default 16) – is the length character bytes. Note that arrays of bytes cannot be returned, only multi-character bytes. Shape has no affect on bytes.

Raises:

EOFError –

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.

Deprecated since version 3.8.0: Use binaryread() instead.

get_concentration_file_type(filename: str | PathLike, precision)[source]

Method to check header and determine if the concentration file is a MT3D like file or a MF6 GWT like concentration file

Parameters:

  • filename (str or PathLike) – Path of binary MODFLOW file to determine precision.

  • precision (str) – double or single

Returns:

Result will be ucn or head

Return type:

str

get_headfile_precision(filename: str | PathLike)[source]

Determine precision of a MODFLOW head file.

Parameters:

filename (str or PathLike) – Path of binary MODFLOW file to determine precision.

Returns:

Result will be unknown, single, or double

Return type:

str

join_struct_arrays(arrays)[source]

Simple function that can join two numpy structured arrays.