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
-
array_free_format
¶
-
binary
-
decimal
-
static
decode_fortran_descriptor
(fd)[source]¶ Decode fortran descriptor
Parameters: fd (str) – Returns: npl, fmt, width, decimal Return type: int, str, int, int
-
format
-
fortran
-
free
-
npl
-
numpy
-
py
-
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:
flopy.datbase.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, 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)
-
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
-
array
¶
-
data_type
¶
-
dtype
¶
-
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.Returns: 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)
-
model
¶
-
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) –
- 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 – 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()
-
plotable
¶
-
to_shapefile
(filename)[source]¶ - 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: Return type: None Notes
Examples
>>> import flopy >>> ml = flopy.modflow.Modflow.load('test.nam') >>> ml.rch.rech.as_shapefile('test_rech.shp')
- model (model object) – The model object (of type
-
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:
flopy.datbase.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, 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)
-
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
-
array
¶
-
data_type
¶
-
dtype
¶
-
get_kper_entry
(kper)[source]¶ get the file entry info for a given kper returns (itmp,file entry string from Util3d)
-
model
¶
-
name
¶
-
plotable
¶
- model (model object) – The model object (of type
-
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:
flopy.datbase.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, np.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
-
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.
-
cnstnt_str
¶
-
data_type
¶
-
dtype
¶
-
filename
¶
-
format
-
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.
Returns: 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) –
Returns: 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.
Returns: Return type: 1-D or 2-D array
-
model
¶
-
model_file_path
¶ where the model expects the file to be
Returns: file_path (str) Return type: path relative to the name file
-
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) –
- 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 – 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()
-
plotable
¶
-
python_file_path
¶ where python is going to write the file :returns: file_path (str) :rtype: 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)[source]¶ Export 2-D model data to a shapefile (as polygons) of self.array
Parameters: filename (str) – Shapefile name to write Returns: Return type: None Notes
Examples
>>> import flopy >>> ml = flopy.modflow.Modflow.load('test.nam') >>> ml.dis.top.as_shapefile('test_top.shp')
-
vtype
¶
- model (model object) – The model object (of type
-
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:
flopy.datbase.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, 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)
-
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
-
array
Return a numpy array of the 3D shape. If an unstructured model, then return an array of size nodes.
-
data_type
¶
-
dtype
¶
-
classmethod
load
(f_handle, model, shape, dtype, name, ext_unit_dict=None, array_format=None)[source]¶
-
model
¶
-
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) –
- 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 – 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()
-
plotable
¶
-
to_shapefile
(filename)[source]¶ - 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: Return type: None Notes
Examples
>>> import flopy >>> ml = flopy.modflow.Modflow.load('test.nam') >>> ml.lpf.hk.to_shapefile('test_hk.shp')