Struct TensorTrain 

pub struct TensorTrain {
    pub cores: Vec<TtCore>,
    pub shape: [usize; 6],
    pub ranks: Vec<usize>,
    pub domain: Domain,
    pub tolerance: f64,
    pub max_rank: usize,
    /* private fields */
}

Tensor-Train representation of the 6D phase-space distribution f(x,v).

The TT decomposition factors a 6D tensor into a chain of d=6 three-way cores with TT ranks r_0=1, r_1, r_2, r_3, r_4, r_5, r_6=1.

Fields

cores: Vec<TtCore>

The 6 TT cores. cores[k] has shape (ranks[k], shape[k], ranks[k+1]).

shape: [usize; 6]

Grid sizes: [nx1, nx2, nx3, nv1, nv2, nv3].

ranks: Vec<usize>

TT ranks: [r_0, r_1, r_2, r_3, r_4, r_5, r_6] with r_0 = r_6 = 1.

domain: Domain

Computational domain (extents, BCs).

tolerance: f64

Approximation tolerance for TT-SVD and recompression.

max_rank: usize

Maximum allowed TT rank.

Implementations

impl TensorTrain

pub fn new(domain: Domain, max_rank: usize) -> Self

Create a minimal-rank (all ranks 1) TT representing the zero tensor.

pub fn with_positivity_limiter(self, enabled: bool) -> Self

Enable or disable the Zhang-Shu positivity-preserving limiter.

When enabled, negative values produced by semi-Lagrangian interpolation are clamped to zero after each advection step, with mass-conservative rescaling to preserve the total integral.

pub fn positivity_violations(&self) -> u64

Total number of negative-value cells corrected by the positivity limiter across all advection steps so far.

pub fn from_snapshot( snap: &PhaseSpaceSnapshot, max_rank: usize, tolerance: f64, domain: &Domain, ) -> Self

TT-SVD decomposition of a full 6D snapshot.

Algorithm (Oseledets 2011, Algorithm 1):

1. Reshape the full tensor as C = reshape(data, [n_0, n_1*…*n_5]).
2. For k = 0..4:
   • C has shape (r_{k} * n_k, remaining)
   • Compute truncated SVD: C ≈ U_k * S_k * V_k^T
   • Core k = reshape(U_k, [r_k, n_k, r_{k+1}])
   • C = diag(S_k) * V_k^T for the next step
3. Core 5 = C (the residual, with r_right = 1).

pub fn from_snapshot_owned( snap: PhaseSpaceSnapshot, max_rank: usize, tolerance: f64, domain: &Domain, ) -> Self

Like from_snapshot, but takes ownership of the snapshot data to avoid an O(N^6) clone.

pub fn evaluate(&self, indices: [usize; 6]) -> f64

Evaluate f at a single 6D index by left-to-right contraction of all cores.

f(i0, i1, i2, i3, i4, i5) = G0[:,i0,:] * G1[:,i1,:] * ... * G5[:,i5,:]

pub fn to_full(&self) -> Vec<f64>

Expand the TT back to a full 6D array. Only practical for small grids.

pub fn recompress(&mut self, tolerance: f64)

Recompress the TT to reduce ranks while keeping error below tolerance.

Two-sweep rounding (Oseledets 2011):

1. Left-to-right QR sweep (left-orthogonalize).
2. Right-to-left SVD sweep with truncation.

pub fn add(&self, other: &TensorTrain) -> TensorTrain

Add two TT tensors via rank concatenation (direct sum of cores).

Result has ranks r_self + r_other (before recompression).

pub fn scale(&mut self, factor: f64)

Scale all entries by a constant factor.

pub fn inner_product(&self, other: &TensorTrain) -> f64

TT inner product: <self, other> = sum_{all indices} self(i) * other(i).

Computed by sequential contraction from left to right. O(d * n * r^4).

pub fn norm(&self) -> f64

Frobenius norm: ||self||_F = sqrt(<self, self>).

Trait Implementations

impl PhaseSpaceRepr for TensorTrain

fn set_progress(&mut self, p: Arc<StepProgress>)

Attach shared progress state for intra-phase cell-level reporting. Implementations can use this to report progress via StepProgress::set_intra_progress.

fn compute_density(&self) -> DensityField

Integrate f over all velocities: ρ(x) = ∫f dv³. This is the coupling moment to the Poisson equation.

fn advect_x(&mut self, _displacement: &DisplacementField, dt: f64)

Drift sub-step: advect f in spatial coordinates by displacement Δx = v·dt. Pure translation in x at constant v.

fn advect_v(&mut self, acceleration: &AccelerationField, dt: f64)

Kick sub-step: advect f in velocity coordinates by Δv = g·dt. Pure translation in v at constant x.

fn moment(&self, position: &[f64; 3], order: usize) -> Tensor

Compute velocity moment of order n at given spatial position. Order 0 = density, 1 = mean velocity, 2 = dispersion tensor.

fn total_mass(&self) -> f64

Total mass M = ∫f dx³dv³. Should be conserved to machine precision.

fn casimir_c2(&self) -> f64

Casimir invariant C₂ = ∫f² dx³dv³. Increase over time indicates numerical diffusion.

fn entropy(&self) -> f64

Boltzmann entropy S = −∫f ln f dx³dv³. Should be exactly conserved; growth = numerical error.

fn stream_count(&self) -> StreamCountField

Number of distinct velocity streams at each spatial point. Detects caustic surfaces (sheet folds).

fn velocity_distribution(&self, position: &[f64; 3]) -> Vec<f64>

Extract the local velocity distribution f(v|x) at a given spatial position. Used for dark matter detection predictions.

fn total_kinetic_energy(&self) -> Option<f64>

Total kinetic energy T = ½∫fv² dx³dv³.

fn to_snapshot(&self, time: f64) -> Option<PhaseSpaceSnapshot>

Extract a full 6D snapshot of the current state.

fn as_any(&self) -> &dyn Any

Downcast to concrete type for implementation-specific queries (e.g. HT rank data).

fn as_any_mut(&mut self) -> &mut dyn Any

Mutable downcast for in-place modification (e.g. BUG integrator leaf updates). Returns self as &mut dyn Any. Only HtTensor overrides this; the default returns self but concrete downcasts will yield None.

fn load_snapshot( &mut self, snap: PhaseSpaceSnapshot, ) -> Result<(), CausticError>

Replace the current state with data from a dense 6D snapshot.

fn can_materialize(&self) -> bool

Whether full 6D materialization fits in available memory. Default: true. Compressed representations (HT, TT) should override to check shape vs a memory threshold.

fn memory_bytes(&self) -> usize

Approximate memory usage of this representation in bytes. Default returns 0; implementations should override for accurate tracking.