Core Water Flow API

Reference documentation for the functions exposed from permeabledt.water_flow_module.

The module simulates the three-zone permeable pavement conceptual model. Most users interact with run_simulation (for new code) or the legacy run_from_files wrapper. Lower-level utilities are available for reading input files, assembling parameter dictionaries, and post-processing results.

Simulation entry points

run_simulation(params, rainfall_file, inflow=None, evapotranspiration=None, rainfall_unit='mm', verbose=True, plot_outflow=False, output_path=None)

Execute the full water-flow model for a rainfall event stored in a .dat file. The helper reads, converts, and simulates the event, returning tidy pandas outputs.

Parameters

  • params (dict): Parameter dictionary produced by initialize_parameters (and optionally updated via modify_parameters).

  • rainfall_file (str or pathlib.Path): Path to a rainfall .dat file with mm/dd/YYYY HH:MM rain columns.

  • inflow (Sequence[float] or None): Optional external inflow series in m³/s. Defaults to zeros that match the rainfall length.

  • evapotranspiration (Sequence[float] or None): Optional maximum ET series in m/s. Defaults to zeros.

  • rainfall_unit (str): Unit stored in rainfall_file ('mm' or 'in').

  • verbose (bool): When True, prints the water balance summary and elapsed time.

  • plot_outflow (bool): When True, plots rainfall vs. outflow using plots.plot_rainfall_hydrograph.

  • output_path (str or pathlib.Path or None): Optional figure path passed to the plotting helper when plot_outflow is enabled.

Returns

  • data (pandas.DataFrame): Time-step results containing rainfall, inflow, state variables, and fluxes (see results_dataframe).

  • water_balance (pandas.DataFrame): Single-row summary returned by calculate_water_balance.

Example

import permeabledt as pdt

setup = pdt.read_setup_file("inputs/tc_pf_example.ini")
params = pdt.initialize_parameters(setup)

data, wb = pdt.run_simulation(
    params,
    "inputs/rainfall_event.dat",
    rainfall_unit="in",
    verbose=False,
)

print(wb[["Vtotal_in", "Vtotal_pipe (m3)"]])

run_model(parameters, rainfall_file, inflow=None, evapotranspiration=None, rainfall_unit='mm')

Lower-level driver that performs the time-stepping loop and returns raw lists of series. This function is primarily used internally and by particle filtering code that needs access to the full dictionary of arrays.

Returns

A dict with keys such as date, t, tQrain, tQin, tQpipe, thp, ts, etc. Use results_dataframe to convert this dictionary to a tidy pandas.DataFrame.

run_from_files(pavement, event, input_folder='input_files', calibrated_parameters=None, verbose=True)

Backwards-compatible wrapper that reproduces the original package behaviour. It loads the legacy configuration and rainfall folders, optionally applies calibrated parameters, and then calls run_simulation.

Parameters

  • pavement (str): Pavement identifier used in the legacy folder layout.

  • event (int): Event number within the legacy folders.

  • input_folder (str): Base folder that contains legacy configuration files.

  • calibrated_parameters (dict or None): Optional overrides applied via modify_parameters before running the model.

  • verbose (bool): Passed to run_simulation.

Returns

Same as run_simulation.

run_single_timestep(parameters, qin, qrain, emax, hp_prev, s_prev, hsz_prev, husz_prev, nusz_prev, nsz_prev)

Advance the model by one time step given the previous state and instantaneous forcings. Designed for the particle filter implementation where individual particles evolve independently.

Parameters

  • parameters (dict): Model parameters dictionary.

  • qin, qrain, emax (float): External inflow, rainfall, and ET forcing for the current step.

  • hp_prev, s_prev, hsz_prev, husz_prev, nusz_prev, nsz_prev (float): Previous state values.

Returns

A dictionary containing the updated state (hp, s, hsz, husz, nusz, nsz) and the diagnostic flow Qpipe for the current step.

Parameter utilities

read_setup_file(setup_file)

Read an INI configuration file using configparser.ConfigParser and return the loaded parser object.

initialize_parameters(setup)

Build the parameter dictionary expected by the simulation from a ConfigParser. The dictionary includes geometry, hydraulic properties, and time-step information.

modify_parameters(parameters, calibrated_params=None)

Update a parameters dictionary with a calibration result. When thickness values are modified, dependent totals (such as l) are recomputed before returning the new dictionary.

Data loading helpers

read_rainfall_dat_file(rainfall_file)

Parse a rainfall .dat file into a DataFrame with date (timezone-naive datetime) and rain columns.

rainfall_data_treatment(rainfall_file, surface_area, dt, rainfall_unit='mm')

Read a rainfall file and convert the totals into m³/s flow rates based on the specified surface area and time step. Returns a tuple (flow_series, dates).

load_input_files(parameters, rainfall_file, evt_file=None, inflow_file=None, rainfall_unit='in')

Legacy helper that converts rainfall to flow and optionally loads inflow and ET series from separate files. Returns (inflow, rainfall_flow, evapotranspiration) lists sized to the rainfall record.

results_dataframe(results, save=False, filename='water_flow_results.csv')

Convert the raw dictionary returned by run_model into a pandas.DataFrame. Optionally saves the CSV when save=True.

calculate_water_balance(data, dt)

Summarise a simulation by integrating inflow/outflow volumes and peak metrics. Returns a single-row pandas.DataFrame with columns such as Vtotal_in, Vtotal_pipe (m3), Qpeak_over (L/s), etc.

Additional notes

  • All time series are assumed to share the same time step defined by params['dt'].

  • Rainfall .dat files are expected to contain intensities per time step; the helpers take care of converting them to flows using the pavement area.

  • Plotting functionality is optional; import errors will occur if matplotlib is not installed when plot_outflow=True.