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.ApplicabilityDomainBounded envelope and distance guard.SurrogateValidationError, 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:
objectBounded 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:
- feature_names: tuple[str, ...]
- classmethod from_dict(payload)[source]
Load an applicability domain from a mapping.
- Parameters:
payload (Mapping[str, object])
- Return type:
- max_distance: float
- max_values: dict[str, float]
- mean_values: dict[str, float]
- min_values: dict[str, float]
- scale_values: dict[str, float]
- class femic.hydrology.surrogate.ApplicabilityResult(inside, missing_features=(), outside_features=(), distance=None, reasons=())[source]
Bases:
objectWhether 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, ...] = ()
- class femic.hydrology.surrogate.DesignFactor(name, low, high)[source]
Bases:
objectOne continuous factor in a surrogate design.
- Parameters:
name (str)
low (float)
high (float)
- high: float
- low: float
- name: str
- class femic.hydrology.surrogate.DesignPoint(features)[source]
Bases:
objectOne feature vector from a surrogate design.
- Parameters:
features (dict[str, float])
- features: dict[str, float]
- 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:
objectRBF-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:
- 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]
- train_standardized: tuple[tuple[float, ...], ...]
- warnings: tuple[str, ...] = ()
- y_mean: float
- y_scale: float
- exception femic.hydrology.surrogate.HydrologySurrogateError[source]
Bases:
RuntimeErrorRaised 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:
objectStandardized 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:
- 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]
- warnings: tuple[str, ...] = ()
- class femic.hydrology.surrogate.SurrogateDataset(feature_names, target_name, samples, source='', schema_version='femic.hydrology.surrogate_dataset.v1')[source]
Bases:
objectA 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
- class femic.hydrology.surrogate.SurrogateDesign(design_id, generated_utc, factors, points, seed, schema_version='femic.hydrology.surrogate_design.v1')[source]
Bases:
objectLatin-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
- class femic.hydrology.surrogate.SurrogateModel(*args, **kwargs)[source]
Bases:
ProtocolProtocol 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]
- property warnings: tuple[str, ...]
Return model warnings.
- class femic.hydrology.surrogate.SurrogateSample(features, target)[source]
Bases:
objectOne feature/target training or validation sample.
- Parameters:
features (dict[str, float])
target (float)
- features: dict[str, float]
- target: float
- 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:
objectValidation 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:
- 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:
- 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:
- femic.hydrology.surrogate.evaluate_surrogate(model, dataset, *, refuse_out_of_domain=True)[source]
Evaluate a surrogate against held-out samples.
- Parameters:
model (SurrogateModel)
dataset (SurrogateDataset)
refuse_out_of_domain (bool)
- Return type:
- 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:
- femic.hydrology.surrogate.load_surrogate(path)[source]
Load a surrogate model from JSON.
- Parameters:
path (Path)
- Return type:
- femic.hydrology.surrogate.save_surrogate(model, path)[source]
Save a surrogate model as JSON.
- Parameters:
model (SurrogateModel)
path (Path)
- 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:
dataset (SurrogateDataset)
validation_fraction (float)
seed (int)
- Return type:
tuple[SurrogateDataset, SurrogateDataset]