flopy.utils.util_array module

util_array module. Contains the util_2d, util_3d and transient_2d classes.: These classes encapsulate modflow-style array inputs away from the individual packages. The end-user should not need to instantiate these classes directly.

class ArrayFormat(u2d, python=None, fortran=None, array_free_format=None)[source]

Bases: object

ArrayFormat class for handling various output format types for both MODFLOW and flopy

Parameters:

u2d (Util2d instance) –
python (str (optional)) – python-style output format descriptor e.g. {0:15.6e}
fortran (str (optional)) – fortran style output format descriptor e.g. (2E15.6)

fortran

fortran format output descriptor (e.g. (100G15.6)

Type:: str

py

python format output descriptor (e.g. “{0:15.6E}”)

Type:: str

numpy

numpy format output descriptor (e.g. “%15.6e”)

Type:: str

npl

number if items per line of output

Type:: int

width

the width of the formatted numeric output

Type:: int

decimal

the number of decimal digits in the numeric output

Type:: int

format

the output format type e.g. I, G, E, etc

Type:: str

free

free format flag

Type:: bool

binary

binary format flag

Type:: bool

get_default_numpy_fmt : (dtype : [np.int32, np.float32]): a static method to get a default numpy dtype - used for loading

decode_fortran_descriptor : (fd : str): a static method to decode fortran descriptors into npl, format, width, decimal.

Notes

Examples

property array_free_format

property binary

property decimal

static decode_fortran_descriptor(fd)[source]

Decode fortran descriptor

Parameters:: fd (str) –
Returns:: npl, fmt, width, decimal
Return type:: int, str, int, int

classmethod float()[source]

property format

property fortran

property free

static get_default_numpy_fmt(dtype)[source]

classmethod integer()[source]

property npl

property numpy

property py

property width

class Transient2d(model, shape, dtype, value, name, fmtin=None, cnstnt=1.0, iprn=-1, ext_filename=None, locat=None, bin=False, array_free_format=None)[source]

Bases: DataInterface

Transient2d class for handling time-dependent 2-D model arrays. just a thin wrapper around Util2d

Parameters:

model (model object) – The model object (of type flopy.modflow.mf.Modflow) to which this package will be added.
shape (length 2 tuple) – shape of the 2-D transient arrays, typically (nrow,ncol)
dtype ([np.int32, np.float32, bool]) – the type of the data
value (variable) – the data to be assigned to the 2-D arrays. Typically a dict of {kper:value}, where kper is the zero-based stress period to assign a value to. Value should be cast-able to Util2d instance can be a scalar, list, or ndarray is the array value is constant in time.
name (string) – name of the property, used for writing comments to input files and for forming external files names (if needed)
fmtin (string) – modflow fmtin variable (optional). (the default is None)
cnstnt (string) – modflow cnstnt variable (optional) (the default is 1.0)
iprn (int) – modflow iprn variable (optional) (the default is -1)
locat (int) –
modflow locat variable (optional) (the default is None). If the model instance does not support free format and the external flag is not set and the value is a simple scalar, then locat must be explicitly passed as it is the unit number

to read the array from
ext_filename (string) – the external filename to write the array representation to (optional) (the default is None) . If type(value) is a string and is an accessible filename, the ext_filename is reset to value.
bin (bool) – flag to control writing external arrays as binary (optional) (the default is False)

transient_2ds

the transient sequence of Util2d objects

Type:: dict{kper:Util2d}

get_kper_entry : (itmp,string): get the itmp value and the Util2d file entry of the value in transient_2ds in bin kper. if kper < min(Transient2d.keys()), return (1,zero_entry<Util2d>). If kper > < min(Transient2d.keys()), but is not found in Transient2d.keys(), return (-1,’’)

Notes

Examples

property array

build_transient_sequence()[source]: parse self.__value into a dict{kper:Util2d}

property data_type

property dtype

export(f, **kwargs)[source]

classmethod from_4d(model, pak_name, m4ds)[source]

construct a Transient2d instance from a dict(name: (masked) 4d numpy.ndarray :param model: :type model: flopy.mbase derived type :param pak_name: :type pak_name: str package name (e.g. RCH) :param m4ds: each ndarray must have shape (nper,1,nrow,ncol).

if an entire (nrow,ncol) slice is np.nan, then that kper is skipped.

Return type:: Transient2d instance

get_kper_entry(kper)[source]: Get the file entry info for a given kper returns (itmp,file entry string from Util2d)

get_zero_2d(kper)[source]

static masked4d_array_to_kper_dict(m4d)[source]

property model

property name

plot(filename_base=None, file_extension=None, kper=0, fignum=None, **kwargs)[source]

Plot transient 2-D model input data

Parameters:

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)
file_extension (str) – Valid matplotlib.pyplot file extension for savefig(). Only used if filename_base is not None. (default is ‘png’)
kper (int or str) – model stress period. if ‘all’ is provided, all stress periods will be plotted
fignum (list or int) – Figure numbers for plot title
**kwargs (dict) –

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

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

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

inactivebool
Boolean used to determine if a black overlay in inactive cells in a layer will be displayed. (default is True)

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

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

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

masked_valueslist
List of unique values to be excluded from the plot.

kperstr
MODFLOW zero-based stress period number to return. If kper=’all’ then data for all stress period will be extracted. (default is zero).

Returns:

out – Empty list is returned if filename_base is not None. Otherwise a list of matplotlib.pyplot.axis is returned.

Return type:

list

Notes

Examples

>>> import flopy
>>> ml = flopy.modflow.Modflow.load('test.nam')
>>> ml.rch.rech.plot()

property plottable

class Transient3d(model, shape, dtype, value, name, fmtin=None, cnstnt=1.0, iprn=-1, ext_filename=None, locat=None, bin=False, array_free_format=None)[source]

Bases: DataInterface

Transient3d class for handling time-dependent 3-D model arrays. just a thin wrapper around Util3d

Parameters:

model (model object) – The model object (of type flopy.modflow.mf.Modflow) to which this package will be added.
shape (length 3 tuple) – shape of the 3-D transient arrays, typically (nlay,nrow,ncol)
dtype ([np.int32, np.float32, bool]) – the type of the data
value (variable) – the data to be assigned to the 3-D arrays. Typically a dict of {kper:value}, where kper is the zero-based stress period to assign a value to. Value should be cast-able to Util2d instance can be a scalar, list, or ndarray is the array value is constant in time.
name (string) – name of the property, used for writing comments to input files and for forming external files names (if needed)
fmtin (string) – modflow fmtin variable (optional). (the default is None)
cnstnt (string) – modflow cnstnt variable (optional) (the default is 1.0)
iprn (int) – modflow iprn variable (optional) (the default is -1)
locat (int) –
modflow locat variable (optional) (the default is None). If the model instance does not support free format and the external flag is not set and the value is a simple scalar, then locat must be explicitly passed as it is the unit number

to read the array from
ext_filename (string) – the external filename to write the array representation to (optional) (the default is None) . If type(value) is a string and is an accessible filename, the ext_filename is reset to value.
bin (bool) – flag to control writing external arrays as binary (optional) (the default is False)

transient_3ds

the transient sequence of Util3d objects

Type:: dict{kper:Util3d}

get_kper_entry : (itmp,string): get the itmp value and the Util2d file entry of the value in transient_2ds in bin kper. if kper < min(Transient2d.keys()), return (1,zero_entry<Util2d>). If kper > < min(Transient2d.keys()), but is not found in Transient2d.keys(), return (-1,’’)

Notes

Examples

property array

build_transient_sequence()[source]: parse self.__value into a dict{kper:Util3d}

property data_type

property dtype

get_kper_entry(kper)[source]: get the file entry info for a given kper returns (itmp,file entry string from Util3d)

get_zero_3d(kper)[source]

property model

property name

property plottable

class Util2d(model, shape, dtype, value, name, fmtin=None, cnstnt=1.0, iprn=-1, ext_filename=None, locat=None, bin=False, how=None, array_free_format=None)[source]

Bases: DataInterface

Util2d class for handling 1- or 2-D model arrays

Parameters:

model (model object) – The model object (of type flopy.modflow.mf.Modflow) to which this package will be added.
shape (tuple) – Shape of the 1- or 2-D array
dtype ([np.int32, np.float32, bool]) – the type of the data
value (variable) – the data to be assigned to the 1- or 2-D array. can be a scalar, list, ndarray, or filename
name (string) – name of the property (optional). (the default is None
fmtin (string) – modflow fmtin variable (optional). (the default is None)
cnstnt (string) – modflow cnstnt variable (optional) (the default is 1.0)
iprn (int) – modflow iprn variable (optional) (the default is -1)
locat (int) –
modflow locat variable (optional) (the default is None). If the model instance does not support free format and the external flag is not set and the value is a simple scalar, then locat must be explicitly passed as it is the unit number

to read the array from)
ext_filename (string) – the external filename to write the array representation to (optional) (the default is None) . If type(value) is a string and is an accessible filename, the ext_filename is reset to value.
bin (bool) – flag to control writing external arrays as binary (optional) (the default is False)

array

the array representation of the 2-D object

Type:: np.ndarray

how

the str flag to control how the array is written to the model input files e.g. “constant”,”internal”,”external”,”openclose”

Type:: str

format

controls the ASCII representation of the numeric array

Type:: ArrayFormat object

get_file_entry : string: get the model input file string including the control record

Notes

If value is a valid filename and model.external_path is None, then a copy of the file is made and placed in model.model_ws directory.

If value is a valid filename and model.external_path is not None, then a copy of the file is made a placed in the external_path directory.

If value is a scalar, it is always written as a constant, regardless of the model.external_path setting.

If value is an array and model.external_path is not None, then the array is written out in the external_path directory. The name of the file that holds the array is created from the name attribute. If the model supports “free format”, then the array is accessed via the “open/close” approach. Otherwise, a unit number and filename is added to the name file.

If value is an array and model.external_path is None, then the array is written internally to the model input file.

Examples

all()[source]

property array

Get the COPY of array representation of value attribute with the effects of the control record multiplier applied.

Returns:: array – Copy of the array with the multiplier applied.
Return type:: numpy.ndarray

Note

.array is a COPY of the array representation as seen by the model - with the effects of the control record multiplier applied.

static array2string(shape, data, fortran_format='(FREE)', python_format=None)[source]: return a string representation of a (possibly wrapped format) array from a file (self.__value) and casts to the proper type (self._dtype) made static to support the load functionality this routine now supports fixed format arrays where the numbers may touch.

property cnstnt_str

property data_type

property dtype

export(f, **kwargs)[source]

property filename

property format

get_constant_cr(value)[source]

get_external_cr()[source]

get_file_entry(how=None)[source]

get_internal_cr()[source]

get_openclose_cr()[source]

get_value()[source]

property how

classmethod load(f_handle, model, shape, dtype, name, ext_unit_dict=None, array_free_format=None, array_format='modflow')[source]: functionality to load Util2d instance from an existing model input file. external and internal record types must be fully loaded if you are using fixed format record types,make sure ext_unit_dict has been initialized from the NAM file

static load_bin(shape, file_in, dtype, bintype=None)[source]

Load unformatted file to a 2-D array

Parameters:

shape (tuple of int) – One or two array dimensions
file_in (file or str) – Filename or file handle
dtype (np.int32 or np.float32) – Data type of unformatted file and Numpy array; use np.int32 for Fortran’s INTEGER, and np.float32 for Fortran’s REAL data types.
bintype (str) – Normally ‘Head’

Notes

This method is similar to MODFLOW’s U2DREL and U2DINT subroutines, but only for unformatted files.

Return type:: 2-D array

static load_block(shape, file_in, dtype)[source]

Load block format from a MT3D file to a 2-D array

Parameters:

shape (tuple of int) – Array dimensions (nrow, ncol)
file_in (file or str) – Filename or file handle
dtype (np.int32 or np.float32) –

Return type:

2-D array

static load_txt(shape, file_in, dtype, fmtin)[source]

Load formatted file to a 1-D or 2-D array

Parameters:

shape (tuple of int) – One or two array dimensions
file_in (file or str) – Filename or file handle
dtype (np.int32 or np.float32) –
fmtin (str) – Fortran array format descriptor, ‘(FREE)’ or e.g. ‘(10G11.4)’

Notes

This method is similar to MODFLOW’s U1DREL, U1DINT, U2DREL and U2DINT subroutines, but only for formatted files.

Return type:: 1-D or 2-D array

property model

property model_file_path

where the model expects the file to be

Returns:: file_path (str)
Return type:: path relative to the name file

property name

static parse_control_record(line, current_unit=None, dtype=<class 'numpy.float32'>, ext_unit_dict=None, array_format=None)[source]: parses a control record when reading an existing file rectifies fixed to free format current_unit (optional) indicates the unit number of the file being parsed

parse_value(value)[source]: parses and casts the raw value into an acceptable format for __value lot of defense here, so we can make assumptions later

plot(title=None, filename_base=None, file_extension=None, fignum=None, **kwargs)[source]

Plot 2-D model input data

Parameters:

title (str) – Plot title. If a plot title is not provide one will be created based on data name (self._name). (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)
file_extension (str) – Valid matplotlib.pyplot file extension for savefig(). Only used if filename_base is not None. (default is ‘png’)
**kwargs (dict) –

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

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

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

inactivebool
Boolean used to determine if a black overlay in inactive cells in a layer will be displayed. (default is True)

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

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

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

masked_valueslist
List of unique values to be excluded from the plot.

Returns:

out – Empty list is returned if filename_base is not None. Otherwise a list of matplotlib.pyplot.axis is returned.

Return type:

list

Notes

Examples

>>> import flopy
>>> ml = flopy.modflow.Modflow.load('test.nam')
>>> ml.dis.top.plot()

property plottable

property python_file_path: where python is going to write the file :returns: file_path (str) :rtype: path relative to python: includes model_ws

set_fmtin(fmtin)[source]

property string: get the string representation of value attribute

Note

the string representation DOES NOT include the effects of the control record multiplier - this method is used primarily for writing model input files

sum()[source]

unique()[source]

property vtype

static write_bin(shape, file_out, data, bintype=None, header_data=None)[source]

static write_txt(shape, file_out, data, fortran_format='(FREE)', python_format=None)[source]

class Util3d(model, shape, dtype, value, name, fmtin=None, cnstnt=1.0, iprn=-1, locat=None, ext_unit_dict=None, array_free_format=None)[source]

Bases: DataInterface

Util3d class for handling 3-D model arrays. just a thin wrapper around: Util2d

Parameters:

model (model object) – The model object (of type flopy.modflow.mf.Modflow) to which this package will be added.
shape (length 3 tuple) – shape of the 3-D array, typically (nlay,nrow,ncol)
dtype ([np.int32, np.float32, bool]) – the type of the data
value (variable) – the data to be assigned to the 3-D array. can be a scalar, list, or ndarray
name (string) – name of the property, used for writing comments to input files
fmtin (string) – modflow fmtin variable (optional). (the default is None)
cnstnt (string) – modflow cnstnt variable (optional) (the default is 1.0)
iprn (int) – modflow iprn variable (optional) (the default is -1)
locat (int) – modflow locat variable (optional) (the default is None). If the model instance does not support free format and the external flag is not set and the value is a simple scalar, then locat must be explicitly passed as it is the unit number to read the array from
ext_filename (string) – the external filename to write the array representation to (optional) (the default is None) . If type(value) is a string and is an accessible filename, the ext_filename is reset to value.
bin (bool) – flag to control writing external arrays as binary (optional) (the default is False)

array

the array representation of the 3-D object

Type:: np.ndarray

get_file_entry : string: get the model input file string including the control record for the entire 3-D property

Notes

Examples

property array: Return a numpy array of the 3D shape. If an unstructured model, then return an array of size nodes.

build_2d_instances()[source]

property data_type

property dtype

export(f, **kwargs)[source]

get_file_entry()[source]

get_value()[source]

classmethod load(f_handle, model, shape, dtype, name, ext_unit_dict=None, array_format=None)[source]

property model

property name

plot(filename_base=None, file_extension=None, mflay=None, fignum=None, **kwargs)[source]

Plot 3-D model input data

Parameters:

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)
file_extension (str) – Valid matplotlib.pyplot file extension for savefig(). Only used if filename_base is not None. (default is ‘png’)
mflay (int) – MODFLOW zero-based layer number to return. If None, then all all layers will be included. (default is None)
**kwargs (dict) –

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

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

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

inactivebool
Boolean used to determine if a black overlay in inactive cells in a layer will be displayed. (default is True)

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

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

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

masked_valueslist
List of unique values to be excluded from the plot.

Returns:

out – Empty list is returned if filename_base is not None. Otherwise a list of matplotlib.pyplot.axis is returned.

Return type:

list

Notes

Examples

>>> import flopy
>>> ml = flopy.modflow.Modflow.load('test.nam')
>>> ml.lpf.hk.plot()

property plottable

new_u2d(old_util2d, value)[source]

read1d(f, a)[source]: Fill the 1d array, a, with the correct number of values. Required in case lpf 1d arrays (chani, layvka, etc) extend over more than one line