Parameters API#

The geoprior.params module provides compact, self-documenting parameter descriptors for scalar physical quantities used in physics-guided neural networks and related geoscientific workflows. The module combines two complementary ideas:

Learnable scalar wrappers for parameters that should be estimated during training, often through a log-space parametrisation that preserves positivity.
Fixed scalar wrappers for constants and modelling datums that should remain non-trainable while still participating cleanly in configuration, serialization, and model assembly.

In the GeoPrior subsidence workflow, these wrappers are especially useful for global physical hyperparameters such as effective compressibility, consistency factors, the effective unit weight of water, or a reference hydraulic head. They complement the spatially varying effective fields learned elsewhere in the model stack rather than replacing them. The module also retains a legacy family of coefficient wrappers for backwards-compatible handling of a generic positive physics coefficient C.

The implementation supports both a TensorFlow-backed mode and a NumPy fallback mode. In TensorFlow mode, learnable parameters are represented through trainable variables and can participate directly in optimization. In fallback mode, the same wrappers degrade gracefully to numeric values while preserving a consistent user-facing interface.

Design overview#

The API can be read as three layers.

Legacy coefficient descriptors These wrappers keep compatibility with earlier workflows that expose a generic positive coefficient C.
General learnable and fixed bases These base classes provide the shared semantics for trainable versus fixed scalar descriptors, configuration handling, and value retrieval.
Domain-facing parameter descriptors and resolver helpers These are the classes and functions most users interact with, including hydraulic conductivity, specific storage, source/sink strength, compressibility, consistency factors, water unit weight, and reference-head configuration.

Public module surface#

The following autosummary blocks use the current module context with an explicit toctree layout so that the API page remains stable during Sphinx builds.

Module reference#

Module geoprior.params provides small, self-documenting helpers for scalar physical hyperparameters used in PINNs and physics-guided nets.

Two families of descriptors are provided:

Learnable scalars (subclasses of BaseLearnable) such as LearnableK, LearnableSs, LearnableMV, LearnableKappa, etc. These wrap a trainable scalar, often stored in log-space to enforce positivity.
Fixed scalars (subclasses of BaseFixed) such as FixedGammaW and FixedHRef, used for constants in the physics block.

Legacy descriptors LearnableC, FixedC and DisabledC are kept for backwards-compatible handling of a generic positive coefficient \(C\).

In the GeoPriorSubsNet consolidation model specifically, the spatial fields \(K(x,y)\), \(S_s(x,y)\), \(H(x,y)\) and the relaxation time \(\tau(x,y)\) are represented as effective fields built from covariates and the neural network, whereas the scalar wrappers here represent global hyperparameters such as the effective compressibility \(m_v\), the consistency factor \(\bar\kappa\), the unit weight of water \(\gamma_w\) and the reference head \(h_{\mathrm{ref}}\).

Legacy coefficient descriptors#

These wrappers preserve backwards compatibility for a generic physics coefficient C. They remain useful when older experiments or saved configurations still rely on the original coefficient-based interface.

`LearnableC`	Indicates that the PINN’s physical coefficient \(C\) should be learned (trainable).
`FixedC`	Non-trainable, constant \(C\).
`DisabledC`	Disable physics – \(C\) is ignored.

General parameter bases#

For advanced extension work, the module exposes abstract base classes for learnable and fixed scalar descriptors. These bases are helpful when implementing new parameter families that should follow the same serialization and runtime conventions as the built-in descriptors.

`BaseLearnable`	Abstract base for learnable physical parameters.
`BaseFixed`	Abstract base for fixed physical parameters.

Learnable physical descriptors#

The learnable family wraps trainable scalar quantities used in the physics-guided model. Positive parameters generally use a log-space representation so that optimization proceeds in an unconstrained space while the recovered physical parameter stays positive.

`LearnableK`	Learnable Hydraulic Conductivity (K).
`LearnableSs`	Learnable Specific Storage (Ss).
`LearnableQ`	Learnable Source/Sink term (Q).
`LearnableMV`	Learnable effective vertical compressibility (m_v).
`LearnableKappa`	Learnable scalar consistency factor (\(\bar{\kappa}\)).

Fixed physical descriptors#

The fixed family is intended for constants and modelling datums that must remain non-trainable. Although fixed, these objects still provide a uniform configuration and retrieval interface, which makes them easier to integrate into model construction and serialization logic.

`FixedGammaW`	Fixed scalar for the (effective) unit weight of water \(\gamma_w\).
`FixedHRef`	Reference head configuration \(h_{\mathrm{ref}}\) for drawdown.

Resolution and normalization helpers#

The resolver helper provides a flexible bridge between raw numeric values, wrapper instances, configuration dictionaries, and serialization workflows. It is the most convenient entry point when a pipeline wants to accept both simple user input and explicit descriptor objects.

resolve_physical_param

Normalize a physical-parameter descriptor with enhanced flexibility.

Interpretation in the GeoPrior workflow#

The parameter wrappers documented here should be interpreted as global scalar descriptors. In other parts of the GeoPrior modeling stack, quantities such as hydraulic conductivity, specific storage, compressible thickness, and relaxation time may also appear as spatially varying effective fields learned from covariates and neural representations. The purpose of geoprior.params is different: it captures global scalar hyperparameters and modelling constants in a form that remains explicit, serializable, and physically interpretable.

This distinction is particularly important for subsidence forecasting. For example, a scalar compressibility wrapper such as LearnableMV does not replace the learned field structure in the main subsidence model. Instead, it provides a compact and interpretable scalar quantity that can be reused by equilibrium relations, priors, or consistency terms. Likewise, LearnableKappa represents a scalar consistency factor used in a relaxation-time prior, while FixedGammaW and FixedHRef act as physical constants or datum choices that help make the governing relations explicit.

Usage examples#

The examples below illustrate the intended public usage pattern. Because the public import surface is the module itself, users typically write imports of the following form:

from geoprior.params import LearnableK
from geoprior.params import LearnableMV
from geoprior.params import FixedGammaW
from geoprior.params import FixedHRef
from geoprior.params import resolve_physical_param

A learnable conductivity descriptor:

from geoprior.params import LearnableK

k_param = LearnableK(initial_value=1.0)
value = k_param.get_value()

A fixed reference-head descriptor:

from geoprior.params import FixedHRef

h_ref = FixedHRef(value=0.0, mode="auto")

A flexible resolution step from a raw numeric value:

from geoprior.params import resolve_physical_param

mv = resolve_physical_param(
    1e-7,
    name="mv",
    status="learnable",
    param_type="MV",
)

Notes#

The module exports a compact public surface through __all__ for the main descriptor families, including the legacy C wrappers, learnable scalar descriptors, and the fixed GammaW / HRef descriptors.
The helper resolve_physical_param() broadens that surface by normalizing numbers, wrappers, strings, and configuration dictionaries into a consistent descriptor workflow.
Private helpers such as _BaseC and the lower-level conversion utilities are intentionally omitted from the public API summary so that the page stays focused on the import patterns intended for end users.