pyhgf.updates.vectorised.learning.resolve_synaptic_uncertainty_settings

pyhgf.updates.vectorised.learning.resolve_synaptic_uncertainty_settings(learning_kwargs=None)

Validate the weight-belief rule’s settings and fill in the defaults.

Each weight carries a Gaussian belief: the weight itself is the belief’s mean and the layer’s weights_precision_delta its precision above the prior. One update step does two things.

Mean. The update is \(\Delta w = -\alpha g/\pi + \text{reversion}\), the incoming descent gradient \(g\) divided by the weight’s precision and scaled by learning_rate \(\alpha\), plus a pull of the mean toward prior_mean. At the start \(\pi = \pi_p\) everywhere, so the rule begins as plain gradient descent at rate \(\alpha \times \texttt{prior\_variance}\) and departs from it only as precision accumulates.

Precision. The increment is the curvature the data impose on that weight, delivered as the importance factors of learning_weights_vectorised() or as a full increment matrix. It then relaxes toward the prior in precision form, \(\pi \leftarrow \pi + H - (\pi - \pi_p)/N\) with \(N = \texttt{window}\). The fixed point is \(\pi^\ast = N \bar{H} + \pi_p\), linear in the evidence at every scale, and the mean reversion is precision-scaled, \((\pi_p / (N\pi))(\mu_p - w)\), so a weight the data have pinned is also pulled back more gently.

Both halves are mean-field: each weight’s gradient is divided by its own precision, and the joint structure across the weights feeding one child is not retained.

Parameters:

learning_kwargs (dict | None) –

The settings, as DeepNetwork.fit(learning_kwargs=...) takes them. Recognised keys, with the defaults of SYNAPTIC_UNCERTAINTY_DEFAULTS:

window

The memory window \(N\), in update steps. Importance decays toward the prior at rate \(1/N\), so curvature older than roughly \(N\) steps no longer protects a weight. Required, and at least 1.

prior_variance

Variance of the per-weight prior belief, \(1/\pi_p\). Also the effective learning rate before any importance has accumulated, so a value that trains the model well under plain gradient descent is the natural setting.

prior_mean

Mean the weights revert toward.

learning_rate

Multiplier \(\alpha\) on the gradient part of the mean update. It exists because the rule otherwise has no step size of its own: the effective rate is \(\alpha/\pi\), and once the accumulated curvature dominates the prior the rate is pinned at \(\alpha/(N\bar{H})\). It sets the overall scale of every step but not the ratio between the rate before and after importance accumulates, which is \(1 + N\bar{H}/\pi_p\) and is the depth of protection the rule applies. It does not scale the reversion, which stays at its \(1/N\) rate, so window keeps meaning one thing only: how long importance is remembered.

increment_scale

Multiplier on the importance increment. It deepens protection without touching anything else: the precision reaches \(\pi_p + c\,N\bar{H}\), so the most protected weights slow by \(c\) times more, while the step size before any importance accumulates, the reversion rate and the window are unchanged. A uniform scale leaves rank orderings unchanged.

The gradient the rule descends is not among them: it is fixed to "synaptic_uncertainty".

Returns:

The validated settings, with the prior precision precomputed.

Return type:

SynapticUncertaintySettings

Raises:

ValueError – If a key is unrecognised, window is missing or below 1, or a positive quantity is not positive.