Skip to Content
DocsAPI ReferenceOptimizeropt_result

spires_opt_result

Struct populated by spires_optimize with the best configuration found and its performance statistics.

Definition

struct spires_opt_result {
    spires_reservoir_config  best_config;
    double                   best_log10_ridge;
    double                   best_score;
    double                   metric_mean;
    double                   metric_std;
};

Fields

FieldTypeDescription
best_configspires_reservoir_configThe reservoir configuration that achieved the highest composite score. This struct can be passed directly to spires_reservoir_create to instantiate a reservoir with the optimized hyperparameters.
best_log10_ridgedoubleBase-10 logarithm of the best ridge regularization parameter. To obtain the actual lambda, compute pow(10.0, best_log10_ridge). The optimizer searches over log-space because good ridge values typically span several orders of magnitude.
best_scoredoubleThe composite score of the best configuration, computed as metric_mean - lambda_var * metric_std - lambda_cost * relative_cost. Higher is better.
metric_meandoubleMean of the selected performance metric (AUROC or AUPRC) across all seeds evaluated in the final budget stage for the best configuration.
metric_stddoubleStandard deviation of the selected performance metric across seeds in the final budget stage. A low value indicates that the configuration performs consistently across different random reservoir instantiations.

Example

struct spires_opt_result result;
 
int rc = spires_optimize(&base, budgets, 3, &score, &result,
                         input, target, series_length);
if (rc != 0) {
    fprintf(stderr, "optimization failed\n");
    return 1;
}
 
printf("Best neurons:       %zu\n", result.best_config.num_neurons);
printf("Best spectral radius: %.3f\n", result.best_config.spectral_radius);
printf("Best log10(lambda): %.2f\n", result.best_log10_ridge);
printf("Composite score:    %.4f\n", result.best_score);
printf("Metric:             %.4f +/- %.4f\n",
       result.metric_mean, result.metric_std);
 
/* Build the final reservoir using the optimized config */
double lambda = pow(10.0, result.best_log10_ridge);
spires_reservoir *r = NULL;
spires_reservoir_create(&result.best_config, &r);
spires_train_ridge(r, input, target, series_length, lambda);

Notes

  • neuron_params lifetime. The best_config.neuron_params pointer inside the result struct points to internally managed memory. It remains valid until the next call to spires_optimize or program termination. If you need the neuron parameters to outlive this window, copy them into your own buffer before calling spires_optimize again.
  • Score interpretation. The best_score is a composite that includes variance and cost penalties (see spires_opt_score). To evaluate raw classification performance, use metric_mean directly.
  • Reproducibility. To reproduce the exact performance of the best configuration, create a reservoir from best_config and train with pow(10.0, best_log10_ridge). Note that different RNG seeds will produce different weight matrices, so metric_std quantifies the expected variation.

See Also

Last updated on
opt_scoreFractional Calculus