use crate::error::{BarracudaError, Result};
use crate::linalg::ridge::ridge_regression;
use rand::Rng;
use rand::SeedableRng;
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EsnConfig {
pub input_size: usize,
pub reservoir_size: usize,
pub output_size: usize,
pub spectral_radius: f64,
pub sparsity: f64,
pub leak_rate: f64,
#[serde(default = "default_regularization")]
pub regularization: f64,
pub seed: u64,
}
fn default_regularization() -> f64 {
1e-6
}
impl Default for EsnConfig {
fn default() -> Self {
Self {
input_size: 1,
reservoir_size: 100,
output_size: 1,
spectral_radius: 0.95,
sparsity: 0.1,
leak_rate: 0.3,
regularization: 1e-6,
seed: 42,
}
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EsnWeights {
pub config: EsnConfig,
pub w_in: Vec<f64>,
pub w_res: Vec<f64>,
pub w_out: Option<Vec<f64>>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EsnClassifier {
pub config: EsnConfig,
#[serde(skip)]
state: Vec<f64>,
pub w_in: Vec<f64>,
pub w_res: Vec<f64>,
pub w_out: Option<Vec<f64>>,
}
impl EsnClassifier {
pub fn new(config: EsnConfig) -> Result<Self> {
validate_esn_config(&config)?;
let mut rng = rand::rngs::StdRng::seed_from_u64(config.seed);
let w_res = Self::init_reservoir(&config, &mut rng);
let w_in = Self::init_input_weights(&config, &mut rng);
Ok(Self {
config: config.clone(),
state: vec![0.0; config.reservoir_size],
w_in,
w_res,
w_out: None,
})
}
fn init_reservoir(config: &EsnConfig, rng: &mut rand::rngs::StdRng) -> Vec<f64> {
let size = config.reservoir_size;
let mut matrix = vec![0.0; size * size];
for i in 0..size {
for j in 0..size {
if rng.random::<f64>() < config.sparsity {
matrix[i * size + j] = rng.random_range(-1.0..1.0);
}
}
}
let approx_radius = (config.sparsity * size as f64).sqrt();
let scale = config.spectral_radius / approx_radius;
for val in &mut matrix {
*val *= scale;
}
matrix
}
fn init_input_weights(config: &EsnConfig, rng: &mut rand::rngs::StdRng) -> Vec<f64> {
(0..(config.reservoir_size * config.input_size))
.map(|_| rng.random_range(-0.5..0.5))
.collect()
}
pub fn from_json(json: &str) -> Result<Self> {
let weights: EsnWeights =
serde_json::from_str(json).map_err(|e| BarracudaError::InvalidInput {
message: format!("ESN JSON parse error: {e}"),
})?;
validate_esn_config(&weights.config)?;
Ok(Self {
config: weights.config.clone(),
state: vec![0.0; weights.config.reservoir_size],
w_in: weights.w_in,
w_res: weights.w_res,
w_out: weights.w_out,
})
}
pub fn to_json(&self) -> Result<String> {
let weights = EsnWeights {
config: self.config.clone(),
w_in: self.w_in.clone(),
w_res: self.w_res.clone(),
w_out: self.w_out.clone(),
};
serde_json::to_string_pretty(&weights).map_err(|e| BarracudaError::InvalidInput {
message: format!("ESN JSON serialize error: {e}"),
})
}
pub fn reset_state(&mut self) {
self.state.fill(0.0);
}
#[must_use]
pub fn get_state(&self) -> &[f64] {
&self.state
}
pub fn set_state(&mut self, state: &[f64]) {
self.state.resize(state.len(), 0.0);
self.state.copy_from_slice(state);
}
fn update_state(&mut self, input: &[f64]) -> Result<()> {
if input.len() != self.config.input_size {
return Err(BarracudaError::InvalidInput {
message: format!(
"Input size {} != expected {}",
input.len(),
self.config.input_size
),
});
}
let n = self.config.reservoir_size;
let leak = self.config.leak_rate;
let mut new_state = vec![0.0; n];
for (i, new_state_i) in new_state.iter_mut().enumerate() {
let mut sum = 0.0;
for (j, &w) in self.w_in[i * self.config.input_size..(i + 1) * self.config.input_size]
.iter()
.enumerate()
{
sum = w.mul_add(input[j], sum);
}
for (&w, &s_j) in self.w_res[i * n..(i + 1) * n].iter().zip(self.state.iter()) {
sum = w.mul_add(s_j, sum);
}
*new_state_i = sum.tanh();
}
for (s_i, &new_i) in self.state.iter_mut().zip(new_state.iter()) {
*s_i = (1.0 - leak).mul_add(*s_i, leak * new_i);
}
Ok(())
}
pub fn train(&mut self, inputs: &[Vec<f64>], targets: &[Vec<f64>]) -> Result<()> {
if inputs.is_empty() || targets.is_empty() {
return Err(BarracudaError::InvalidInput {
message: "Training data cannot be empty".to_string(),
});
}
if inputs.len() != targets.len() {
return Err(BarracudaError::InvalidInput {
message: "Inputs and targets must have same length".to_string(),
});
}
self.reset_state();
let n = self.config.reservoir_size;
let m = self.config.output_size;
let n_samples = inputs.len();
let n_features = n + 1;
let mut states = vec![0.0; n_samples * n_features];
let mut targets_flat = vec![0.0; n_samples * m];
for (s, (input, target)) in inputs.iter().zip(targets.iter()).enumerate() {
if input.len() != self.config.input_size {
return Err(BarracudaError::InvalidInput {
message: format!(
"Input[{}] size {} != expected {}",
s,
input.len(),
self.config.input_size
),
});
}
if target.len() != m {
return Err(BarracudaError::InvalidInput {
message: format!("Target[{}] size {} != expected {}", s, target.len(), m),
});
}
self.update_state(input)?;
for i in 0..n {
states[s * n_features + i] = self.state[i];
}
states[s * n_features + n] = 1.0;
for j in 0..m {
targets_flat[s * m + j] = target[j];
}
}
let ridge = ridge_regression(
&states,
&targets_flat,
n_samples,
n_features,
m,
self.config.regularization,
)?;
self.w_out = Some(ridge.weights);
Ok(())
}
pub fn predict(&mut self, input: &[f64]) -> Result<Vec<f64>> {
if self.w_out.is_none() {
return Err(BarracudaError::InvalidInput {
message: "ESN must be trained before prediction".to_string(),
});
}
self.update_state(input)?;
let n = self.config.reservoir_size;
let m = self.config.output_size;
let n_features = n + 1;
let w_out = self
.w_out
.as_ref()
.ok_or_else(|| BarracudaError::InvalidInput {
message: "readout weights missing after training guard".to_string(),
})?;
let mut output = vec![0.0; m];
for j in 0..m {
let mut sum = 0.0;
for i in 0..n {
sum = w_out[j * n_features + i].mul_add(self.state[i], sum);
}
sum += w_out[j * n_features + n];
output[j] = sum;
}
Ok(output)
}
pub fn predict_from_state(&self) -> Result<Vec<f64>> {
let w_out = self
.w_out
.as_ref()
.ok_or_else(|| BarracudaError::InvalidInput {
message: "ESN must be trained before prediction".to_string(),
})?;
let n = self.config.reservoir_size;
let m = self.config.output_size;
let n_features = n + 1;
let mut output = vec![0.0; m];
for j in 0..m {
let mut sum = 0.0;
for i in 0..n {
sum = w_out[j * n_features + i].mul_add(self.state[i], sum);
}
sum += w_out[j * n_features + n];
output[j] = sum;
}
Ok(output)
}
#[must_use]
pub fn is_trained(&self) -> bool {
self.w_out.is_some()
}
}
fn validate_esn_config(config: &EsnConfig) -> Result<()> {
if config.input_size == 0 || config.reservoir_size == 0 || config.output_size == 0 {
return Err(BarracudaError::InvalidInput {
message: "All sizes must be greater than zero".to_string(),
});
}
if config.spectral_radius <= 0.0 || config.spectral_radius > 2.0 {
return Err(BarracudaError::InvalidInput {
message: "Spectral radius must be in (0, 2]".to_string(),
});
}
if config.sparsity <= 0.0 || config.sparsity > 1.0 {
return Err(BarracudaError::InvalidInput {
message: "Sparsity must be in (0, 1]".to_string(),
});
}
if config.leak_rate <= 0.0 || config.leak_rate > 1.0 {
return Err(BarracudaError::InvalidInput {
message: "Leak rate must be in (0, 1]".to_string(),
});
}
if config.regularization <= 0.0 {
return Err(BarracudaError::InvalidInput {
message: "Regularization must be positive".to_string(),
});
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
fn make_test_esn() -> EsnClassifier {
let config = EsnConfig {
input_size: 2,
reservoir_size: 50,
output_size: 1,
spectral_radius: 0.95,
sparsity: 0.1,
leak_rate: 0.3,
regularization: 1e-6,
seed: 42,
};
EsnClassifier::new(config).unwrap()
}
#[test]
fn test_esn_train_xor() {
let config = EsnConfig {
input_size: 2,
reservoir_size: 100,
output_size: 1,
spectral_radius: 0.95,
sparsity: 0.1,
leak_rate: 0.3,
regularization: 1e-6,
seed: 42,
};
let mut esn = EsnClassifier::new(config).unwrap();
let inputs = vec![
vec![0.0, 0.0],
vec![0.0, 1.0],
vec![1.0, 0.0],
vec![1.0, 1.0],
];
let targets = vec![vec![0.0], vec![1.0], vec![1.0], vec![0.0]];
esn.train(&inputs, &targets).unwrap();
esn.reset_state();
let p00 = esn.predict(&[0.0, 0.0]).unwrap()[0];
esn.reset_state();
let p01 = esn.predict(&[0.0, 1.0]).unwrap()[0];
esn.reset_state();
let p10 = esn.predict(&[1.0, 0.0]).unwrap()[0];
esn.reset_state();
let p11 = esn.predict(&[1.0, 1.0]).unwrap()[0];
let zeros = f64::midpoint(p00, p11);
let ones = f64::midpoint(p01, p10);
assert!(
ones > zeros,
"XOR: (0,1) and (1,0) should output higher than (0,0) and (1,1); \
got p00={p00:.3} p01={p01:.3} p10={p10:.3} p11={p11:.3}"
);
assert!(p00 < 0.5, "XOR(0,0) should be ~0, got {p00}");
assert!(p11 < 0.5, "XOR(1,1) should be ~0, got {p11}");
}
#[test]
fn test_esn_serde() {
let mut esn = make_test_esn();
let inputs = vec![vec![1.0, 0.0], vec![0.0, 1.0]];
let targets = vec![vec![1.0], vec![0.0]];
esn.train(&inputs, &targets).unwrap();
let json = esn.to_json().unwrap();
let mut esn2 = EsnClassifier::from_json(&json).unwrap();
assert_eq!(esn.w_in.len(), esn2.w_in.len());
assert_eq!(esn.w_res.len(), esn2.w_res.len());
assert!(esn2.w_out.is_some());
esn.reset_state();
esn2.reset_state();
let p1 = esn.predict(&[0.5, 0.5]).unwrap();
let p2 = esn2.predict(&[0.5, 0.5]).unwrap();
assert!((p1[0] - p2[0]).abs() < 1e-10);
}
#[test]
fn test_esn_reset_state() {
let mut esn = make_test_esn();
let inputs = vec![vec![1.0, 1.0], vec![1.0, 1.0]];
let targets = vec![vec![0.0], vec![0.0]];
esn.train(&inputs, &targets).unwrap();
esn.predict(&[1.0, 0.0]).unwrap();
esn.reset_state();
let out = esn.predict(&[0.0, 0.0]).unwrap();
assert!(out[0].abs() < 1.0 || out[0].abs() > 0.0);
}
}