Crate caustic

Expand description

§caustic

A trait-based 6D Vlasov–Poisson solver for collisionless gravitational dynamics.

caustic evolves the distribution function f(x,v,t) under the coupled Vlasov–Poisson system:

df/dt + v . grad_x f - grad Phi . grad_v f = 0   (Vlasov equation)
laplacian Phi = 4 pi G rho                        (Poisson equation)
rho = integral f dv^3                              (density coupling)

The library uses a pluggable trait architecture: each component (PhaseSpaceRepr, PoissonSolver, Advector, TimeIntegrator, ExitCondition) is a trait with multiple implementations that can be mixed and matched via the Simulation builder.

§Quick Start

use caustic::prelude::*;
use caustic::{
    FftPoisson, SemiLagrangian, StrangSplitting, UniformGrid6D,
    Domain, DomainBuilder, SpatialBoundType, VelocityBoundType,
    Simulation, sample_on_grid,
};

let domain = Domain::builder()
    .spatial_extent(10.0)
    .velocity_extent(5.0)
    .spatial_resolution(16)
    .velocity_resolution(16)
    .t_final(1.0)
    .spatial_bc(SpatialBoundType::Periodic)
    .velocity_bc(VelocityBoundType::Open)
    .build()
    .unwrap();

let ic = PlummerIC::new(1.0, 1.0, 1.0);
let snap = sample_on_grid(&ic, &domain);

let mut sim = Simulation::builder()
    .domain(domain.clone())
    .poisson_solver(FftPoisson::new(&domain))
    .advector(SemiLagrangian::new())
    .integrator(StrangSplitting::new(1.0))
    .initial_conditions(snap)
    .time_final(1.0)
    .build()
    .unwrap();

let exit = sim.run().unwrap();
exit.print_summary();

§Architecture

Trait	Role
`PhaseSpaceRepr`	Store and query f(x,v): grid, tensor, sheet, spectral, AMR
`PoissonSolver`	Solve nabla^2 Phi = 4piG rho: FFT, multigrid, tree, spherical
`Advector`	Advance f by dt via drift (spatial) and kick (velocity) sub-steps
`TimeIntegrator`	Orchestrate the full timestep: Strang, Yoshida, unsplit RK, etc.
`ExitCondition`	Termination predicates: time limit, energy drift, virial, etc.

Use prelude for the most common imports.

Re-exports§

pub use serde_helpers::decimal_serde;
pub use tooling::core::algos::ht::HtTensor;
pub use tooling::core::algos::lagrangian::SemiLagrangian;
pub use tooling::core::init::isolated::HernquistIC;
pub use tooling::core::init::isolated::IsochroneIC;
pub use tooling::core::init::isolated::IsolatedEquilibrium;
pub use tooling::core::init::isolated::KingIC;
pub use tooling::core::init::isolated::NfwIC;
pub use tooling::core::init::isolated::PlummerIC;
pub use tooling::core::init::isolated::sample_on_grid;
pub use tooling::core::init::isolated::sample_on_grid_with_progress;
pub use tooling::core::progress::ProgressSnapshot;
pub use tooling::core::progress::StepPhase;
pub use tooling::core::progress::StepProgress;
pub use tooling::core::algos::uniform::UniformGrid6D;
pub use tooling::core::algos::wpfc;
pub use tooling::core::algos::wpfc::AdvectionScheme;

Modules§

conservative_svd: Conservative SVD: moment-preserving truncation for low-rank tensors.
prelude: Convenience re-exports for the most commonly used items.
serde_helpers
tooling

Structs§

AccelerationField: 3D vector field g = −∇Φ; three flat Vec<f64> for gx, gy, gz components.
AdaptiveStrangSplitting: Adaptive Strang splitting with Lie-in-Strang embedded error estimation.
AmrGrid: Adaptive mesh refinement grid in 6D phase space.
BlanesMoanSplitting: Blanes-Moan 4th-order symplectic integrator (6-stage, palindromic DKD).
BugConfig: Configuration for the BUG integrator.
BugIntegrator: BUG (Basis Update & Galerkin) integrator for low-rank tensor formats.
CasimirDriftCondition: Exit when relative Casimir drift exceeds tolerance.
CausticFormationCondition: Exit when the first caustic forms (max stream count > 1).
CflViolationCondition: Exit when adaptive Δt drops below dt_min.
CosmologicalStrangSplitting: Cosmological Strang splitting with scale-factor-dependent coefficients.
CustomICArray: Pre-computed 6D distribution function loaded from an external file.
DensityField: 3D scalar field ρ(x); flat Vec<f64> with (nx1, nx2, nx3) shape.
DiskStabilityIC: Disk stability initial conditions: Shu (1969) distribution function f(E, Lz) for an axisymmetric disk with optional bulge, halo, and azimuthal perturbation.
DisplacementField: Displacement Δx = v·Δt for the spatial drift sub-step.
Domain: Complete 6D computational domain specification, ready for use by solver components.
DomainBuilder: Fluent builder for Domain.
EnergyDriftCondition: Exit when relative energy drift exceeds tolerance.
ExitEvaluator: Aggregates and evaluates all registered exit conditions each timestep.
FftIsolatedDeprecated: Isolated-boundary-condition Poisson solver using the Hockney-Eastwood zero-padding method.
FftPoisson: Periodic-boundary-condition Poisson solver using 3D FFTs, O(N^3 log N).
FlowMapRepr: Flow-map Lagrangian representation of the 6D distribution function.
GlobalDiagnostics: One row of the global time-series output.
HtPoisson: HT-format Poisson solver for isolated BCs.
HybridRepr: Hybrid representation combining SheetTracker and UniformGrid6D.
InstrumentedStrangSplitting: Instrumented version of StrangSplitting that records per-sub-step ranks and timings.
KfvsSolver: KFVS macroscopic solver on a 3D spatial grid.
LawsonRkIntegrator: Lawson-RK integrator: exact drift + RK4 gravity kick.
LieSplitting: First-order Lie operator splitting: drift(Δt) followed by kick(Δt).
LoMaC: LoMaC conservation manager.
MacroMicroRepr: Macro-micro representation: f = f_M + g.
MacroState: Macroscopic state at a single spatial cell: density, momentum, energy.
MassLossCondition: Exit when mass fraction drops below threshold.
MergerIC: Binary merger initial conditions: two displaced and boosted equilibria.
Multigrid: Geometric multigrid Poisson solver.
MultipoleExpansion: Multipole expansion calculator for computing far-field boundary conditions.
ParallelBugConfig: Configuration for the Parallel BUG integrator.
ParallelBugIntegrator: Parallel BUG integrator: computes all 6 leaf K-steps simultaneously via rayon.
PhaseSpaceDiagnostics: Collected phase-space structure diagnostics for a single time step.
PhaseSpaceSnapshot: Full 6D snapshot f(x,v) at one instant; flat Vec<f64> with shape (nx1, nx2, nx3, nv1, nv2, nv3). Only stored at checkpoint intervals.
PotentialField: 3D scalar potential field Φ(x); same layout as DensityField.
RangeSeparatedPoisson: Range-separated Poisson solver.
RankAdaptiveController: Adaptive rank controller for HT tensor truncation.
RkBugConfig: Configuration for the RK-BUG integrator.
RkBugIntegrator: RK-BUG integrator: classical Runge-Kutta time stepping with BUG tensor updates.
RkeiIntegrator: RKEI: 3rd-order unsplit Runge-Kutta time integrator.
Rkn6Splitting: 6th-order symplectic integrator (triple-jump composition of Yoshida).
SheetTracker: Lagrangian cold dark matter sheet tracker.
Simulation: The top-level simulation object. Owns all solver components.
SpectralV: Spectral-in-velocity representation using orthonormal Hermite function basis.
Spherical1DPoisson: 1D Poisson solver for spherically symmetric density on a uniform radial grid.
SphericalHarmonicsPoisson: Spherical-harmonics expansion Poisson solver.
SphericalRepr: Spherically symmetric phase-space representation on a (r, v_r, L) grid.
SteadyStateCondition: Exit when ‖∂f/∂t‖ < threshold (steady state reached). Uses interior mutability (Cell) to track previous entropy across calls, since the trait takes &self.
StepProducts: End-of-step products from TimeIntegrator::advance().
StepRankDiagnostics: Per-step rank diagnostics, populated by InstrumentedStrangSplitting. Fields are None when the representation is not HtTensor.
StepTimings: Per-step phase timing breakdown in milliseconds. Populated by instrumented time integrators and Simulation::step().
StrangSplitting: Second-order symplectic time integrator via Strang splitting.
StreamCountField: Number of distinct velocity streams n_s(x) at each spatial point. Nonzero where the sheet has folded (caustic formation).
Tensor: General velocity moment tensor of arbitrary rank.
TensorPoisson: Tensor-format Poisson solver with isolated (vacuum) boundary conditions.
TensorTrain: Tensor-Train representation of the 6D phase-space distribution f(x,v).
TidalIC: Tidal stream initial conditions: a satellite on an orbit in a fixed host potential.
TimeLimitCondition: Exit when simulation time reaches t_final.
TreePoisson: Barnes-Hut tree code Poisson solver.
UnsplitIntegrator: Method-of-lines Runge-Kutta integrator for the full 6D Vlasov PDE.
VgfPoisson: Vico–Greengard–Ferrando isolated Poisson solver.
VirialRelaxedCondition: Exit when the virial ratio 2T/|W| stabilises within tolerance of 1.0.
WallClockCondition: Exit when wall-clock time exceeds limit_secs seconds.
YoshidaSplitting: Fourth-order symplectic time integrator via Yoshida splitting.
ZeldovichIC: Multi-mode Zel’dovich pancake IC: cold dark matter sheet with random perturbations.
ZeldovichSingleMode: Single-mode Zel’dovich pancake IC for validation tests.

Enums§

CausticError: Top-level error type for caustic operations.
ExitReason: Reason why the simulation terminated.
SpatialBoundType: Spatial boundary condition type.
VelocityBoundType: Velocity boundary condition type.

Traits§

Advector: Trait for all phase-space advection schemes.
ExitCondition: Trait for simulation exit predicates. Evaluated after each timestep.
PhaseSpaceRepr: Central trait for all phase-space storage and manipulation strategies.
PoissonSolver: Trait for all gravitational Poisson solver implementations.
TimeIntegrator: Trait for all time integration / operator splitting strategies.

Functions§

dec: Convert f64 to Decimal, returning Decimal::ZERO for unrepresentable values.
f64_to_decimal: Convert f64 to Decimal with a warning on unrepresentable values (NaN, Inf, subnormal).
field_energy_spectrum: Gravitational field energy spectrum E(k) = |k|² |Φ̂(k)|² binned by |k|.
poisson_residual_l2: L2 norm of the Poisson residual: ||∇²Φ − 4πGρ||₂.
potential_power_spectrum: Spherically-averaged potential power spectrum P(k) = <|Φ̂(k)|²>.

Crate caustic

Crate caustic Copy item path

§caustic

§Quick Start

§Architecture

Re-exports§

Modules§

Structs§

Enums§

Traits§

Functions§

Crate caustic