femic.hydrology.surrogate Module

The femic.hydrology.surrogate module owns P114.7 surrogate work. It builds Latin-hypercube designs, trains ridge-linear and RBF Gaussian-process surrogates, validates them on held-out or k-fold data, and refuses queries outside a validated applicability domain.

Use this page when you are turning process-model scenarios into a fast, bounded response surrogate for optimization.

Start Here If…

Use this page first if you are trying to:

  • design process-model scenarios over harvest/road/climate factors;

  • train a linear or Gaussian-process surrogate;

  • validate error and interval coverage on held-out scenarios;

  • save/load a surrogate model; or

  • understand when a surrogate query must be refused.

Typical Usage

from pathlib import Path
from femic.hydrology.surrogate import (
    DesignFactor,
    attach_targets,
    build_latin_hypercube_design,
    cross_validate_surrogate,
    fit_surrogate,
    save_surrogate,
)

design = build_latin_hypercube_design(
    (
        DesignFactor("harvest_fraction", 0.0, 0.6),
        DesignFactor("road_density", 0.0, 2.0),
    ),
    n_samples=200,
    seed=42,
)
dataset = attach_targets(design, targets)
model = fit_surrogate(dataset, family="gp")
report = cross_validate_surrogate(dataset, family="gp", folds=5)
save_surrogate(model, Path("models/hydrology/peak_ratio_gp.json"))

Key Entry Surfaces

  • build_latin_hypercube_design()

  • attach_targets()

  • train_validation_split() Build and split surrogate datasets.

  • fit_surrogate() Fit a linear or Gaussian-process surrogate.

  • evaluate_surrogate() Validate on held-out samples with applicability refusal.

  • cross_validate_surrogate() Run deterministic k-fold validation.

  • save_surrogate()

  • load_surrogate() Persist and load model state.

  • ApplicabilityDomain Bounded envelope and distance guard.

  • SurrogateValidation Error, coverage, refusal, and fold metrics.

Cross-References

Surrogate models for fast hydrologic response queries.

P114.7 provides a design-of-experiments surface, two dependency-free surrogate families (ridge linear and RBF Gaussian process), held-out validation, and an explicit applicability domain that refuses extrapolation.

class femic.hydrology.surrogate.ApplicabilityDomain(feature_names, min_values, max_values, mean_values, scale_values, max_distance)[source]

Bases: object

Bounded feature envelope plus standardized-distance guard.

Parameters:
  • feature_names (tuple[str, ...])

  • min_values (dict[str, float])

  • max_values (dict[str, float])

  • mean_values (dict[str, float])

  • scale_values (dict[str, float])

  • max_distance (float)

check(features)[source]

Check whether one feature vector is inside the domain.

Parameters:

features (Mapping[str, float])

Return type:

ApplicabilityResult

feature_names: tuple[str, ...]
classmethod from_dict(payload)[source]

Load an applicability domain from a mapping.

Parameters:

payload (Mapping[str, object])

Return type:

ApplicabilityDomain

max_distance: float
max_values: dict[str, float]
mean_values: dict[str, float]
min_values: dict[str, float]
scale_values: dict[str, float]
to_dict()[source]

Return the domain as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.surrogate.ApplicabilityResult(inside, missing_features=(), outside_features=(), distance=None, reasons=())[source]

Bases: object

Whether a query lies inside a surrogate’s validated domain.

Parameters:
  • inside (bool)

  • missing_features (tuple[str, ...])

  • outside_features (tuple[str, ...])

  • distance (float | None)

  • reasons (tuple[str, ...])

distance: float | None = None
inside: bool
missing_features: tuple[str, ...] = ()
outside_features: tuple[str, ...] = ()
reasons: tuple[str, ...] = ()
to_dict()[source]

Return the result as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.surrogate.DesignFactor(name, low, high)[source]

Bases: object

One continuous factor in a surrogate design.

Parameters:
  • name (str)

  • low (float)

  • high (float)

high: float
low: float
name: str
to_dict()[source]

Return the factor as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.surrogate.DesignPoint(features)[source]

Bases: object

One feature vector from a surrogate design.

Parameters:

features (dict[str, float])

features: dict[str, float]
to_dict()[source]

Return the point as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.surrogate.GaussianProcessSurrogate(feature_names, mean_values, scale_values, train_standardized, alpha, kernel_inverse, y_mean, y_scale, length_scale, noise, applicability_domain, warnings=(), family='gp')[source]

Bases: object

RBF-kernel Gaussian-process surrogate.

Parameters:
  • feature_names (tuple[str, ...])

  • mean_values (dict[str, float])

  • scale_values (dict[str, float])

  • train_standardized (tuple[tuple[float, ...], ...])

  • alpha (tuple[float, ...])

  • kernel_inverse (tuple[tuple[float, ...], ...])

  • y_mean (float)

  • y_scale (float)

  • length_scale (float)

  • noise (float)

  • applicability_domain (ApplicabilityDomain)

  • warnings (tuple[str, ...])

  • family (str)

alpha: tuple[float, ...]
applicability_domain: ApplicabilityDomain
family: str = 'gp'
feature_names: tuple[str, ...]
classmethod from_dict(payload)[source]

Load a Gaussian-process surrogate from a mapping.

Parameters:

payload (Mapping[str, object])

Return type:

GaussianProcessSurrogate

kernel_inverse: tuple[tuple[float, ...], ...]
length_scale: float
mean_values: dict[str, float]
noise: float
predict(features, *, allow_extrapolation=False)[source]

Predict one target value.

Parameters:
  • features (Mapping[str, float])

  • allow_extrapolation (bool)

Return type:

float

predict_interval(features, *, allow_extrapolation=False)[source]

Predict one target interval.

Parameters:
  • features (Mapping[str, float])

  • allow_extrapolation (bool)

Return type:

tuple[float, float]

scale_values: dict[str, float]
to_dict()[source]

Return the model as a JSON-serializable mapping.

Return type:

dict[str, object]

train_standardized: tuple[tuple[float, ...], ...]
warnings: tuple[str, ...] = ()
y_mean: float
y_scale: float
exception femic.hydrology.surrogate.HydrologySurrogateError[source]

Bases: RuntimeError

Raised when a surrogate design, model, or query is invalid.

class femic.hydrology.surrogate.LinearSurrogate(feature_names, mean_values, scale_values, coefficients, residual_sigma, applicability_domain, warnings=(), family='linear')[source]

Bases: object

Standardized ridge-linear surrogate.

Parameters:
  • feature_names (tuple[str, ...])

  • mean_values (dict[str, float])

  • scale_values (dict[str, float])

  • coefficients (tuple[float, ...])

  • residual_sigma (float)

  • applicability_domain (ApplicabilityDomain)

  • warnings (tuple[str, ...])

  • family (str)

applicability_domain: ApplicabilityDomain
coefficients: tuple[float, ...]
family: str = 'linear'
feature_names: tuple[str, ...]
classmethod from_dict(payload)[source]

Load a linear surrogate from a mapping.

Parameters:

payload (Mapping[str, object])

Return type:

LinearSurrogate

mean_values: dict[str, float]
predict(features, *, allow_extrapolation=False)[source]

Predict one target value.

Parameters:
  • features (Mapping[str, float])

  • allow_extrapolation (bool)

Return type:

float

predict_interval(features, *, allow_extrapolation=False)[source]

Predict one target interval.

Parameters:
  • features (Mapping[str, float])

  • allow_extrapolation (bool)

Return type:

tuple[float, float]

residual_sigma: float
scale_values: dict[str, float]
to_dict()[source]

Return the model as a JSON-serializable mapping.

Return type:

dict[str, object]

warnings: tuple[str, ...] = ()
class femic.hydrology.surrogate.SurrogateDataset(feature_names, target_name, samples, source='', schema_version='femic.hydrology.surrogate_dataset.v1')[source]

Bases: object

A validated surrogate training or validation dataset.

Parameters:
  • feature_names (tuple[str, ...])

  • target_name (str)

  • samples (tuple[SurrogateSample, ...])

  • source (str)

  • schema_version (str)

feature_names: tuple[str, ...]
samples: tuple[SurrogateSample, ...]
schema_version: str = 'femic.hydrology.surrogate_dataset.v1'
source: str = ''
target_name: str
to_dict()[source]

Return the dataset as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.surrogate.SurrogateDesign(design_id, generated_utc, factors, points, seed, schema_version='femic.hydrology.surrogate_design.v1')[source]

Bases: object

Latin-hypercube design over continuous hydrologic factors.

Parameters:
  • design_id (str)

  • generated_utc (str)

  • factors (tuple[DesignFactor, ...])

  • points (tuple[DesignPoint, ...])

  • seed (int)

  • schema_version (str)

design_id: str
factors: tuple[DesignFactor, ...]
generated_utc: str
points: tuple[DesignPoint, ...]
schema_version: str = 'femic.hydrology.surrogate_design.v1'
seed: int
to_dict()[source]

Return the design as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.surrogate.SurrogateModel(*args, **kwargs)[source]

Bases: Protocol

Protocol for a validated surrogate model.

property applicability_domain: ApplicabilityDomain

Return the validated applicability domain.

property family: str

Return the surrogate family name.

property feature_names: tuple[str, ...]

Return the model feature order.

predict(features, *, allow_extrapolation=False)[source]

Predict one target value.

Parameters:
  • features (Mapping[str, float])

  • allow_extrapolation (bool)

Return type:

float

predict_interval(features, *, allow_extrapolation=False)[source]

Predict an interval for one target value.

Parameters:
  • features (Mapping[str, float])

  • allow_extrapolation (bool)

Return type:

tuple[float, float]

to_dict()[source]

Serialize the model.

Return type:

dict[str, object]

property warnings: tuple[str, ...]

Return model warnings.

class femic.hydrology.surrogate.SurrogateSample(features, target)[source]

Bases: object

One feature/target training or validation sample.

Parameters:
  • features (dict[str, float])

  • target (float)

features: dict[str, float]
target: float
to_dict()[source]

Return the sample as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.surrogate.SurrogateValidation(model_family, evaluation_size, accepted_count, refused_count, rmse, mae, r2, coverage_95, mean_interval_width, fold_count, is_valid, warnings=())[source]

Bases: object

Validation metrics for a surrogate against held-out targets.

Parameters:
  • model_family (str)

  • evaluation_size (int)

  • accepted_count (int)

  • refused_count (int)

  • rmse (float | None)

  • mae (float | None)

  • r2 (float | None)

  • coverage_95 (float | None)

  • mean_interval_width (float | None)

  • fold_count (int)

  • is_valid (bool)

  • warnings (tuple[str, ...])

accepted_count: int
coverage_95: float | None
evaluation_size: int
fold_count: int
is_valid: bool
mae: float | None
mean_interval_width: float | None
model_family: str
r2: float | None
refused_count: int
rmse: float | None
to_dict()[source]

Return the validation as a JSON-serializable mapping.

Return type:

dict[str, object]

warnings: tuple[str, ...] = ()
femic.hydrology.surrogate.attach_targets(design, targets, *, target_name='peak_flow_ratio', source='')[source]

Attach process-model targets to a design.

Parameters:
  • design (SurrogateDesign)

  • targets (Sequence[float])

  • target_name (str)

  • source (str)

Return type:

SurrogateDataset

femic.hydrology.surrogate.build_latin_hypercube_design(factors, *, n_samples, seed=0, generated_utc=None)[source]

Build a Latin-hypercube design over continuous factors.

Parameters:
  • factors (Sequence[DesignFactor])

  • n_samples (int)

  • seed (int)

  • generated_utc (str | None)

Return type:

SurrogateDesign

femic.hydrology.surrogate.cross_validate_surrogate(dataset, *, family='linear', folds=5, seed=0, ridge=1e-06, length_scale=None, noise=1e-06)[source]

Run deterministic k-fold cross-validation for one surrogate family.

Parameters:
  • dataset (SurrogateDataset)

  • family (str)

  • folds (int)

  • seed (int)

  • ridge (float)

  • length_scale (float | None)

  • noise (float)

Return type:

SurrogateValidation

femic.hydrology.surrogate.evaluate_surrogate(model, dataset, *, refuse_out_of_domain=True)[source]

Evaluate a surrogate against held-out samples.

Parameters:
Return type:

SurrogateValidation

femic.hydrology.surrogate.fit_surrogate(dataset, *, family='linear', ridge=1e-06, length_scale=None, noise=1e-06)[source]

Fit one of the dependency-free surrogate families.

Parameters:
  • dataset (SurrogateDataset)

  • family (str)

  • ridge (float)

  • length_scale (float | None)

  • noise (float)

Return type:

SurrogateModel

femic.hydrology.surrogate.load_surrogate(path)[source]

Load a surrogate model from JSON.

Parameters:

path (Path)

Return type:

SurrogateModel

femic.hydrology.surrogate.save_surrogate(model, path)[source]

Save a surrogate model as JSON.

Parameters:
Return type:

Path

femic.hydrology.surrogate.train_validation_split(dataset, *, validation_fraction=0.2, seed=0)[source]

Split a dataset into deterministic train/validation subsets.

Parameters:
Return type:

tuple[SurrogateDataset, SurrogateDataset]