Physical Parameter Descriptors

The fusionlab.params module provides a suite of simple, self-documenting classes designed to give you explicit control over how physical coefficients are handled within the library’s Physics-Informed Neural Networks (PINNs).

Instead of using ambiguous strings like 'learnable' or bare floats, these classes make the model’s configuration clear and robust. They allow you to specify whether a physical parameter should be treated as a fixed constant or as a trainable variable to be discovered by the model during training (inverse modeling).

General Learnable Parameters (BaseLearnable)

This is the modern and recommended approach for defining any physical parameter in models like TransFlowSubsNet. The BaseLearnable class is an abstract base that provides a consistent framework for creating learnable or fixed physical constants.

Key Features:

  • Explicit Control: Clearly defines whether a parameter is trainable.

  • Positivity Constraints: Can enforce positivity for parameters like hydraulic conductivity (\(K\)) by learning their logarithm, \(\log(K)\), and then taking the exponent during use.

  • Keras Serialization: Fully compatible with Keras model saving and loading.

LearnableK

API Reference:

LearnableK

A specific implementation for defining the Hydraulic Conductivity (\(K\)). By default, it uses a log-transform to ensure the learned value of \(K\) is always positive.

Usage Example

1from fusionlab.params import LearnableK
2
3# Define K as a trainable variable, starting from an initial
4# guess of 0.001. The model will learn its optimal value.
5k_parameter = LearnableK(initial_value=0.001)
6
7# In the model, you would pass this object:
8# model = TransFlowSubsNet(..., K=k_parameter, ...)

LearnableSs

API Reference:

LearnableSs

An implementation for defining the Specific Storage (\(S_s\)). Like LearnableK, it defaults to using a log-transform to enforce positivity.

Usage Example

1from fusionlab.params import LearnableSs
2
3# Define Ss as a trainable variable with an initial value.
4ss_parameter = LearnableSs(initial_value=1e-5)

LearnableQ

API Reference:

LearnableQ

An implementation for defining the Source/Sink Term (\(Q\)). Unlike \(K\) and \(S_s\), the source/sink term can be positive (injection) or negative (pumping). Therefore, this class does not use a log-transform by default and learns the value directly.

Usage Example

1from fusionlab.params import LearnableQ
2
3# Define Q as a trainable variable, starting from zero.
4q_parameter = LearnableQ(initial_value=0.0)

Consolidation Coefficient Descriptors (_BaseC)

These are the original, more specialized descriptor classes designed specifically for the consolidation coefficient (\(C\)) used in PIHALNet. While the general BaseLearnable is now preferred, these remain useful and provide clear, self-documenting intent.

LearnableC

API Reference:

LearnableC

This class signals that the consolidation coefficient \(C\) should be a trainable variable. It learns \(\log(C)\) to ensure \(C > 0\).

Usage Example

1from fusionlab.params import LearnableC
2
3# Configure the model to discover the value of C during training.
4learnable_c = LearnableC(initial_value=0.01)
5# model = PIHALNet(..., pinn_coefficient_C=learnable_c)

FixedC

API Reference:

FixedC

This class signals that the coefficient \(C\) should be treated as a non-trainable, fixed constant.

Usage Example

1from fusionlab.params import FixedC
2
3# Use a known, fixed value for C.
4fixed_c = FixedC(value=0.05)
5# model = PIHALNet(..., pinn_coefficient_C=fixed_c)

DisabledC

API Reference:

DisabledC

This class is a simple flag used to signal that the physics-informed loss related to the coefficient \(C\) should be completely disabled. This is useful for running the model in a purely data-driven mode for ablation studies.

Usage Example

1from fusionlab.params import DisabledC
2
3# Run the model without the consolidation physics constraint.
4# Note: The `lambda_physics` weight in .compile() should also be 0.
5no_physics_c = DisabledC()
6# model = PIHALNet(..., pinn_coefficient_C=no_physics_c)

Parameter Resolution Utility (resolve_physical_param)

API Reference:

resolve_physical_param()

This is a powerful internal utility that normalizes the various ways a user might specify a physical parameter (e.g., a simple float, the string 'learnable', or a LearnableK instance) into a consistent internal representation that the model can use. While you typically won’t call this function directly, it’s what allows the model constructors to be so flexible.