flopy.utils.zonbud module

class ZBNetOutput(zones, time, arrays, zone_array, flux=True)

Bases: object

Class that holds zonebudget netcdf output and allows export utilities to recognize the output data type.

Parameters:

• zones (np.ndarray) – array of zone numbers

• time (np.ndarray) – array of totim

• arrays (dict) – dictionary of budget term arrays. axis 0 is totim, axis 1 is zones

• flux (bool) – boolean flag to indicate if budget data is a flux “L^3/T”(True, default) or if the data have been processed to volumetric values “L^3” (False)

class ZoneBudget(cbc_file, z, kstpkper=None, totim=None, aliases=None, verbose=False, **kwargs)

Bases: object

ZoneBudget class

Parameters:

• cbc_file (str or CellBudgetFile object) – The file name or CellBudgetFile object for which budgets will be computed.

• z (ndarray) – The array containing to zones to be used.

• kstpkper (tuple of ints) – A tuple containing the time step and stress period (kstp, kper). The kstp and kper values are zero based.

• totim (float) – The simulation time.

• aliases (dict) – A dictionary with key, value pairs of zones and aliases. Replaces the corresponding record and field names with the aliases provided. When using this option in conjunction with a list of zones, the zone(s) passed may either be all strings (aliases), all integers, or mixed.

Return type:

None

Examples

>>> from flopy.utils.zonbud import ZoneBudget
>>> zon = ZoneBudget.read_zone_file('zone_input_file')
>>> zb = ZoneBudget('zonebudtest.cbc', zon, kstpkper=(0, 0))
>>> zb.to_csv('zonebudtest.csv')
>>> zb_mgd = zb * 7.48052 / 1000000

copy()

Return a deepcopy of the object.

export(f, ml, **kwargs)

Method to export a netcdf file, or add zonebudget output to an open netcdf file instance

Parameters:

• f (str or flopy.export.netcdf.NetCdf object) –

• ml (flopy.modflow.Modflow or flopy.mf6.ModflowGwf object) –

• **kwargs –

  logger : flopy.export.netcdf.Logger instance masked_vals : list

  list of values to mask

Return type:

flopy.export.netcdf.NetCdf object

get_budget(names=None, zones=None, net=False, pivot=False)

Get a list of zonebudget record arrays.

Parameters:

• names (list of strings) – A list of strings containing the names of the records desired.

• zones (list of ints or strings) – A list of integer zone numbers or zone names desired.

• net (boolean) – If True, returns net IN-OUT for each record.

• pivot (boolean) – If True, returns data in a more user friendly format

Returns:

budget_list – A list of the zonebudget record arrays.

Return type:

list of record arrays

Examples

>>> names = ['FROM_CONSTANT_HEAD', 'RIVER_LEAKAGE_OUT']
>>> zones = ['ZONE_1', 'ZONE_2']
>>> zb = ZoneBudget('zonebudtest.cbc', zon, kstpkper=(0, 0))
>>> bud = zb.get_budget(names=names, zones=zones)

get_dataframes(start_datetime=None, timeunit='D', index_key='totim', names=None, zones=None, net=False, pivot=False)

Get pandas dataframes.

Parameters:

• start_datetime (str) – Datetime string indicating the time at which the simulation starts.

• timeunit (str) – String that indicates the time units used in the model.

• index_key (str) – Indicates the fields to be used (in addition to “record”) in the resulting DataFrame multi-index.

• names (list of strings) – A list of strings containing the names of the records desired.

• zones (list of ints or strings) – A list of integer zone numbers or zone names desired.

• net (boolean) – If True, returns net IN-OUT for each record.

• pivot (bool) – If True, returns dataframe in a more user friendly format

Returns:

df – Pandas DataFrame with the budget information.

Return type:

Pandas DataFrame

Examples

>>> from flopy.utils.zonbud import ZoneBudget
>>> zon = ZoneBudget.read_zone_file('zone_input_file')
>>> zb = ZoneBudget('zonebudtest.cbc', zon, kstpkper=(0, 0))
>>> df = zb.get_dataframes()

get_model_shape()

Get model shape

Returns:

• nlay (int) – Number of layers

• nrow (int) – Number of rows

• ncol (int) – Number of columns

get_record_names(stripped=False)

Get a list of water budget record names in the file.

Returns:

out – List of unique text names in the binary file.

Return type:

list of strings

Examples

>>> zb = ZoneBudget('zonebudtest.cbc', zon, kstpkper=(0, 0))
>>> recnames = zb.get_record_names()

get_volumetric_budget(modeltime, recarray=None, extrapolate_kper=False)

Method to generate a volumetric budget table based on flux information

Parameters:

• modeltime (flopy.discretization.ModelTime object) – ModelTime object for calculating volumes

• recarray (np.recarray) – optional, user can pass in a numpy recarray to calculate volumetric budget. recarray must be pivoted before passing to get_volumetric_budget

• extrapolate_kper (bool) –

  flag to determine if we fill in data gaps with other timestep information from the same stress period. if True, we assume that flux is constant throughout a stress period and the pandas dataframe returned contains a volumetric budget per stress period

  if False, calculates volumes from available flux data

Return type:

pd.DataFrame

classmethod read_output(fname, net=False, dataframe=False, **kwargs)

Method to read a zonebudget output file into a recarray or pandas dataframe

Parameters:

• fname (str) – zonebudget output file name

• net (bool) – boolean flag for net budget

• dataframe (bool) – boolean flag to return a pandas dataframe

• **kwargs –

  pivot : bool

  start_datetimestr

  Datetime string indicating the time at which the simulation starts. Can be used when pandas dataframe is requested

  timeunitstr

  String that indicates the time units used in the model.

Return type:

np.recarray

classmethod read_zone_file(fname)

Method to read a zonebudget zone file into memory

Parameters:

fname (str) – zone file name

Returns:

zones

Return type:

np.array

to_csv(fname)

Saves the budget record arrays to a formatted comma-separated values file.

Parameters:

fname (str) – The name of the output comma-separated values file.

Return type:

None

classmethod write_zone_file(fname, array, fmtin=None, iprn=None)

Saves a numpy array in a format readable by the zonebudget program executable.

File format: line 1: nlay, nrow, ncol line 2: INTERNAL (format) line 3: begin data . . .

example from NACP: 19 250 500 INTERNAL (10I7) 199 199 199 199 199 199 199 199 199 199 199 199 199 199 199 199 199 199 … INTERNAL (10I7) 199 199 199 199 199 199 199 199 199 199 199 199 199 199 199 199 199 199 …

Parameters:

• array (array) – The array of zones to be written.

• fname (str) – The path and name of the file to be written.

• fmtin (int) – The number of values to write to each line.

• iprn (int) – Padding space to add between each value.

class ZoneBudget6(name='zonebud', model_ws='.', exe_name='zbud6', extension='.zbnam')

Bases: object

Model class for building, editing and running MODFLOW 6 zonebuget

Parameters:

• name (str) – model name for zonebudget

• model_ws (str) – path to model

• exe_name (str) – executable name

• extension (str) – name file extension

add_package(pkg_name, pkg)

Method to add a package to the ZoneBudget6 object

Parameters:

• pkg_name (str) – three letter package abbreviation

• pkg (str or object) – either a package file name or package object

change_model_name(name)

Method to change the model name for writing a zonebudget model.

Parameters:

name (str) – new model name

change_model_ws(model_ws)

Method to change the model ws for writing a zonebudget model.

Parameters:

model_ws (str) – new model directory

export(f, ml, **kwargs)

Method to export a netcdf file, or add zonebudget output to an open netcdf file instance

Parameters:

• f (str, PathLike, or flopy.export.netcdf.NetCdf object) – The file to export to

• ml (flopy.modflow.Modflow or flopy.mf6.ModflowGwf object) –

• **kwargs –

  logger : flopy.export.netcdf.Logger instance masked_vals : list

  list of values to mask

Return type:

flopy.export.netcdf.NetCdf object

get_budget(f=None, names=None, zones=None, net=False, pivot=False)

Method to read and get zonebudget output

Parameters:

• f (str) – zonebudget output file name

• names (list of strings) – A list of strings containing the names of the records desired.

• zones (list of ints or strings) – A list of integer zone numbers or zone names desired.

• net (boolean) – If True, returns net IN-OUT for each record.

• pivot (bool) – Method to pivot recordarray into a more user friendly method for working with data

Return type:

np.recarray

get_dataframes(start_datetime=None, timeunit='D', index_key='totim', names=None, zones=None, net=False, pivot=False)

Get pandas dataframes.

Parameters:

• start_datetime (str) – Datetime string indicating the time at which the simulation starts.

• timeunit (str) – String that indicates the time units used in the model.

• index_key (str) – Indicates the fields to be used (in addition to “record”) in the resulting DataFrame multi-index.

• names (list of strings) – A list of strings containing the names of the records desired.

• zones (list of ints or strings) – A list of integer zone numbers or zone names desired.

• net (boolean) – If True, returns net IN-OUT for each record.

• pivot (bool) – If True, returns data in a more user friendly fashion

Returns:

df – Pandas DataFrame with the budget information.

Return type:

Pandas DataFrame

Examples

>>> from flopy.utils.zonbud import ZoneBudget6
>>> zb6 = ZoneBudget6.load("my_nam_file", model_ws="my_model_ws")
>>> zb6.run_model()
>>> df = zb6.get_dataframes()

get_volumetric_budget(modeltime, recarray=None, extrapolate_kper=False)

Method to generate a volumetric budget table based on flux information

Parameters:

• modeltime (flopy.discretization.ModelTime object) – ModelTime object for calculating volumes

• recarray (np.recarray) – optional, user can pass in a numpy recarray to calculate volumetric budget. recarray must be pivoted before passing to get_volumetric_budget

• extrapolate_kper (bool) –

  flag to determine if we fill in data gaps with other timestep information from the same stress period. if True, we assume that flux is constant throughout a stress period and the pandas dataframe returned contains a volumetric budget per stress period

  if False, calculates volumes from available flux data

Return type:

pd.DataFrame

static load(nam_file, model_ws: str | PathLike = '.')

Method to load a zonebudget model from namefile

Parameters:

• nam_file (str) – zonebudget name file

• model_ws (str or PathLike, default ".") – model workspace path

Return type:

ZoneBudget6 object

run_model(exe_name=None, nam_file=None, silent=False)

Method to run a zonebudget model

Parameters:

• exe_name (str) – optional zonebudget executable name

• nam_file (str) – optional zonebudget name file name

• silent (bool) – optional flag to silence output

Return type:

tuple

write_input(line_length=20)

Method to write a ZoneBudget 6 model to file

Parameters:

line_length (int) – length of line for izone array

class ZoneFile6(model, izone, extension='.zon', aliases=None)

Bases: object

Class to build, read, write and edit MODFLOW 6 zonebudget zone files

Parameters:

• model (ZoneBudget6 object) – model object

• izone (np.array) – numpy array of zone numbers

• extension (str) – zone file extension name, defaults to “.zon”

• aliases (dict) – optional dictionary of zone aliases. ex. {1 : “nw_model”}

static load(f: str | PathLike, model)

Method to load a Zone file for zonebudget 6.

Parameter

fstr or PathLike

zone file path

modelZoneBudget6 object

zonebudget 6 model object

rtype:

ZoneFile6 object

property ncells

Method to get number of model cells

write_input(f=None, line_length=20)

Method to write the zonebudget 6 file

Parameters:

• f (str) – zone file name

• line_length (int) – maximum length of line to write in izone array

dataframe_to_netcdf_fmt(df, zone_array, flux=True)

Method to transform a volumetric zonebudget dataframe into array format for netcdf.

time is on axis 0 zone is on axis 1

Parameters:

• df (pd.DataFrame) –

• zone_array (np.ndarray) – zonebudget zones array

• flux (bool) – boolean flag to indicate if budget data is a flux “L^3/T” (True, default) or if the data have been processed to volumetric values “L^3” (False)

Return type:

ZBNetOutput object

sort_tuple(tup, n=2)

Sort a tuple by the first n values

tup: tuple

input tuple

nint

values to sort tuple by (default is 2)

Returns:

tup – tuple sorted by the first n values

Return type:

tuple

sum_flux_tuples(fromzones, tozones, fluxes)