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 flopy.utils.util_array.ArrayFormat(u2d, python=None, fortran=None, array_free_format=None)

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)

Attributes

fortran (str) fortran format output descriptor (e.g. (100G15.6)
py (str) python format output descriptor (e.g. “{0:15.6E}”)
numpy (str) numpy format output descriptor (e.g. “%15.6e”)
npl (int) number if items per line of output
width (int) the width of the formatted numeric output
decimal (int) the number of decimal digits in the numeric output
format (str) the output format type e.g. I, G, E, etc
free (bool) free format flag
binary (bool) binary format flag

Methods

decode_fortran_descriptor(fd) Decode fortran descriptor
get_default_numpy_fmt ((dtype) a static method to get a default numpy dtype - used for loading
static decode_fortran_descriptor(fd)

Decode fortran descriptor

Parameters:fd : str
Returns:npl, fmt, width, decimal : int, str, int, int
class flopy.utils.util_array.Transient2d(model, shape, dtype, value, name, fmtin=None, cnstnt=1.0, iprn=-1, ext_filename=None, locat=None, bin=False, array_free_format=None)

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.int,np.float32,np.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)

Attributes

transient_2ds (dict{kper:Util2d}) the transient sequence of Util2d objects

Methods

get_kper_entry(kper) get the file entry info for a given kper
build_transient_sequence()

parse self.__value into a dict{kper:Util2d}

classmethod from_4d(model, pak_name, m4ds)

construct a Transient2d instance from a dict(name: (masked) 4d numpy.ndarray Parameters ———-

model : flopy.mbase derived type pak_name : str package name (e.g. RCH) m4ds : dict(name,(masked) 4d numpy.ndarray)

each ndarray must have shape (nper,1,nrow,ncol). if an entire (nrow,ncol) slice is np.NaN, then that kper is skipped.
Transient2d instance
get_kper_entry(kper)

get the file entry info for a given kper returns (itmp,file entry string from Util2d)

plot(filename_base=None, file_extension=None, **kwargs)

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

**kwargs : dict

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)

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)

inactive
: bool

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

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.

kper
: str

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

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

Examples

>>> import flopy
>>> ml = flopy.modflow.Modflow.load('test.nam')
>>> ml.rch.rech.plot()
to_shapefile(filename)
Export transient 2D data to a shapefile (as polygons). Adds an
attribute for each unique Util2d instance in self.data
Parameters:

filename : str

Shapefile name to write

Returns:

None

Examples

>>> import flopy
>>> ml = flopy.modflow.Modflow.load('test.nam')
>>> ml.rch.rech.as_shapefile('test_rech.shp')
class flopy.utils.util_array.Transient3d(model, shape, dtype, value, name, fmtin=None, cnstnt=1.0, iprn=-1, ext_filename=None, locat=None, bin=False, array_free_format=None)

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.int,np.float32,np.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)

Attributes

transient_3ds (dict{kper:Util3d}) the transient sequence of Util3d objects

Methods

get_kper_entry(kper) get the file entry info for a given kper
build_transient_sequence()

parse self.__value into a dict{kper:Util3d}

get_kper_entry(kper)

get the file entry info for a given kper returns (itmp,file entry string from Util3d)

class flopy.utils.util_array.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)

Util2d class for handling 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 : lenght 3 tuple

shape of the 3-D array

dtype : [np.int,np.float32,np.bool]

the type of the data

value : variable

the data to be assigned to the 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)

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.

Attributes

array Get the COPY of array representation of value attribute with the effects of the control record multiplier applied.
how (str) the str flag to control how the array is written to the model input files e.g. “constant”,”internal”,”external”,”openclose”
format (ArrayFormat object) controls the ASCII representation of the numeric array

Methods

get_file_entry (string) get the model input file string including the control record
array

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

Returns:

array : numpy.ndarray

Copy of the array with the multiplier applied.

static array2string(shape, data, fortran_format='(FREE)', python_format=None)

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.

static load(f_handle, model, shape, dtype, name, ext_unit_dict=None, array_free_format=None, array_format='modflow')

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_block(shape, file_in, dtype)

load a (possibly wrapped format) array from a mt3d block (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.

static load_txt(shape, file_in, dtype, fmtin)

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

model_file_path

where the model expects the file to be

Returns:file_path (str): path relative to the name file
static parse_control_record(line, current_unit=None, dtype=<class 'numpy.float32'>, ext_unit_dict=None, array_format=None)

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)

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)

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

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)

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)

inactive
: bool

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

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.

Returns:

out : list

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

Examples

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

where python is going to write the file Returns ——-

file_path (str) : path relative to python: includes model_ws
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
to_shapefile(filename)

Export 2-D model data to a shapefile (as polygons) of self.array

Parameters:

filename : str

Shapefile name to write

Returns:

None

Examples

>>> import flopy
>>> ml = flopy.modflow.Modflow.load('test.nam')
>>> ml.dis.top.as_shapefile('test_top.shp')
class flopy.utils.util_array.Util3d(model, shape, dtype, value, name, fmtin=None, cnstnt=1.0, iprn=-1, locat=None, ext_unit_dict=None, array_free_format=None)
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.int,np.float32,np.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 defaut is False)

Attributes

array Return a numpy array of the 3D shape.

Methods

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

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

plot(filename_base=None, file_extension=None, mflay=None, fignum=None, **kwargs)

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

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)

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)

inactive
: bool

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

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.

Returns:

out : list

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

Examples

>>> import flopy
>>> ml = flopy.modflow.Modflow.load('test.nam')
>>> ml.lpf.hk.plot()
to_shapefile(filename)
Export 3-D model data to shapefile (polygons). Adds an
attribute for each Util2d in self.u2ds
Parameters:

filename : str

Shapefile name to write

Returns:

None

Examples

>>> import flopy
>>> ml = flopy.modflow.Modflow.load('test.nam')
>>> ml.lpf.hk.to_shapefile('test_hk.shp')
flopy.utils.util_array.read1d(f, a)

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