Enum RotationState 

pub enum RotationState {
    Real(NoRotation),
    Angle(Tensor<3>),
    Quaternion(Tensor<4>),
    Rotor(Tensor<4>),
}

The cumulative-rotation accumulator carried between calls in a Mamba-3 cache — the variant matching the block’s RotationKind.

• Real — nothing at all: a real transition has no cumulative rotation to carry.
• Angle — abelian per-pair cumulative RoPE angle, shape [batch, nheads, num_rope_angles] (today’s cum_angle).
• Quaternion — per-block cumulative unit quaternion, shape [batch, nheads, blocks, 4], produced by quat_cumprod.

This is the cache-level counterpart of RotationKind. It is defined here (the rotation module owns the accumulator type); substituting it for the pathway caches’ cum_angle_bha field happens together with the forward/step wiring that consumes it.

Variants

Real(NoRotation)

RotationKind::Real1D’s empty accumulator: a real transition composes nothing between calls. It carries a NoRotation only because Burn’s Module derive takes exactly one field per enum variant.

Angle(Tensor<3>)

Abelian RoPE cumulative angle, shape [batch, nheads, num_rope_angles].

Quaternion(Tensor<4>)

Quaternion cumulative rotation, shape [batch, nheads, blocks, 4].

Rotor(Tensor<4>)

SO(4) cumulative rotation, shape [batch, nheads, 2·blocks, 4]: the left factors Qₜ = qₜ⊗⋯⊗q₁ in the first blocks entries of the block axis, the right factors Tₜ = pₜ⊗⋯⊗p₁ in the second (see split_rotor).

One tensor rather than two so the scan, the normalisation and the cache plumbing stay single-call; the conjugation in v ↦ q v p̄ reverses the right-hand order twice, so T accumulates with the very same left-fold as Q and no reversed scan is needed.

Implementations

impl RotationState

pub fn real() -> Self

The empty accumulator of RotationKind::Real1D.

pub fn zeros_angle( batch: usize, nheads: usize, num_rope_angles: usize, device: &Device, ) -> Self

Zero-initialised abelian angle accumulator [batch, nheads, num_rope_angles].

pub fn identity_quaternion( batch: usize, nheads: usize, blocks: usize, device: &Device, ) -> Self

Identity-initialised quaternion accumulator [batch, nheads, blocks, 4] (every block is the identity quaternion (1, 0, 0, 0)).

fn variant(&self) -> &'static str

The variant’s name, for assertion messages.

pub fn expect_real(self) -> Self

Check this is the empty Real accumulator and hand it back; panics on any other variant, so a cache built for a rotating kind cannot be fed to a Real1D block.

pub fn angle(self) -> Tensor<3>

Unwrap the abelian angle accumulator; panics if this is a quaternion.

pub fn identity_rotor( batch: usize, nheads: usize, blocks: usize, device: &Device, ) -> Self

Identity-initialised SO(4) accumulator [batch, nheads, 2·blocks, 4] (both factors of every block are the identity quaternion (1, 0, 0, 0)).

pub fn identity( kind: RotationKind, batch: usize, nheads: usize, num_rope_angles: usize, num_quat_blocks: usize, device: &Device, ) -> Self

The identity accumulator for kind — the one place a fresh cache’s rotation state is built, for every pathway and both cache types.

pub fn quaternion(self) -> Tensor<4>

Unwrap the quaternion accumulator; panics if this is an angle.

pub fn rotor(self) -> Tensor<4>

Unwrap the SO(4) accumulator ([batch, nheads, 2·blocks, 4], both factors stacked); panics for any other variant.

fn quat_stack(self, kind: RotationKind) -> (Tensor<4>, usize)

The stacked quaternion accumulator for kind, together with the number of state 4-blocks it covers — half its block axis for RotationKind::Rotor4D, which stacks two factors there.

Panics on a variant the kind does not use: the two are the same rank and differ only in the length of one axis, so a mismatched cache would otherwise be reinterpreted rather than rejected.

pub fn sanity(&self)

Run the NaN/Inf guards on the held tensor.

Trait Implementations

impl AutodiffModule for RotationState

fn valid(&self) -> Self

Returns the same module, but on the inner backend without auto-differentiation.

fn from_inner(module: Self) -> Self

Wraps an inner module back into an auto-diff module.

impl Clone for RotationState

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RotationState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for RotationState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Module for RotationState

fn num_params(&self) -> usize

Get the number of parameters the module has, including all of its sub-modules.

fn visit<Visitor: ModuleVisitor>(&self, visitor: &mut Visitor)

Visit each tensor parameter in the module with a visitor.

fn map<Mapper: ModuleMapper>(self, mapper: &mut Mapper) -> Self

Map each tensor parameter in the module with a mapper.

fn collect_devices(&self, devices: Devices) -> Devices

Return all the devices found in the underneath module tree added to the given vector without duplicates.

fn to_device(self, device: &Device) -> Self

Move the module and all of its sub-modules to the given device.

fn fork(self, device: &Device) -> Self

Fork the module and all of its sub-modules to the given device.

fn devices(&self) -> Vec<Device>

Return all the devices found in the underneath module tree without duplicates.

fn no_grad(self) -> Self

Each tensor in the module tree will not require grad.

fn freeze_group(self, group: ParamGroup) -> Self

Set require_grad to false for every parameter in the given group, leaving the rest of the module untouched.

fn unfreeze_group(self, group: ParamGroup) -> Self

Set require_grad to true for every parameter in the given group, leaving the rest of the module untouched.

fn train(self) -> Self

where Self: AutodiffModule,

Move the module and all of its sub-modules to the autodiff backend.

fn quantize_weights(self, quantizer: &mut Quantizer) -> Self

Quantize the weights of the module.

fn quantize_weights_group( self, quantizer: &mut Quantizer, group: ParamGroup, ) -> Self

Quantize the weights of the given parameter group.

fn apply_reparameterization<R>(self, reparameterizer: R) -> Self

where Self: Sized, R: Reparameterizer,

Attach reparameterizations using the given [Reparameterizer].

fn apply_lora(self, lora: Lora) -> Self

where Self: Sized,

Attach LoRA adapters to the module’s 2-D weights, freezing the base weights.

fn apply_qlora(self, qlora: QLora) -> Self

where Self: Sized,

Apply QLoRA to the module: quantize the (frozen) base weights and attach trainable LoRA adapters to 2-D weights.

fn into_record(self) -> ModuleRecord

where Self: Sized,

Collect this module’s parameters into a ModuleRecord.

fn into_record_group(self, group: ParamGroup) -> ModuleRecord

where Self: Sized,

Collect the parameters group names into a ModuleRecord.

fn try_load_record(self, record: ModuleRecord) -> Result<Self, RecordError>

where Self: Sized,

Apply a ModuleRecord to this module, returning the loaded module.

fn load_record(self, record: ModuleRecord) -> Self

where Self: Sized,

Apply a ModuleRecord to this module, consuming and returning it.

fn save_file<P>(self, path: P) -> Result<(), RecordError>

where P: AsRef<Path>, Self: Sized,

Save this module’s parameters to a burnpack file on disk.

fn load_file<P>(self, path: P) -> Self

where P: AsRef<Path>, Self: Sized,

Load this module’s parameters from a burnpack file on disk, returning the loaded module.

fn try_load_file<P>(self, path: P) -> Result<Self, RecordError>

where P: AsRef<Path>, Self: Sized,

Fallible variant of load_file.

impl ModuleDisplay for RotationState

fn format(&self, passed_settings: DisplaySettings) -> String

Formats the module with provided display settings.

fn custom_settings(&self) -> Option<DisplaySettings>

Custom display settings for the module.

fn custom_content(&self, _content: Content) -> Option<Content>

Custom attributes for the module.

impl ModuleDisplayDefault for RotationState

fn content(&self, content: Content) -> Option<Content>

Attributes of the module used for display purposes.

fn num_params(&self) -> usize

Gets the number of the parameters of the module.