flopy.mbase module

mbase module

This module contains the base model class from which all of the other models inherit from.

class BaseModel(modelname='modflowtest', namefile_ext='nam', exe_name: str | PathLike = 'mf2005', model_ws: str | PathLike = '.', structured=True, verbose=False, **kwargs)

Bases: ModelInterface

MODFLOW-based models base class.

Parameters:

• modelname (str, default "modflowtest") – Name of the model, which is also used for model file names.

• namefile_ext (str, default "nam") – Name file extension, without “.”

• exe_name (str or PathLike, default "mf2005") – Name or path of the modflow executable. If a name is provided, the executable must be on the system path.

• model_ws (str or PathLike, optional, default ".") – Path to the model workspace. Model files will be created in this directory. Default is the current working directory.

• structured (bool, default True) – Specify if model grid is structured (default) or unstructured.

• verbose (bool, default False) – Print additional information to the screen.

• **kwargs (dict, optional) – Used to define: xll/yll for the x- and y-coordinates of the lower-left corner of the grid, xul/yul for the x- and y-coordinates of the upper-left corner of the grid (deprecated), rotation for the grid rotation (default 0.0), crs for the coordinate reference system, and start_datetime for model start date (default “1-1-1970”).

add_existing_package(filename: str | PathLike, ptype=None, copy_to_model_ws=True)

Add an existing package to a model instance.

Parameters:

• filename (str or PathLike) – Path of the file to add as a package

• ptype (optional) – Model package type (e.g. “lpf”, “wel”, etc). If None then the file extension of the filename arg is used

• copy_to_model_ws (bool) – Copy the package file into the model workspace.

Return type:

None

add_external(fname: str | PathLike, unit, binflag=False, output=False)

Assign an external array so that it will be listed as a DATA or DATA(BINARY) entry in the name file. This will allow an outside file package to refer to it.

Parameters:

• fname (str or PathLike) – Path of external array

• unit (int) – Unit number of external array

• binflag (boolean, optional) – Binary or not, default is False

add_output(fname: str | PathLike, unit, binflag=False, package=None)

Assign an external array so that it will be listed as a DATA or DATA(BINARY) entry in the name file. This will allow an outside file package to refer to it.

Parameters:

• fname (str) – filename of external array

• unit (int) – unit number of external array

• binflag (boolean) – binary or not. (default is False)

add_output_file(unit, fname: str | PathLike | None = None, extension='cbc', binflag=True, package=None)

Add an ascii or binary output file for a package

Parameters:

• unit (int) – Unit number of external array

• fname (str or PathLike, optional) – Path of external array, default is None

• extension (str) – Extension to use for the cell-by-cell file. Only used if fname is None, default is cbc

• binflag (bool) – Whether the output file is a binary file, efault is True

• package (str) – The package the output file is attached to, default is None

add_package(p)

Add a package.

Parameters:

p (Package object) –

add_pop_key_list(key)

Add a external file unit number to a list that will be used to remove model output (typically binary) files from ext_unit_dict.

Parameters:

key (int) – file unit number

Examples

change_model_ws(new_pth: str | PathLike | None = '.', reset_external=False)

Change the model work space.

Parameters:

new_pth (str or PathLike) – Path of the new model workspace. If this path does not exist, it will be created. If no value (None) is given, the default is the present working directory.

Returns:

val – Can be used to see what packages are in the model, and can then be used with get_package to pull out individual packages.

Return type:

list of strings

check(f: str | PathLike | None = None, verbose=True, level=1)

Check model data for common errors.

Parameters:

• f (str or PathLike, optional, default None) – String defining file name or file handle for summary file of check method output. If a string is passed a file handle is created. If f is None, check method does not write results to a summary file. (default is None)

• verbose (bool) – Boolean flag used to determine if check method results are written to the screen

• level (int) – Check method analysis level. If level=0, summary checks are performed. If level=1, full checks are performed.

Return type:

None

Examples

>>> import flopy
>>> m = flopy.modflow.Modflow.load('model.nam')
>>> m.check()

property exename: str

export(f: str | PathLike, **kwargs)

Method to export a model to netcdf or shapefile based on the extension of the file name (.shp for shapefile, .nc for netcdf)

Parameters:

• f (str or PathLike) – The file path

• kwargs (keyword arguments) –

  modelgridflopy.discretization.Grid instance

  user supplied modelgrid which can be used for exporting in lieu of the modelgrid associated with the model object

Return type:

None or Netcdf object

get_ext_dict_attr(ext_unit_dict=None, unit=None, filetype=None, pop_key=True)

get_name_file_entries()

Get a string representation of the name file.

get_output(fname: str | PathLike | None = None, unit=None)

Get an output file from the model by specifying either the file name or the unit number.

Parameters:

• fname (str or PathLike, optional) – Path of output array

• unit (int, optional) – Unit number of output array

get_output_attribute(fname: str | PathLike | None = None, unit=None, attr=None)

Get an attribute of a model output file by specifying either the file name or the unit number.

Parameters:

• fname (str or PathLike, optional) – path of output array

• unit (int, optional) – Unit number of output array

get_package(name)

Get a package.

Parameters:

name (str) – Name of the package, ‘RIV’, ‘LPF’, etc. (case-insensitive).

Returns:

pp – Package object of type flopy.pakbase.Package

Return type:

Package object

has_package(name)

Check if package name is in package list.

Parameters:

name (str) – Name of the package, ‘DIS’, ‘BAS6’, etc. (case-insensitive).

Returns:

True if package name exists, otherwise False if not found.

Return type:

bool

property hdry

property hnoflo

property laycbd

property laytyp

load_results()

property model_ws: str

property modelgrid

property modeltime

property name

Get model name

Returns:

name – name of model

Return type:

str

property namefile: str

next_ext_unit()

Function to encapsulate next_ext_unit attribute

next_unit(i=None)

property packagelist

plot(SelPackList=None, **kwargs)

Plot 2-D, 3-D, transient 2-D, and stress period list (MfList) model input data

Parameters:

• SelPackList (bool or list) – List of of packages to plot. If SelPackList=None all packages are plotted. (default is None)

• **kwargs (dict) –

  filename_basestr

  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_extensionstr

  Valid matplotlib.pyplot file extension for savefig(). Only used if filename_base is not None. (default is ‘png’)

  mflayint

  MODFLOW zero-based layer number to return. If None, then all all layers will be included. (default is None)

  kperint

  MODFLOW zero-based stress period number to return. (default is zero)

  keystr

  MfList dictionary key. (default is None)

Returns:

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

Return type:

list

Notes

Examples

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

remove_external(fname: str | PathLike | None = None, unit=None)

Remove an external file from the model by specifying either the file name or the unit number.

Parameters:

• fname (str or PathLike, optional) – Path of external array

• unit (int, optional) – Unit number of external array

remove_output(fname: str | PathLike | None = None, unit=None)

Remove an output file from the model by specifying either the file name or the unit number.

Parameters:

• fname (str or PathLike, optional) – Path of output array

• unit (int, optional) – Unit number of output array

remove_package(pname)

Remove a package from this model

Parameters:

pname (string) – Name of the package, such as ‘RIV’, ‘BAS6’, etc.

run_model(silent=False, pause=False, report=False, normal_msg='normal termination') → Tuple[bool, List[str]]

This method will run the model using subprocess.Popen.

Parameters:

• silent (boolean) – Echo run information to screen (default is True).

• pause (boolean, optional) – Pause upon completion (default is False).

• report (boolean, optional) – Save stdout lines to a list (buff) which is returned by the method . (default is False).

• normal_msg (str) – Normal termination message used to determine if the run terminated normally. (default is ‘normal termination’)

Returns:

• success (boolean)

• buff (list of lines of stdout)

set_model_units()

Every model needs its own set_model_units method

set_output_attribute(fname: str | PathLike | None = None, unit=None, attr=None)

Set a variable in an output file from the model by specifying either the file name or the unit number and a dictionary with attributes to change.

Parameters:

• fname (str or PathLike, optional) – Path of output array

• unit (int, optional) – Unit number of output array

set_version(version)

to_shapefile(filename: str | PathLike, package_names=None, **kwargs)

Wrapper function for writing a shapefile for the model grid. If package_names is not None, then search through the requested packages looking for arrays that can be added to the shapefile as attributes

Parameters:

• filename (str or PathLike) – Path of the shapefile to write

• package_names (list of package names (e.g. ["dis","lpf"])) – Packages to export data arrays to shapefile. (default is None)

Return type:

None

Examples

>>> import flopy
>>> m = flopy.modflow.Modflow()
>>> m.to_shapefile('model.shp', SelPackList)

property verbose

property version

write_input(SelPackList=False, check=False)

Write the input.

Parameters:

SelPackList (False or list of packages) –

write_name_file()

Every Package needs its own writenamefile function

class FileData

Bases: object

add_file(fname, unit, binflag=False, output=False, package=None)

class FileDataEntry(fname, unit, binflag=False, output=False, package=None)

Bases: object

class ModelInterface

Bases: object

abstract check(f=None, verbose=True, level=1)

abstract property exename

abstract export(f, **kwargs)

get_package_list(ftype=None)

Get a list of all the package names.

Parameters:

ftype (str) – Type of package, ‘RIV’, ‘LPF’, etc.

Returns:

val – Can be used to see what packages are in the model, and can then be used with get_package to pull out individual packages.

Return type:

list of strings

abstract property hdry

abstract property hnoflo

abstract property laycbd

abstract property laytyp

abstract property model_ws

abstract property modelgrid

abstract property namefile

abstract property packagelist

abstract property solver_tols

update_modelgrid()

abstract property verbose

abstract property version

exception PackageLoadException(error, location='')

Bases: Exception

FloPy package load exception.

resolve_exe(exe_name: str | PathLike, forgive: bool = False) → str

Resolves the absolute path of the executable, raising FileNotFoundError if the executable cannot be found (set forgive to True to return None and warn instead of raising an error).

Parameters:

• exe_name (str or PathLike) – The executable’s name or path. If only the name is provided, the executable must be on the system path.

• forgive (bool) – If True and executable cannot be found, return None and warn rather than raising a FileNotFoundError. Defaults to False.

Returns:

str

Return type:

absolute path to the executable

run_model(exe_name: str | PathLike, namefile: str | None, model_ws: str | PathLike = '.', silent=False, pause=False, report=False, processors=None, normal_msg='normal termination', use_async=False, cargs=None, custom_print=None) → Tuple[bool, List[str]]

Run the model using subprocess.Popen, optionally collecting stdout and printing timestamped progress. Model workspace, namefile, executable to use, and several other options may be configured, and additional command line arguments may also be provided.

Parameters:

• exe_name (str or PathLike) – Executable name or path. If the executable name is provided, the executable must be on the system path. Alternatively, a full path to the executable may be provided.

• namefile (str, optional) – Name of the name file of model to run. The name may be None to run models that don’t require a control file (name file)

• model_ws (str or PathLike, optional, default '.') – Path to the parent directory of the namefile. (default is the current working directory ‘.’)

• silent (boolean, default True) – Whether to suppress model output. (Default is True)

• pause (boolean, optional, default False) – Pause and wait for keystroke upon completion. (Default is False)

• report (boolean, optional, default False) – Save stdout lines to a list (buff) returned by the method. (Default is False)

• processors (int) – Number of processors. Parallel simulations are only supported for MODFLOW 6 simulations. (default is None)

• normal_msg (str or list) – Termination message used to determine if the model terminated normally. More than one message can be provided using a list. (Default is ‘normal termination’)

• use_async (boolean) – Asynchronously read model stdout and report with timestamps. Good for models taking a long time to run, not good for models that run quickly.

• cargs (str or list, optional, default None) – Additional command line arguments to pass to the executable. (Default is None)

• custom_print (callable) – Optional callable for printing. It will replace the builtin print function. This is useful for a shorter print output or integration into other systems such as GUIs. default is None, i.e. use the builtin print

Returns:

• success (boolean)

• buff (list of lines of stdout (empty if report is False))