Surrogate Model Contract
Purpose
This page is the short source-of-truth contract for FEMIC P114.7 surrogate models. It defines the design, dataset, model families, applicability domain, validation metrics, persistence, and refusal rules.
Quick Contract
Design schema:
femic.hydrology.surrogate_design.v1.Model schema:
femic.hydrology.surrogate_model.v1.Families:
linearandgp.Design: Latin hypercube over continuous factors.
Validation: held-out or k-fold RMSE, MAE, R2, 95% coverage, interval width.
Applicability: feature min/max envelope plus standardized-distance guard.
Default behavior: refuse out-of-domain queries.
No silent extrapolation.
Design And Dataset
A design records factors, bounds, seed, points, and a deterministic design ID. A dataset records feature order, target name, source, and samples. Every sample must contain exactly the dataset features and finite target/feature values.
The design does not choose targets. Targets come from process-model runs or a reviewed scenario library.
Surrogate Families
Linear:
standardized ridge-linear regression;
residual-sigma interval;
warning when there are too few samples for a residual estimate.
Gaussian process:
RBF kernel on standardized features;
heuristic length scale unless supplied;
predictive variance interval;
Cholesky solve with bounded jitter and a warning when jitter is required.
Applicability And Refusal
A query is inside the domain when:
every required feature is present;
every feature is within its training min/max;
the standardized distance from the training mean is within the guard.
An out-of-domain query raises HydrologySurrogateError unless the caller
explicitly sets allow_extrapolation=True. The default refusal is the
contract used by optimization.
Validation Metrics
evaluate_surrogate records:
evaluation and accepted/refused counts;
RMSE, MAE, and R2;
95% interval coverage;
mean interval width;
fold count;
warnings for refusals, no accepted samples, and low coverage.
cross_validate_surrogate applies the same metrics across deterministic
folds.
Persistence
Saved models include family, feature order, scaler, coefficients or kernel state, hyperparameters, applicability domain, and warnings. Loading rejects an unknown family or malformed JSON.
Limits
Surrogate validity is bounded by training coverage.
Validation error is not hydrologic validation.
Categorical scenarios need explicit encoding.
No public-gauge or process-model benchmark is implied by a good CV score.
P114.9 owns the final benchmark and pilot validation.