spires_reservoir_create

Allocate and initialize a new reservoir from a configuration struct.

Signature

spires_status spires_reservoir_create(const spires_reservoir_config *cfg,
                                      spires_reservoir **out_r);

Parameters

Returns

spires_status — SPIRES_OK on success. On failure, one of:

• SPIRES_ERR_INVALID_ARG — cfg or out_r is NULL, or a config field is out of range (e.g., num_neurons == 0, spectral_radius < 0, ei_ratio outside [0, 1], fractional neuron type with NULL neuron_params).
• SPIRES_ERR_ALLOC — memory allocation failed. No partial resources are leaked.
• SPIRES_ERR_INTERNAL — internal error during weight matrix generation or spectral rescaling.

Example

spires_reservoir_config cfg = {
    .num_neurons      = 200,
    .num_inputs       = 1,
    .num_outputs      = 1,
    .spectral_radius  = 0.9,
    .ei_ratio         = 0.8,
    .input_strength   = 1.0,
    .connectivity     = 0.1,
    .dt               = 0.001,
    .connectivity_type = SPIRES_CONN_RANDOM,
    .neuron_type       = SPIRES_NEURON_LIF_DISCRETE,
    .neuron_params     = NULL
};
 
spires_reservoir *r = NULL;
spires_status s = spires_reservoir_create(&cfg, &r);
if (s != SPIRES_OK) {
    fprintf(stderr, "creation failed: %d\n", s);
    return 1;
}
 
/* use the reservoir ... */
 
spires_reservoir_destroy(r);

Notes

• Ownership. On success, the caller owns the returned spires_reservoir and must eventually free it with spires_reservoir_destroy. The library does not retain any reference to the cfg struct or its neuron_params array after this call returns.
• Thread safety. This function does not access shared mutable state and is safe to call concurrently from multiple threads, provided each call operates on independent cfg and out_r pointers.
• Determinism. Weight matrix generation uses a pseudo-random number generator. For reproducible reservoirs, seed the RNG before calling this function. Consult the Parallelism guide for details.
• Validation. All config fields are validated before any allocation occurs. If validation fails, no memory is allocated and *out_r is untouched.

See Also

• spires_reservoir_config — the configuration struct.
• spires_reservoir_destroy — free a reservoir.
• spires_reservoir_reset — reset state without reallocating.