`spires_train_rls`

Train the readout weight matrix using Recursive Least Squares (RLS) over a complete input/target time series. RLS is a streaming, second-order method that processes the series one timestep at a time and converges significantly faster than the online delta rule.

Signature


spires_status spires_train_rls(spires_reservoir *r,
                               const double *input_series,
                               const double *target_series,
                               size_t series_length,
                               double delta, double lambda);

Parameters

Parameter	Type	Description
`r`	`spires_reservoir *`	Handle to the reservoir. Must not be `NULL`. The reservoir is reset before training begins; after training, the state reflects the final timestep of `input_series`.
`input_series`	`const double *`	Flattened input matrix of shape `[series_length x num_inputs]`, row-major. Must not be `NULL`.
`target_series`	`const double *`	Flattened target matrix of shape `[series_length x num_outputs]`, row-major. Element `target_series[t * num_outputs + k]` is the desired output channel `k` at timestep `t`. Must not be `NULL`.
`series_length`	`size_t`	Number of timesteps in both the input and target series. Must be greater than zero.
`delta`	`double`	Initial prior scaling factor. The inverse correlation matrix is initialized as $P(0) = \delta^{-1} I$ . Must be positive. A value of `1.0` is a sensible default. Smaller values produce a wider prior and faster initial adaptation.
`lambda`	`double`	Forgetting factor in $(0, 1]$ . Controls how much older samples are discounted. Use `1.0` for stationary tasks (no forgetting). Values below `1.0` give exponentially decaying memory with effective horizon $\approx 1/(1-\lambda)$ steps.

Returns

spires_status — SPIRES_OK on success. On failure:

SPIRES_ERR_INVALID_ARG — a pointer is NULL, series_length is 0, delta is non-positive, or lambda is outside $(0, 1]$ .
SPIRES_ERR_ALLOC — memory allocation for the inverse correlation matrix $P$ or workspace arrays failed.

Example


double delta  = 1.0;   /* unit prior */
double lambda = 1.0;   /* no forgetting */
 
spires_status s = spires_train_rls(r, input, target, T, delta, lambda);
if (s != SPIRES_OK) {
    fprintf(stderr, "RLS training failed: %d\n", s);
    return 1;
}
 
/* Run inference on new data */
spires_reservoir_reset(r);
for (size_t t = 0; t < test_len; t++) {
    spires_step(r, &test_input[t * num_inputs]);
    double y[NUM_OUTPUTS];
    spires_compute_output(r, y);
}

Notes

Internal workflow. This function (1) resets the reservoir state and zeroes W_out, (2) allocates $P \in \mathbb{R}^{N \times N}$ initialized to $\delta^{-1} I$ , (3) processes each timestep sequentially: steps the reservoir, reads the state x, computes the Kalman gain k = Px / (lambda + x'Px), updates W_out += e * k' where e = target - W_out * x, and downdates P via a rank-1 update, (4) frees P and returns. The trained W_out is stored inside the reservoir for use by spires_compute_output.
Memory. Allocates one $N \times N$ matrix for $P$ ( $8N^2$ bytes in double precision) plus two $O(N)$ workspace vectors. For $N = 400$ this is approximately 1.3 MB. Unlike ridge regression, the full state matrix $\Phi$ is never stored.
Single-call training. The $P$ matrix is local to this function and is freed on return. To continue updating weights incrementally after this call, use spires_train_online.
State after training. The reservoir state after this call reflects the final timestep of input_series. Call spires_reservoir_reset before processing new sequences.
Thread safety. Do not call this function on a reservoir that is concurrently in use by another thread.

spires_train_rls