Struct TensorGradAccumulator 

pub struct TensorGradAccumulator { /* private fields */ }

Accumulates gradients across mini-batches before an optimizer step.

Typical usage

use ipfrs_tensorlogic::grad_accumulator::{
    TensorGradAccumulator, AccumulatorConfig, AccumulationMode,
};

let config = AccumulatorConfig {
    accumulation_steps: 2,
    mode: AccumulationMode::Mean,
    max_grad_norm: Some(1.0),
};
let mut acc = TensorGradAccumulator::new(config);

// First mini-batch
acc.accumulate("weight", &[0.5, -0.3]).expect("example: should succeed in docs");
assert!(!acc.is_ready());

// Second mini-batch
acc.accumulate("weight", &[0.7, 0.1]).expect("example: should succeed in docs");
assert!(acc.is_ready());

// Retrieve accumulated gradients and reset
let grads = acc.step().expect("example: should succeed in docs");
assert!(grads.contains_key("weight"));

Implementations

impl TensorGradAccumulator

pub fn new(config: AccumulatorConfig) -> Self

Create a new accumulator with the given configuration.

pub fn accumulate( &mut self, name: &str, gradients: &[f64], ) -> Result<(), String>

Add gradients for the named parameter to the accumulation buffer.

If the buffer for name already exists its length must match gradients.len(), otherwise an error is returned. On the first call for a given name the buffer is created with the supplied length.

After all parameter gradients for a mini-batch have been added the caller should increment the internal step counter by calling accumulate for every parameter in each mini-batch.

pub fn is_ready(&self) -> bool

Returns true when every buffer has accumulated at least accumulation_steps contributions.

pub fn step(&mut self) -> Result<HashMap<String, Vec<f64>>, String>

Consume the accumulated gradients and return the final values.

• In AccumulationMode::Mean mode each gradient vector is divided by the number of steps that were accumulated.
• If max_grad_norm is configured, gradient vectors whose L2 norm exceeds it are rescaled.
• All buffers are cleared after a successful step.

Returns an error if the accumulator is not ready (see is_ready).

pub fn clip_grad_norm(gradients: &mut [f64], max_norm: f64) -> f64

Clip a gradient vector in-place so that its L2 norm does not exceed max_norm.

Returns the original L2 norm (before any scaling).

pub fn get_buffer(&self, name: &str) -> Option<&GradBuffer>

Borrow the buffer for the named parameter, if it exists.

pub fn buffer_count(&self) -> usize

Number of parameter buffers currently tracked.

pub fn reset(&mut self)

Clear all buffers and reset the step counter. Lifetime statistics (total_accumulations, total_clips) are preserved.

pub fn current_step(&self) -> usize

Current accumulation step (0-based within the current window).

pub fn stats(&self) -> AccumulatorStats

Return a snapshot of the accumulator’s statistics.