flopy.mf6.mfsimbase module

class MFSimulationBase(sim_name='sim', version='mf6', exe_name: str | PathLike = 'mf6', sim_ws: str | PathLike = '.', verbosity_level=1, continue_=None, nocheck=None, memory_print_option=None, write_headers=True, lazy_io=False, use_pandas=True)[source]

Bases: PackageContainer

Entry point into any MODFLOW simulation.

MFSimulation is used to load, build, and/or save a MODFLOW 6 simulation. A MFSimulation object must be created before creating any of the MODFLOW 6 model objects.

Parameters:

  • sim_name (str) – Name of the simulation.

  • version (str) – Version of MODFLOW 6 executable

  • exe_name (str) – Path to MODFLOW 6 executable

  • sim_ws (str) – Path to MODFLOW 6 simulation working folder. This is the folder containing the simulation name file.

  • verbosity_level (int) – Verbosity level of standard output from 0 to 2. When 0 is specified no standard output is written. When 1 is specified standard error/warning messages with some informational messages are written. When 2 is specified full error/warning/informational messages are written (this is ideal for debugging).

  • continue (bool) – Sets the continue option in the simulation name file. The continue option is a keyword flag to indicate that the simulation should continue even if one or more solutions do not converge.

  • nocheck (bool) – Sets the nocheck option in the simulation name file. The nocheck option is a keyword flag to indicate that the model input check routines should not be called prior to each time step. Checks are performed by default.

  • memory_print_option (str) – Sets memory_print_option in the simulation name file. Memory_print_option is a flag that controls printing of detailed memory manager usage to the end of the simulation list file. NONE means do not print detailed information. SUMMARY means print only the total memory for each simulation component. ALL means print information for each variable stored in the memory manager. NONE is default if memory_print_option is not specified.

  • write_headers (bool) – When true flopy writes a header to each package file indicating that it was created by flopy.

  • lazy_io (bool) – When true flopy only reads external data when the data is requested and only writes external data if the data has changed. This option automatically overrides the verify_data and auto_set_sizes, turning both off.

  • use_pandas (bool) – Load/save data using pandas dataframes (for supported data)

Examples

>>> s = MFSimulationBase.load('my simulation', 'simulation.nam')
sim_name

Name of the simulation

Type:

str

name_file

Simulation name file package

Type:

MFPackage

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

Check model data for common errors.

Parameters:

  • f (str or PathLike, optional) – String defining file name or file handle for summary file of check method output. If str or pathlike, a file handle is created. If None, the 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.

Returns:

check list – Python list containing simulation check results

Return type:

list

Examples

>>> import flopy
>>> m = flopy.modflow.Modflow.load('model.nam')
>>> m.check()
delete_output_files()[source]

Deletes simulation output files.

property exchange_files

Return list of exchange files associated with this simulation.

Returns:

list

Return type:

list of exchange names

get_exchange_file(filename)[source]

Get a specified exchange file.

Parameters:

filename (str) – Name of exchange file to get

Returns:

exchange package

Return type:

MFPackage

get_file(filename)[source]

Get a specified file.

Parameters:

filename (str) – Name of mover file to get

Returns:

mover package

Return type:

MFPackage

get_model(model_name=None)[source]

Returns the models in the simulation with a given model name, name file name, or model type.

Parameters:

model_name (str) – Name of the model to get. Passing in None or an empty list will get the first model.

Returns:

model

Return type:

MFModel

get_solution_package(key)[source]

Get the solution package with the specified key.

Parameters:

key (str) – solution package file name

Returns:

solution_package

Return type:

MFPackage

is_valid()[source]

Checks the validity of the solution and all of its models and packages. Returns true if the solution is valid, false if it is not.

Returns:

valid – Whether this is a valid simulation

Return type:

bool

static load(cls_child, sim_name='modflowsim', version='mf6', exe_name: str | PathLike = 'mf6', sim_ws: str | PathLike = '.', strict=True, verbosity_level=1, load_only=None, verify_data=False, write_headers=True, lazy_io=False, use_pandas=True)[source]

Load an existing model. Do not call this method directly. Should only be called by child class.

Parameters:

  • cls_child – cls object of child class calling load

  • sim_name (str) – Name of the simulation.

  • version (str) – MODFLOW version

  • exe_name (str or PathLike) – Path to MODFLOW executable (relative to the simulation workspace or absolute)

  • sim_ws (str or PathLike) – Path to simulation workspace

  • strict (bool) – Strict enforcement of file formatting

  • verbosity_level (int) –

    Verbosity level of standard output

    0: No standard output 1: Standard error/warning messages with some informational

    messages

    2: Verbose mode with full error/warning/informational

    messages. This is ideal for debugging.

  • load_only (list) – List of package abbreviations or package names corresponding to packages that flopy will load. default is None, which loads all packages. the discretization packages will load regardless of this setting. subpackages, like time series and observations, will also load regardless of this setting. example list: [‘ic’, ‘maw’, ‘npf’, ‘oc’, ‘ims’, ‘gwf6-gwf6’]

  • verify_data (bool) – Verify data when it is loaded. this can slow down loading

  • write_headers (bool) – When true flopy writes a header to each package file indicating that it was created by flopy

  • lazy_io (bool) – When true flopy only reads external data when the data is requested and only writes external data if the data has changed. This option automatically overrides the verify_data and auto_set_sizes, turning both off.

  • use_pandas (bool) – Load/save data using pandas dataframes (for supported data)

Returns:

sim

Return type:

MFSimulation object

Examples

>>> s = flopy.mf6.mfsimulation.load('my simulation')
load_package(ftype, fname: str | PathLike, pname, strict, ref_path: str | PathLike, dict_package_name=None, parent_package=None)[source]

Load a package from a file.

Parameters:

  • ftype (str) – the file type

  • fname (str or PathLike) – the path of the file containing the package input

  • pname (str) – the user-defined name for the package

  • strict (bool) – strict mode when loading the file

  • ref_path (str) – path to the file. uses local path if set to None

  • dict_package_name (str) – package name for dictionary lookup

  • parent_package (MFPackage) – parent package

property model_dict

Return a dictionary of models associated with this simulation.

Returns:

model dict – dictionary of models

Return type:

dict

property model_names

Return a list of model names associated with this simulation.

Returns:

list

Return type:

list of model names

plot(model_list: str | List[str] | None = None, SelPackList=None, **kwargs)[source]

Plot simulation or models.

Method to plot a whole simulation or a series of models that are part of a simulation.

Parameters:

  • model_list (list, optional) – List of model names to plot, if none all models will be plotted

  • SelPackList (list, optional) – List of package names to plot, if none all packages will be plotted

  • kwargs –

    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 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 – matplotlib.pyplot.axes objects

Return type:

(list)

register_exchange_file(package)[source]

Register an exchange package file with the simulation. This is a call-back method made from the package and should not be called directly.

Parameters:

package (MFPackage) – Exchange package object to register

register_ims_package(solution_file: MFPackage, model_list: str | List[str])[source]
register_model(model, model_type, model_name, model_namefile)[source]

Add a model to the simulation. This is a call-back method made from the package and should not be called directly.

Parameters:

  • model (MFModel) – Model object to add to simulation

  • sln_group (str) – Solution group of model

Returns:

model_structure_object

Return type:

MFModelStructure

register_package(package, add_to_package_list=True, set_package_name=True, set_package_filename=True)[source]

Register a package file with the simulation. This is a call-back method made from the package and should not be called directly.

Parameters:

  • package (MFPackage) – Package to register

  • add_to_package_list (bool) – Add package to lookup list

  • set_package_name (bool) – Produce a package name for this package

  • set_package_filename (bool) – Produce a filename for this package

Returns:

(path

Return type:

tuple, package structure : MFPackageStructure)

register_solution_package(solution_file: MFPackage, model_list: str | List[str])[source]

Register a solution package with the simulation.

Parameters
solution_fileMFPackage

solution package to register

model_listlist of strings

list of models using the solution package to be registered

remove_exchange_file(package)[source]

Removes the exchange file “package”. This is for internal flopy library use only.

Parameters:

package (MFPackage) – Exchange package to be removed

remove_model(model_name)[source]

Remove model with name model_name from the simulation

Parameters:

model_name (str) – Model name to remove from simulation

remove_package(package_name)[source]

Removes package from the simulation. package_name can be the package’s name, type, or package object to be removed from the model.

Parameters:

package_name (str) – Name of package to be removed

rename_all_packages(name)[source]

Rename all packages with name as prefix.

Parameters:

name (str) – Prefix of package names

rename_model_namefile(model, new_namefile)[source]

Rename a model’s namefile. For internal flopy library use only.

Parameters:

  • model (MFModel) – Model object whose namefile to rename

  • new_namefile (str) – Name of the new namefile

run_simulation(silent=None, pause=False, report=False, processors=None, normal_msg='normal termination', use_async=False, cargs=None, custom_print=None)[source]

Run the simulation.

Parameters:

  • silent (bool) – Run in silent mode

  • pause (bool) – Pause at end of run

  • report (bool) – Save stdout lines to a list (buff)

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

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

  • use_async (bool) – Asynchronously read model stdout and report with timestamps. good for models that take long time to run. not good for models that run really fast

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

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

Returns:

  • success (bool)

  • buff (list of lines of stdout)

set_all_data_external(check_data=True, external_data_folder=None, base_name=None, binary=False)[source]

Sets the simulation’s list and array data to be stored externally.

Parameters:

  • check_data (bool) – Determines if data error checking is enabled during this process. Data error checking can be slow on large datasets.

  • external_data_folder (str or PathLike) – Path relative to the simulation path or model relative path (see use_model_relative_path parameter), where external data will be stored

  • base_name (str) – Base file name prefix for all files

  • binary (bool) – Whether file will be stored as binary

set_all_data_internal(check_data=True)[source]
set_sim_path(path: str | PathLike)[source]

Return a list of output data keys.

Parameters:

path (str) – Relative or absolute path to simulation root folder.

property sim_package_list

List of all “simulation level” packages

property sim_path: Path
update_package_filename(package, new_name)[source]

Updates internal arrays to be consistent with a new file name. This is for internal flopy library use only.

Parameters:

  • package (MFPackage) – Package with new name

  • new_name (str) – Package’s new name

write_simulation(ext_file_action=ExtFileAction.copy_relative_paths, silent=False)[source]

Write the simulation to files.

Parameters
ext_file_actionExtFileAction

Defines what to do with external files when the simulation path has changed. Defaults to copy_relative_paths which copies only files with relative paths, leaving files defined by absolute paths fixed.

silentbool

Writes out the simulation in silent mode (verbosity_level = 0)

class MFSimulationData(path: str | PathLike, mfsim)[source]

Bases: object

Class containing MODFLOW simulation data and file formatting data. Use MFSimulationData to set simulation-wide settings which include data formatting and file location settings.

Parameters:

path (str) – path on disk to the simulation

indent_string

String used to define how much indent to use (file formatting)

Type:

str

internal_formatting

List defining string to use for internal formatting

Type:

list

external_formatting

List defining string to use for external formatting

Type:

list

open_close_formatting

List defining string to use for open/close

Type:

list

max_columns_of_data

Maximum columns of data before line wraps. For structured grids this is set to ncol by default. For all other grids the default is 20.

Type:

int

wrap_multidim_arrays

Whether to wrap line for multi-dimensional arrays at the end of a row/column/layer

Type:

bool

_float_precision

Number of decimal points to write for a floating point number

Type:

int

_float_characters

Number of characters a floating point number takes up

Type:

int

write_headers

When true flopy writes a header to each package file indicating that it was created by flopy

Type:

bool

sci_note_upper_thres

Numbers greater than this threshold are written in scientific notation

Type:

float

sci_note_lower_thres

Numbers less than this threshold are written in scientific notation

Type:

float

mfpath

File path location information for the simulation

Type:

MFFileMgmt

model_dimensions

Dictionary containing discretization information for each model

Type:

dict

mfdata

Custom dictionary containing all model data for the simulation

Type:

SimulationDict

property float_characters

Gets max characters used in floating point numbers.

property float_precision

Gets precision of floating point numbers.

property lazy_io
property max_columns_of_data
set_sci_note_lower_thres(value)[source]

Sets threshold number where any number smaller than threshold is represented in scientific notation.

Parameters:

value (float) – threshold value

set_sci_note_upper_thres(value)[source]

Sets threshold number where any number larger than threshold is represented in scientific notation.

Parameters:

value (float) – threshold value

class SimulationDict(path=None)[source]

Bases: dict

Class containing custom dictionary for MODFLOW simulations. Dictionary contains model data. Dictionary keys are “paths” to the data that include the model and package containing the data.

Behaves as an dict with some additional features described below.

Parameters:

path (MFFileMgmt) – Object containing path information for the simulation

find_in_path(key_path, key_leaf)[source]

Attempt to find key_leaf in a partial key path key_path.

Parameters:

  • key_path (str) – partial path to the data

  • key_leaf (str) – name of the data

Returns:

  • Data (MFData,)

  • index (int)

input_keys()[source]

Return a list of input data keys.

Returns:

input keys

Return type:

list

keys()[source]

Return a list of all keys.

Returns:

all keys

Return type:

list

observation_keys()[source]

Return a list of observation keys.

Returns:

observation keys

Return type:

list

output_keys(print_keys=True)[source]

Return a list of output data keys supported by the dictionary.

Parameters:

print_keys (bool) – print keys to console

Returns:

output keys

Return type:

list