Module cache_layout 

Cache-optimized data layouts for particle-based simulations.

This module provides Structure-of-Arrays (SoA) containers, Morton/Z-curve spatial sorting, and cache-line aligned allocation utilities. These data structures are designed for optimal CPU cache utilization and auto-vectorization in particle simulations (SPH, MD, N-body, etc.).

Structure-of-Arrays Layout

Instead of the traditional Array-of-Structures (AoS):

[{x0,y0,z0,vx0,vy0,vz0,...}, {x1,y1,z1,vx1,vy1,vz1,...}, ...]

We store each field in a separate contiguous array:

x:  [x0, x1, x2, ...]
y:  [y0, y1, y2, ...]
z:  [z0, z1, z2, ...]
vx: [vx0, vx1, vx2, ...]
...

This layout allows the compiler to vectorize loops over a single component (e.g., all x-positions) without wasting cache lines on unneeded fields.

Morton (Z-curve) Ordering

Particles can be sorted by their 3D Morton code so that spatially close particles are also close in memory. This dramatically improves cache hit rates for neighbour-search kernels in SPH, MD, and similar methods.

Structs

AlignedVec

Cache-line-aligned vector wrapper.

Particle

A simple AoS particle representation for interchange with SoA containers.

ParticleSoA

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

Enums

CacheLayoutError

Errors arising from cache-layout operations.

Functions

morton_decode_3d

Decode a Morton code back into three unsigned integer coordinates.

morton_encode_3d

Encode three unsigned integer coordinates into a single 63-bit Morton code.

position_to_morton

Convert a floating-point position to a Morton code using the given grid_spacing.