mfsetup.tdis module

Functions related to temporal discretization

mfsetup.tdis.add_date_comments_to_tdis(tdis_file, start_dates, end_dates=None)

Add stress period start and end dates to a tdis file as comments; add modflow-setup version info to tdis file header.

mfsetup.tdis.aggregate_dataframe_to_stress_period(data, id_column, data_column, datetime_column='datetime', end_datetime_column=None, category_column=None, start_datetime=None, end_datetime=None, period_stat='mean', resolve_duplicates_with='raise error')

Aggregate time-series data in a DataFrame to a single value representing a period defined by a start and end date.

Parameters:

dataDataFrame

Must have an id_column, data_column, datetime_column, and optionally, an end_datetime_column.

id_columnstr

Column in data with location identifier (e.g. node or well id).

data_columnstr or list

Column(s) in data with values to aggregate.

datetime_columnstr

Column in data with times for each value. For downsampling of multiple values in data to a longer period represented by start_datetime and end_datetime, this is all that is needed. Aggregated values will include values in datetime_column that are >= start_datetime and < end_datetime. In other words, datetime_column represents the start of each time interval in data. Values can be strings (e.g. YYYY-MM-DD) or pandas Timestamps. By default, None.

end_datetime_columnstr

Column in data with end times for period represented by each value. This is only needed for upsampling, where the interval defined by start_datetime and end_datetime is smaller than the time intervals in data. The row(s) in data that have a datetime_column value < end_datetime, and an end_datetime_column value > start_datetime will be retained in aggregated. Values can be strings (e.g. YYYY-MM-DD) or pandas Timestamps. By default, None.

start_datetimestr or pandas.Timestamp

Start time of aggregation period. Only used if an aggregation start and end time are not given in period_stat. If None, and no start and end time are specified in period_stat, the first time in datetime_column is used. By default, None.

end_datetimestr or pandas.Timestamp

End time of aggregation period. Only used if an aggregation start and end time are not given in period_stat. If None, and no start and end time are specified in period_stat, the last time in datetime_column is used. By default, None.

period_statstr, list, or NoneType

Method for aggregating data. By default, ‘mean’.

• Strings will be passed to DataFrame.groupby as the aggregation method. For example, 'mean' would result in DataFrame.groupby().mean().

• If period_stat is None, 'mean' is used.

• Lists of length 2 can be used to specify a statistic for a month (e.g. ['mean', 'august']), or for a time period that can be represented as a single string in pandas. For example, ['mean', '2014'] would average all values in the year 2014; ['mean', '2014-01'] would average all values in January of 2014, etc. Basically, if the string can be used to slice a DataFrame or Series, it can be used here.

• Lists of length 3 can be used to specify a statistic and a start and end date. For example, ['mean', '2014-01-01', '2014-03-31'] would average the values for the first three months of 2014.

resolve_duplicates_with{‘sum’, ‘mean’, ‘first’, ‘raise error’}

Method for reducing duplicates (of times, sites and measured or estimated category). By default, ‘raise error’ will result in a ValueError if duplicates are encountered. Otherwise any aggregate method in pandas can be used (e.g. DataFrame.groupby().<method>())

Returns:

aggregatedDataFrame

Aggregated values. Columns are the same as data, except the time column is named ‘start_datetime’. In other words, aggregated periods are represented by their start dates (as opposed to midpoint dates or end dates).

mfsetup.tdis.aggregate_xarray_to_stress_period(data, datetime_coords_name='time', start_datetime=None, end_datetime=None, period_stat='mean')

mfsetup.tdis.concat_periodata_groups(perioddata_groups, time_units='days')

Concatenate multiple perioddata DataFrames, but sort result on (absolute) datetimes and increment model time and stress period numbers accordingly.

mfsetup.tdis.convert_freq_to_period_start(freq)

convert pandas frequency to period start

mfsetup.tdis.get_parent_stress_periods(parent_model, nper=None, parent_stress_periods='all')

mfsetup.tdis.parse_perioddata_groups(perioddata_dict, **kwargs)

Reorganize input in perioddata dict into a list of groups (dicts).

mfsetup.tdis.setup_perioddata(model, tdis_perioddata_config, default_start_datetime=None, nper=None, steady=None, time_units='days', oc_saverecord=None, parent_model=None, parent_stress_periods=None)

Sets up the perioddata DataFrame that is used to reference model stress period start and end times to real date time.

Parameters:

model_type_

_description_

tdis_perioddata_configdict

perioddata:, tdis: (MODFLOW 6 models) or dis: (MODFLOW-2005 models) block from the Modflow-setup configuration file.

default_start_datetimestr, optional

Start date for model from the tdis: options: block in the configuration file, or model.modeltime.start_datetime Flopy attribute. Only used where start_datetime information is missing, for example if a group for an initial steady-state period in tdis_perioddata_config doesn’t have a start_datetime: entry. By default, None, in which case the default start_datetime of 1970-01-01 may be applied by py:func:setup_perioddata_group.

nperint, optional

Number of stress periods. Only used if nper is specified in the tdis: dimensions: block of the configuration file and not in a perioddata group.

steadybool, sequence or dict

Whether each period is steady-state or transient. Only used if steady is specified in the tdis: or sto: configuration file blocks (MODFLOW 6 models) or the dis: block (MODFLOW-2005 models), and not in perioddata groups.

time_unitsstr, optional

Model time units, by default ‘days’.

oc_saverecorddict, optional

Output control settings, keyed by stress period. Only used to record this information in the stress period data table.

parent_modelflopy model instance, optional

Parent model, if model is an inset.

parent_stress_periodslist of ints, optional

Parent model stress periods to apply to the inset model (read from the parent: copy_stress_periods: item in the configuration file).

Returns:

perioddataDataFrame

Table of stress period information with columns:

start_datetime	Start date of each model stress period
end_datetime	End date of each model stress period
time	MODFLOW elapsed time, in days [1]
per	Model stress period number
perlen	Stress period length (days)
nstp	Number of timesteps in stress period
tsmult	Timestep multiplier
steady	Steady-state or transient
oc	Output control setting for MODFLOW
parent_sp	Corresponding parent model stress period

Notes

perioddata is also saved to stress_period_data.csv in the tables folder (usually /tables).

Footnotes

[1]

Modflow elapsed time includes the time lengths specified for any steady-state periods (at least 1 day). Therefore if the model has an initial steady-state period with a perlen of one day, the elapsed time at the model start date will already be 1 day.

mfsetup.tdis.setup_perioddata_group(start_date_time, end_date_time=None, nper=None, perlen=None, model_time_units='days', freq=None, steady={0: True, 1: False}, nstp=10, tsmult=1.5, oc_saverecord={0: ['save head last', 'save budget last']})

Sets up time discretization for a model; outputs a DataFrame with stress period dates/times and properties. Stress periods can be established by explicitly specifying perlen as a list of period lengths in model units. Or, stress periods can be generated via pandas.date_range(), using three of the start_date_time, end_date_time, nper, and freq arguments.

Parameters:

start_date_timestr or datetime-like

Left bound for generating stress period dates. See pandas.date_range().

end_date_timestr or datetime-like, optional

Right bound for generating stress period dates. See pandas.date_range().

nperint, optional

Number of stress periods. Only used if perlen is None, or in combination with freq if an end_date_time isn’t specified.

perlensequence or None, optional

A list of stress period lengths in model time units. Or specify as None and specify 3 of start_date_time, end_date_time, nper and/or freq.

model_time_unitsstr, optional

‘days’ or ‘seconds’. By default, ‘days’.

freqstr or DateOffset, default None

For setting up uniform stress periods between a start and end date, or of length nper. Same as argument to pandas.date_range. Frequency strings can have multiples, e.g. ‘6MS’ for a 6 month interval on the start of each month. See the pandas documentation for a list of frequency aliases. Note: Only “start” frequences (e.g. MS vs M for “month end”) are supported.

steadydict

Dictionary with zero-based stress periods as keys and boolean values. Similar to MODFLOW-6 input, the information specified for a period will continue to apply until information for another period is specified.

nstpint or sequence

Number of timesteps in a stress period. Must be an integer if perlen=None.

nstpint or sequence

Timestep multiplier for a stress period. Must be an integer if perlen=None.

oc_saverecorddict

Dictionary with zero-based stress periods as keys and output control options as values. Similar to MODFLOW-6 input, the information specified for a period will continue to apply until information for another period is specified.

Returns:

perioddatapandas.DataFrame

DataFrame summarizing stress period information. Data columns:

start_datetime	pandas datetimes	start date/time of each stress period
end_datetime	pandas datetimes	end date/time of each stress period
time	float	cumulative MODFLOW time at end of period
per	int	zero-based stress period
perlen	float	stress period length in model time units
nstp	int	number of timesteps in the stress period
tsmult	int	timestep multiplier for stress period
steady	bool	True=steady-state, False=Transient
oc	dict	MODFLOW-6 output control options

Notes

Initial steady-state period

If the first stress period is specified as steady-state (steady[0] == True), the period length (perlen) in MODFLOW time is automatically set to 1. If subsequent stress periods are specified, or if no end-date is specified, the end date for the initial steady-state stress period is set equal to the start date. In the latter case, the assumption is that the specified start date represents the start of the transient simulation, and the initial steady-state (which is time-invarient anyways) is intended to produce a valid starting condition. If only a single steady-state stress period is specified with an end date, then that end date is retained.

MODFLOW time vs real time

The time column of the output DataFrame represents time in the MODFLOW simulation, which cannot have zero-lengths for any period. Therefore, initial steady-state periods are automatically assigned lengths of one (as described above), and MODFLOW time is incremented accordingly. If the model has an initial steady-state period, this means that subsequent MODFLOW times will be 1 time unit greater than the acutal date-times.

End-dates

Specified end_date_time represents the right bound of the time discretization, or in other words, the time increment after the last time increment to be simulated. For example, end_date_time='2019-01-01' would mean that '2018-12-31' is the last date simulated by the model (which ends at 2019-01-01 00:00:00).