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: linear and gp.

  • 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.

Cross-References