API Reference

High-level map of the permeabledt public API. Detailed pages for each module are linked throughout.

Core Water Flow – Simulation entry points and utilities.
Calibration – Genetic-algorithm calibration helpers.
Particle Filtering – pypfilt model and observation adapters.
Weather Data – HRRR accumulated-precipitation tools.
Plotting – Optional matplotlib helpers.

Quick reference

Core water-flow helpers (`permeabledt` top-level)

Function	Description
`run_simulation(params, rainfall_file, *, inflow=None, evapotranspiration=None, rainfall_unit='mm', verbose=True, plot_outflow=False, output_path=None)`	Read a rainfall `.dat` file, simulate the event, and return pandas outputs.
`run_model(params, rainfall_file, inflow=None, evapotranspiration=None, rainfall_unit='mm')`	Lower-level driver that returns raw lists for each series.
`run_from_files(pavement, event, input_folder='input_files', calibrated_parameters=None, verbose=True)`	Legacy wrapper compatible with the historical folder layout.
`read_setup_file(path)`	Load an INI file with `configparser`.
`initialize_parameters(setup)`	Build the parameter dictionary expected by the solver.
`modify_parameters(parameters, calibrated_params)`	Apply calibration overrides to a parameter dictionary.
`results_dataframe(results)`	Convert the dictionary from `run_model` into a `DataFrame`.
`calculate_water_balance(data, dt)`	Summarise volumes and peaks from a simulation.

Calibration (`permeabledt` top-level)

Function	Description
`run_calibration(calibration_rainfall, calibration_observed_data, setup_file, ...)`	Run the DEAP-based GA using parallel rainfall/observation file lists.
`calibrate(args, *kwargs)`	Thin wrapper around the legacy `calibration.main`.

Particle filtering (`permeabledt.particle_filter`)

Class	Description
`PavementModel`	`pypfilt.Model` subclass that steps the pavement states.
`PipeObs`	Observation model that provides a normal likelihood for pipe flow.

Weather data (`permeabledt.download_HRRR_historical_forecast`)

Class	Description
`HRRRAccumulatedPrecipitationDownloader`	Download, save, and compare HRRR accumulated precipitation.

Plotting (`permeabledt.plots` – optional)

Function	Description
`plot_rainfall_hydrograph(...)`	Plot rainfall bars and simulated outflow.
`plot_event_comparison(...)`	Compare modeled vs observed outflow for multiple events.
`plot_calibration_summary(...)`	Summarise calibration metrics.

Typical import pattern

import permeabledt as pdt

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

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

Optional features (calibration, particle filtering, weather downloads, plotting) are imported lazily. Attempting to use them without the corresponding extras raises RuntimeError with installation guidance, e.g.:

try:
    best, calibrated_setup, logbook = pdt.run_calibration(rain_events, observed, setup_file)
except RuntimeError:
    print("Install with: pip install 'permeabledt[calib]'")

Refer to the module-specific pages linked above for full parameter tables and usage notes.