Struct PlasticityTrainer 

pub struct PlasticityTrainer {
    pub config: TrainingConfig,
}

Reward-modulated training loop over a SpikingNetwork.

Applies scalar rewards to neuromodulators and steps the network. Domain-specific logic (mining, trading, distillation) does not belong here. For critic-shaped vectors under the critic feature, use Self::train_step_from_critic or crate::bridge (plain code spans, not doc links — both only exist with the critic feature enabled).

Fields

config: TrainingConfig

Active training configuration.

Implementations

impl PlasticityTrainer

pub fn new(config: TrainingConfig) -> Self

Creates a trainer with the given configuration.

pub fn train_step( &mut self, network: &mut SpikingNetwork, stimuli: &[f32], reward: f32, ) -> Result<Vec<usize>, StepError>

Runs one training step with generic stimuli and an externally computed reward.

When TrainingConfig::use_reward_modulation is true (default) and reward is finite, positive values increase dopamine and decrease norepinephrine; negative values do the opposite emphasis. Modulator values are clamped to [0.0, 1.0]. Non-finite rewards (NaN and ±infinity) leave modulators unchanged so invalid environment data cannot poison plasticity updates. When the flag is false, the network steps with its current modulators unchanged regardless of reward.

Returns indices of neurons that spiked, or a StepError from neuromod.

pub fn train_step_with_rng<R: Rng + ?Sized>( &mut self, network: &mut SpikingNetwork, stimuli: &[f32], reward: f32, rng: &mut R, ) -> Result<Vec<usize>, StepError>

Same as Self::train_step, but drives neuromod’s stochastic input encoding from a caller-supplied RNG.

Use this when a session must be replayable: the same network state, config, stimuli, reward, and RNG stream produce identical spikes and plasticity updates. train_step keeps the convenience path that uses neuromod’s thread-local RNG.

Examples

use neuromod::SpikingNetwork;
use plasticity_lab::{PlasticityTrainer, TrainingConfig};
use rand::SeedableRng;
use rand::rngs::StdRng;

let mut trainer = PlasticityTrainer::new(TrainingConfig::default());
let mut network = SpikingNetwork::with_dimensions(4, 2, 8);
let mut rng = StdRng::seed_from_u64(42);
let spikes = trainer
    .train_step_with_rng(&mut network, &[0.25; 8], 0.2, &mut rng)
    .unwrap();
assert!(spikes.iter().all(|&i| i < 4));

pub fn train_step_with_modulators( &mut self, network: &mut SpikingNetwork, stimuli: &[f32], modulators: &NeuroModulators, ) -> Result<Vec<usize>, StepError>

Steps the network with explicit neuromodulators (e.g. from the limbic bridge).

Does not apply scalar reward shaping; callers that already ran a critic should convert via crate::to_neuromodulators (critic feature; a plain code span, not a doc link — that item doesn’t exist without the feature) and pass the result here.

pub fn train_step_with_modulators_and_rng<R: Rng + ?Sized>( &mut self, network: &mut SpikingNetwork, stimuli: &[f32], modulators: &NeuroModulators, rng: &mut R, ) -> Result<Vec<usize>, StepError>

Same as Self::train_step_with_modulators, with a caller-supplied RNG.

pub fn train_step_from_critic( &mut self, network: &mut SpikingNetwork, stimuli: &[f32], vector: &ModulatorVector, ) -> Result<Vec<usize>, StepError>

Steps the network with a critic limbic_critic::ModulatorVector.

Converts via crate::bridge::to_neuromodulators then steps. Available only with the critic feature.

pub fn run_session( &mut self, network: &mut SpikingNetwork, data: &[TrainingExample], ) -> Result<TrainingSummary, TrainerError>

Replays a batch of generic training examples and returns aggregated metrics.

Admission is atomic: every example is validated (dimensions, finite stimuli, infinite-reward) before the first train_step. A malformed sample at index N therefore cannot leave samples 0..N applied. Examples are then processed in slice order, matching the historical sequential contract.

This is the no-observer compatibility path: it does not construct TrainingStepEvents, format or serialize telemetry, or dynamically dispatch. For per-step callbacks see Self::run_session_with_observer.

Errors

• TrainerError::EmptyBatch if data is empty (no sample index).
• TrainerError::InvalidSample if any example fails preflight; the error names the first failing index and invariant. Network and trainer state are unchanged.
• TrainerError::Step if a network step fails after admission (for example a StepError that cannot be seen from the example alone).

pub fn run_session_with_rng<R: Rng + ?Sized>( &mut self, network: &mut SpikingNetwork, data: &[TrainingExample], rng: &mut R, ) -> Result<TrainingSummary, TrainerError>

Replays a batch using a caller-supplied RNG for every network step.

Identical to Self::run_session except stochastic input spikes are drawn from rng instead of neuromod’s thread-local generator. One RNG stream is used for the whole batch — it is not reseeded per example. A starting seed replays from the beginning; a mid-session resume needs that same generator already advanced through the prefix, not a fresh seed on a deserialized checkpoint.

Errors

• TrainerError::EmptyBatch if data is empty.
• TrainerError::Step if any network step fails.

pub fn run_session_with_observer<O: TrainingObserver>( &mut self, network: &mut SpikingNetwork, data: &[TrainingExample], observer: &mut O, ) -> Result<TrainingSummary, TrainerError>

Replays a batch like Self::run_session, notifying observer after each successful network step.

Exactly one TrainingStepEvent is delivered per completed step, in batch order. The event borrows spike indices and neuromodulator state; it does not expose mutable network access.

If observer returns an error at step N (0-based), the session aborts before stepping example N + 1. The error reports step_index and the number of network steps that completed (TrainerError::Observer).

The observer is a generic type parameter (monomorphized, not dyn), so a simple callback has no dynamic dispatch on the hot path. The no-observer Self::run_session path does not construct events.

Errors

• TrainerError::EmptyBatch if data is empty (observer is not called).
• TrainerError::Step if a network step fails (observer is not called for that failed step; earlier steps have already been observed).
• TrainerError::Observer if observer returns an error.