Neural Parameterization

nn_global — globally shared learned parameter

An nn_global parameter is a globally shared learned value: a single scalar applied to all locations. Internally it is stored as an unconstrained logit and mapped to its physical range via a logistic (sigmoid) transform:

physical = lower + (upper - lower) * sigmoid(logit)

This bounded transform is smooth and differentiable, keeping values strictly within the declared physical bounds throughout optimization—no clamping needed.

The logit is initialized from a standard normal distribution (seeded from site_learning.training.seed) and updated directly by the optimizer.

Suitable for: parameters expected to take a single effective value across all sites, such as radiation half-saturation or VPD sensitivity coefficients.

nn_feature_based — spatially varying learned parameter

An nn_feature_based parameter is a spatially varying learned parameter: an attribute-to-parameter mapping from static environmental attributes to parameter values. The current implementation uses one independent multilayer perceptron (MLP) per physical parameter, but the framework accepts any differentiable mapping of the attributes.

For site-wise parameters, the mapping predicts one value per site.

For layer-wise parameters, it predicts one value per site and soil layer. ADELM selects the execution path from the target parameter shape; the config always uses the same source name, nn_feature_based.

The mapping structure is:

[n_features]
    -> Linear -> ELU -> Dropout
    -> ...
    -> Linear -> sigmoid -> physical bounds
    = parameter values within declared bounds

• Inputs for site-wise parameters: static environmental attribute features listed in parameterization.nn.attri_features.

• Inputs for layer-wise parameters: the same attribute features, augmented with soil_sand_fraction, soil_clay_fraction, and soil_organic_matter_fraction for each soil layer.

• Hidden layers: widths configured via parameterization.nn.hidden_dims.

• Dropout: applied after each hidden ELU; rate set by parameterization.nn.dropout_rate.

• Output:

  • site-wise parameters produce one bounded value per site

  • layer-wise parameters produce one bounded value per site and soil layer

• Initialization: weights use Kaiming uniform initialization; biases are set to zero.

Suitable for: parameters expected to vary spatially with vegetation type, climate, or soil conditions—such as maximum stomatal conductance or root distribution shape—as well as layered soil parameters whose values depend on both site context and soil texture.

Bounds and physical constraints

See also

Configuration — parameterization.parameters section for how to declare bounds in config.yaml.

Every nn_global or nn_feature_based parameter must declare bounds: [lower, upper] in the config. The logistic transform guarantees that the predicted value always lies strictly inside (lower, upper) without clipping.

parameterization:
  parameters:
    jarvis_max_stomatal_conductance:
      source: nn_feature_based
      bounds: [50, 300]        # mm s-1; sigmoid output always in (50, 300)
    jarvis_radiation_half_saturation:
      source: nn_global
      bounds: [50, 800]        # W m-2

During training

Learnable parameters are recomputed during each forward pass using the current weights. Gradients propagate back through the bounded transform and into the MLP weights (for nn_feature_based) or the logit scalars (for nn_global), so the entire forward chain—process equations, state updates, parameter mappings, and loss—shares a single automatic-differentiation graph.