Surrogate Models For Hydrologic Response
Purpose
P114.7 provides fast surrogate models for hydrologic response queries. The surrogate is trained on process-model scenarios or a reviewed scenario library and refuses queries outside a validated applicability domain.
It is a fast approximation, not a substitute for the process model or
hydrologist review. The design schema is
femic.hydrology.surrogate_design.v1 and the model schema is
femic.hydrology.surrogate_model.v1.
Design Of Experiments
Continuous factors are sampled with a Latin-hypercube design:
from femic.hydrology.surrogate import DesignFactor, build_latin_hypercube_design
design = build_latin_hypercube_design(
(
DesignFactor("harvest_fraction", 0.0, 0.6),
DesignFactor("road_density", 0.0, 2.0),
DesignFactor("climate_index", 0.8, 1.2),
),
n_samples=200,
seed=42,
)
Attach process-model targets with attach_targets. Categorical climate
scenarios should be encoded by a reviewed numeric covariate or handled as
separate surrogates.
Surrogate Families
Two dependency-free families are implemented:
linear: standardized ridge-linear regression with a residual interval.gp: RBF-kernel Gaussian process with a predictive variance.
Additional families can be added behind the SurrogateModel protocol.
Training And Validation
from femic.hydrology.surrogate import (
attach_targets,
cross_validate_surrogate,
evaluate_surrogate,
fit_surrogate,
train_validation_split,
)
dataset = attach_targets(design, targets, target_name="peak_flow_ratio")
train, validation = train_validation_split(dataset, validation_fraction=0.2, seed=42)
model = fit_surrogate(train, family="gp")
report = evaluate_surrogate(model, validation)
cv = cross_validate_surrogate(dataset, family="gp", folds=5, seed=42)
Validation records RMSE, MAE, R2, 95% interval coverage, mean interval width, accepted/refused counts, and fold count.
Applicability Domain And Refusal
The applicability domain combines:
a per-feature training min/max envelope;
a standardized-distance guard around the training mean.
Queries outside the domain raise by default:
model.predict({"harvest_fraction": 0.9, "road_density": 5.0})
# HydrologySurrogateError: Query is outside the applicability domain...
Use allow_extrapolation=True only for an explicitly reviewed extrapolation
test. Do not silently feed extrapolated queries into optimization.
Persistence
from femic.hydrology.surrogate import load_surrogate, save_surrogate
save_surrogate(model, Path("models/hydrology/peak_ratio_gp.json"))
loaded = load_surrogate(Path("models/hydrology/peak_ratio_gp.json"))
The saved model includes the feature order, scaler, coefficients or kernel state, hyperparameters, and applicability domain.
Limits
The surrogate is only valid inside its training coverage.
Validation error is not a hydrologic validation.
The GP length scale is heuristic unless supplied.
Categorical scenarios need explicit encoding.
Process-model calibration and benchmark validation remain P114.9.
Hydrologist review is required before operational use.
No silent extrapolation: out-of-domain queries are refused by default.