Calibration API

Reference for the genetic-algorithm calibration utilities in permeabledt.calibration.

The public interface consists of the modern run_calibration function plus the legacy calibrate wrapper kept for backward compatibility. Both require the optional calibration dependencies (pip install "permeabledt[calib]").

run_calibration(calibration_rainfall, calibration_observed_data, setup_file, output_setup_file=None, logbook_output_path=None, seed=None)

Run the DEAP-based single-objective genetic algorithm across one or more calibration events.

Arguments

  • calibration_rainfall (list[str | Path]): Paths to rainfall .dat files. Each entry must align with the observed outflow file at the same index.

  • calibration_observed_data (list[str | Path]): Paths to observed outflow CSV files. Each file must contain the modeled discharge column as the second column (converted internally from ft³/s to L/s).

  • setup_file (str | Path): INI file containing calibration parameter bounds under the [CALIBRATION_PARAMETERS] section and genetic algorithm settings in [CALIBRATION].

  • output_setup_file (str | Path, optional): When provided, the calibrated setup is written back to disk using these parameter values.

  • logbook_output_path (str | Path, optional): When set, a CSV export of the DEAP logbook (generation statistics and hall-of-fame individual) is written to this path.

  • seed (int, optional): Random seed applied to both Python’s random module and NumPy for reproducible runs.

Behaviour

  • All rainfall/observed files must be supplied as lists of equal length. An empty list raises a ValueError.

  • Calibration parameter names and bounds are parsed from setup_file. GA options such as population size, number of generations, crossover probability, and mutation probability are also read from the INI.

  • Fitness evaluation delegates to the evaluate helper, which runs the water flow model for each event and compares modeled vs observed outflow.

Returns

  • best_individual (list[float]): Parameter values from the hall-of-fame individual.

  • calibrated_setup (configparser.ConfigParser): The modified configuration object with calibrated values inserted.

  • logbook (deap.tools.Logbook): Evolutionary history, including generation statistics and the hall-of-fame individual per iteration.

Example

import permeabledt as pdt

rain_events = ["data/event1_rain.dat", "data/event2_rain.dat"]
observed    = ["data/event1_obs.csv", "data/event2_obs.csv"]
setup_file  = "configs/tc_pf_site.ini"

best, calibrated_setup, logbook = pdt.run_calibration(
    rain_events,
    observed,
    setup_file,
    output_setup_file="outputs/calibrated.ini",
    logbook_output_path="outputs/logbook.csv",
    seed=123,
)

print("Best candidate:", best)
print("Generations recorded:", len(logbook))

calibrate(*args, **kwargs)

Convenience wrapper that forwards all arguments to the legacy permeabledt.calibration.main routine. It is preserved for existing scripts that rely on the historical folder layout and command-line behaviour.

Notes

  • Raises RuntimeError if the optional calibration dependencies are missing.

  • Returns whatever calibration.main returns (typically None). For new code prefer run_calibration, which surfaces the best individual, calibrated setup, and DEAP logbook directly.