geoprior.models.tuners#

Model tuner exports and convenience helpers.

class geoprior.models.tuners.SubsNetTuner(fixed_params, search_space=None, objective='val_loss', max_trials=10, project_name='SubsNetrTuner_Project', directory='subsnet_tuner_results', executions_per_trial=1, tuner_type='randomsearch', seed=None, overwrite=True, _logger=None, **kwargs)[source]#

Bases: PINNTunerBase

Specialized tuner for GeoPriorSubsNet models.

This class provides a flexible hyperparameter tuner for the physics-informed GeoPriorSubsNet. It builds on PINNTunerBase and uses keras-tuner backends to search architectural, physics, and compile-time spaces. Fixed, data-dependent parameters are separated from the search space, and GeoPrior input checks are enforced during run and create.

The recommended entry point is SubsNetTuner.create, which infers data dimensions from NumPy arrays, merges them with robust defaults, and applies user overrides.

Parameters:

fixed_params (dict) – Non-tunable configuration passed to the model __init__. Typical keys include static_input_dim, dynamic_input_dim, future_input_dim, output_subsidence_dim, output_gwl_dim, forecast_horizon, and stable flags such as use_batch_norm or pde_mode.
search_space (dict, optional) – Hyperparameter definitions. Each entry is either a list of discrete choices or a typed range dictionary such as {"dropout_rate": {"type": "float", "min_value": 0.1, "max_value": 0.4}}. Supported types are int, float, choice, and bool. Items are routed to model __init__ or to compile as noted below.
objective (str or keras_tuner.Objective, default "val_loss") – Metric to optimize. If the string contains “loss”, direction is inferred as “min”.
max_trials (int, default 10) – Maximum number of trials evaluated by the tuner.
project_name (str, default "SubsNetrTuner_Project") – Project name used for directory layout.
directory (str, default "subsnet_tuner_results") – Root directory where tuner artifacts are saved.
executions_per_trial (int, default 1) – Number of repeated trainings per hyperparameter set.
tuner_type ({'randomsearch', 'bayesianoptimization', 'hyperband'}, default 'randomsearch') – Search algorithm used by keras-tuner.
seed (int, optional) – Random seed for reproducibility.
overwrite (bool, default True) – If True, existing project results are overwritten.
_logger (logging.Logger or callable, optional) – Logger or print-like callable for progress lines.
kwargs (dict) – Forwarded to PINNTunerBase for advanced control.

Variables:

model_class (Type[tf.keras.Model]) – Bound to GeoPriorSubsNet.
fixed_params (dict) – Finalized, non-tunable model configuration.
search_space (dict) – User-provided hyperparameter search definitions.
best_hps (keras_tuner.HyperParameters or None) – Best hyperparameters found by the search.
best_model (tf.keras.Model or None) – Model built with the best hyperparameters.
tuner (keras_tuner.Tuner or None) – Underlying tuner instance after run or search.
tuning_summary (dict) – Compact summary saved under the project directory.

Notes

Required inputs. GeoPriorSubsNet expects coords for spatiotemporal coordinates, dynamic_features for time-varying covariates, and H_field for the soil-thickness field.

The helper canonicalizes H_field from common aliases, e.g., soil_thickness, soil thickness, h_field.

Target canonicalization. Targets are canonicalized to subs_pred and gwl_pred from subsidence and gwl. This is handled internally before data pipelines are built.

Compile-only hyperparameters. These search keys are not passed to __init__ and are routed to compile:

learning_rate
lambda_gw, lambda_cons, lambda_prior, lambda_smooth, lambda_mv
mv_lr_mult, kappa_lr_mult

Losses and metrics. By default the supervised heads use mean squared error with mean absolute error metrics. If fixed_params["quantiles"] is set, a pinball loss can be injected via a user loss factory at compile time.

Physics objectives. GeoPrior adds residuals consistent with consolidation and groundwater flow:

\(R_gw = Ss * d(h)/dt - div(K * grad(h)) - Q\)
\(R_cons = d(s)/dt - (s_eq - s) / tau\)

with \(s_eq = m_v * gamma_w * (h_ref - h) * H\). Weights are controlled by the compile-time lambdas.

Typical search groups.

Architecture: embed_dim, hidden_units, lstm_units, attention_units, num_heads, dropout_rate, vsn_units, use_vsn, use_batch_norm
Physics: pde_mode, mv, kappa, use_effective_h, hd_factor, kappa_mode, scale_pde_residuals
Optimization: learning_rate and lambda weights

Workflow. run builds tf.data pipelines from NumPy inputs, applies key canonicalization, validates GeoPrior requirements, and delegates to search. The best HPs and a built model are returned and stored on the class. The tuning workflow combines Keras Tuner search patterns with the poromechanics background from [21, 22, 23].

Examples

Create from arrays and tune a small space.

>>> from geoprior.models.forecast_tuner import SubsNetTuner
>>> fixed = {"forecast_horizon": 7}
>>> space = {
...   "embed_dim": [32, 64],
...   "num_heads": [2, 4],
...   "dropout_rate": {"type": "float",
...     "min_value": 0.1, "max_value": 0.3},
...   "learning_rate": [1e-3, 5e-4],
...   "lambda_gw": {"type": "float",
...     "min_value": 0.5, "max_value": 1.5},
... }
>>> tuner = SubsNetTuner.create(
...   inputs_data=inputs_np,
...   targets_data=targets_np,
...   search_space=space,
...   fixed_params=fixed,
...   max_trials=20,
...   project_name="GeoPrior_HP_Search",
... )
>>> best_model, best_hps, kt = tuner.run(
...   inputs=inputs_np,
...   y=targets_np,
...   validation_data=(val_inputs_np, val_targets_np),
...   epochs=30,
...   batch_size=32,
... )