Struct FlowMapRepr 

pub struct FlowMapRepr {
    pub positions: Vec<f64>,
    pub velocities: Vec<f64>,
    pub f0_values: Vec<f64>,
    pub masses: Vec<f64>,
    pub n_lag: usize,
    pub nv_lag: usize,
    pub spatial_shape: [usize; 3],
    pub domain: Domain,
    /* private fields */
}

Flow-map Lagrangian representation of the 6D distribution function.

Stores n_lag³ * nv_lag³ Lagrangian tracer points, each carrying:

• Initial position q and velocity p (from IC)
• Current position X(t;q,p) and velocity V(t;q,p)
• Initial distribution value f₀(q,p) and particle mass

Density is recovered via CIC deposition, following the same pattern as SheetTracker.

Fields

positions: Vec<f64>

Lagrangian grid positions X(t;q) — flat [x0,y0,z0, x1,y1,z1, …]

velocities: Vec<f64>

Lagrangian grid velocities V(t;q) — flat [vx0,vy0,vz0, …]

f0_values: Vec<f64>

Initial distribution function value f₀(q,p) at each Lagrangian point

masses: Vec<f64>

Mass of each Lagrangian tracer (= f₀ * dq³ * dp³)

n_lag: usize

Number of Lagrangian points per spatial dimension

nv_lag: usize

Number of Lagrangian points per velocity dimension

spatial_shape: [usize; 3]

Spatial grid dimensions for density deposition [nx, ny, nz]

domain: Domain

Domain specification

Implementations

impl FlowMapRepr

pub fn new(domain: &Domain, n_lag: usize, nv_lag: usize) -> Self

Create a new FlowMapRepr with all tracers at their initial positions and zero f₀.

The Lagrangian grid spans the full domain: n_lag³ points in spatial dimensions, nv_lag³ points in velocity dimensions. Each dimension is uniformly spaced.

pub fn from_snapshot( snap: &PhaseSpaceSnapshot, domain: &Domain, n_lag: usize, nv_lag: usize, ) -> Self

Initialize from a PhaseSpaceSnapshot by sampling f₀ at Lagrangian grid points.

Places n_lag³ * nv_lag³ tracers on a regular grid in (x,v) space. Records f₀ at each point via trilinear interpolation of the snapshot data, and computes particle masses as m_i = f₀(q_i, p_i) * dq³ * dp³.

pub fn num_tracers(&self) -> usize

Total number of Lagrangian tracer points.

Trait Implementations

impl PhaseSpaceRepr for FlowMapRepr

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

Register a progress reporter for intra-step progress updates.

fn compute_density(&self) -> DensityField

CIC deposition of tracer masses onto the spatial grid.

For each Lagrangian tracer, finds the 8 nearest spatial cells and distributes its mass using trilinear weights, then divides by cell volume to get density. Uses rayon parallelism with fold/reduce (same pattern as SheetTracker).

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

Drift sub-step: X[i] += V[i] * dt for each tracer. Exact – no interpolation.

For periodic domains, positions are wrapped into [-L, L].

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

Kick sub-step: V[i] += g(X[i]) * dt for each tracer.

The acceleration at each tracer’s current position is obtained by trilinear interpolation of the acceleration field.

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

Velocity moment at a given spatial position.

Finds all tracers in the same spatial cell and computes the requested moment from their velocities and masses.

fn total_mass(&self) -> f64

Total mass. Constant by Liouville’s theorem — returns the cached value.

fn casimir_c2(&self) -> f64

Casimir invariant C₂ = integral of f² over phase space.

Approximated by depositing onto the spatial grid and computing integral of rho^2. This is a spatial-only approximation; the true C₂ involves the 6D distribution.

fn entropy(&self) -> f64

Entropy S = -integral of f ln f over phase space. Constant by Liouville’s theorem — returns the cached value.

fn stream_count(&self) -> StreamCountField

Number of distinct velocity streams at each spatial point.

Counts the number of distinct Lagrangian tracers per spatial cell.

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

Local velocity distribution at a given spatial position.

Collects the speed |v| of all tracers in the same cell as the given position.

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

Total kinetic energy T = sum of 0.5 * mass[i] * |V[i]|^2.

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

Extract a full 6D snapshot by CIC deposition of all tracers.

Each tracer is deposited onto 2^3 x 2^3 = 64 surrounding cells in the 6D grid. This is expensive for large grids and should only be used for checkpoints.

fn as_any(&self) -> &dyn Any

Downcast to &dyn Any for runtime type queries.

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

Downcast to &mut dyn Any for runtime type queries.

fn memory_bytes(&self) -> usize

Heap memory used by position, velocity, f0, and mass arrays.

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.