Struct ParticleSoA 

pub struct ParticleSoA {
    pub x: Vec<f64>,
    pub y: Vec<f64>,
    pub z: Vec<f64>,
    pub vx: Vec<f64>,
    pub vy: Vec<f64>,
    pub vz: Vec<f64>,
    pub fx: Vec<f64>,
    pub fy: Vec<f64>,
    pub fz: Vec<f64>,
    pub mass: Vec<f64>,
    /* private fields */
}

Cache-friendly particle storage using Structure-of-Arrays layout.

Positions, velocities, and forces are stored in separate contiguous arrays for optimal vectorization and cache utilization. This layout is ideal for tight inner loops that only touch one or two fields at a time (e.g., force accumulation only needs x, y, z, fx, fy, fz – velocities stay cold).

Examples

use oxiphysics_core::cache_layout::ParticleSoA;

let mut soa = ParticleSoA::new(0);
soa.push([1.0, 2.0, 3.0], [0.1, 0.2, 0.3], [0.0; 3], 1.0);
assert_eq!(soa.len(), 1);
assert_eq!(soa.get_position(0).expect("valid index"), [1.0, 2.0, 3.0]);

Fields

x: Vec<f64>

X positions.

y: Vec<f64>

Y positions.

z: Vec<f64>

Z positions.

vx: Vec<f64>

X velocities.

vy: Vec<f64>

Y velocities.

vz: Vec<f64>

Z velocities.

fx: Vec<f64>

X forces.

fy: Vec<f64>

Y forces.

fz: Vec<f64>

Z forces.

mass: Vec<f64>

Masses.

Implementations

impl ParticleSoA

pub fn new(capacity: usize) -> Self

Allocate a new, empty container pre-allocated for capacity particles.

pub fn len(&self) -> usize

Number of particles currently stored.

pub fn is_empty(&self) -> bool

Whether the container holds zero particles.

pub fn capacity(&self) -> usize

Current allocated capacity (in particles).

pub fn push(&mut self, pos: [f64; 3], vel: [f64; 3], force: [f64; 3], mass: f64)

Append a single particle.

pub fn get_position(&self, i: usize) -> Result<[f64; 3], CacheLayoutError>

Return the position of particle i.

Returns Err if i >= len().

pub fn set_position( &mut self, i: usize, pos: [f64; 3], ) -> Result<(), CacheLayoutError>

Set the position of particle i.

Returns Err if i >= len().

pub fn get_velocity(&self, i: usize) -> Result<[f64; 3], CacheLayoutError>

Return the velocity of particle i.

Returns Err if i >= len().

pub fn set_velocity( &mut self, i: usize, vel: [f64; 3], ) -> Result<(), CacheLayoutError>

Set the velocity of particle i.

Returns Err if i >= len().

pub fn get_force(&self, i: usize) -> Result<[f64; 3], CacheLayoutError>

Return the force on particle i.

Returns Err if i >= len().

pub fn set_force( &mut self, i: usize, force: [f64; 3], ) -> Result<(), CacheLayoutError>

Set the force on particle i.

Returns Err if i >= len().

pub fn zero_forces(&mut self)

Zero all force components. This is a very cache-friendly operation because it streams through three contiguous arrays sequentially.

pub fn from_aos(particles: &[Particle]) -> Self

Convert from an AoS slice of Particles.

pub fn to_aos(&self) -> Vec<Particle>

Convert back to an AoS VecParticle`.

pub fn swap(&mut self, i: usize, j: usize) -> Result<(), CacheLayoutError>

Swap two particles at indices i and j.

Returns Err if either index is out of bounds or if i == j.

pub fn sort_by_morton_code( &mut self, grid_spacing: f64, ) -> Result<(), CacheLayoutError>

Sort all particles by their 3D Morton (Z-curve) code.

After sorting, particles that are spatially close share nearby memory addresses, which dramatically improves cache performance for neighbour-search algorithms.

Returns Err if grid_spacing is invalid (non-positive or non-finite). Returns Ok(()) immediately if the container has fewer than two particles.

pub fn prefetch_range(&self, _start: usize, _end: usize)

Hint the CPU prefetcher to load particles in \[start, end).

On stable Rust this is a no-op; it documents the developer’s intent and may be replaced with intrinsic prefetch instructions when they stabilise.

pub fn get_mass(&self, i: usize) -> Result<f64, CacheLayoutError>

Return the mass of particle i.

Returns Err if i >= len().

pub fn pop(&mut self) -> Result<Particle, CacheLayoutError>

Remove the last particle (analogous to Vec::pop).

Returns the removed particle, or Err if the container is empty.

pub fn clear(&mut self)

Remove all particles without deallocating.

pub fn reserve(&mut self, additional: usize)

Reserve capacity for at least additional more particles.

pub fn bounding_box(&self) -> Result<([f64; 3], [f64; 3]), CacheLayoutError>

Compute the axis-aligned bounding box of all particles.

Returns (min_corner, max_corner) or Err if empty.

pub fn kinetic_energy(&self) -> f64

Compute the total kinetic energy: sum_i 0.5 * m_i * |v_i|^2.

pub fn centre_of_mass(&self) -> Result<[f64; 3], CacheLayoutError>

Compute the centre of mass position.

Returns Err if the container is empty or total mass is zero.

Trait Implementations

impl Clone for ParticleSoA

fn clone(&self) -> ParticleSoA

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ParticleSoA

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

Formats the value using the given formatter.

impl PartialEq for ParticleSoA

fn eq(&self, other: &ParticleSoA) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for ParticleSoA