Welcome to NSphere's Documentation!
Overview
NSphere simulates the evolution of spherical self-gravitating systems, primarily targeting collisionless dark matter halos in astrophysics. It leverages the inherent spherical symmetry to simplify the complex 𝑁-body problem. By reducing the six-dimensional phase space (position and velocity) to three dimensions (radius r, radial velocity 𝑣ᵣ, and angular momentum ℓ or velocity angle), the computational cost is significantly lowered. The core principle is self-consistency: the gravitational potential is generated by the mass distribution of all particles, and particles orbit within that potential. In equilibrium, such systems, described by a phase-space Distribution Function (DF) often dependent on energy (ε) and angular momentum (ℓ), are generally stable. NSphere provides a tool to efficiently explore how these systems evolve when perturbed or subjected to new physical processes (e.g., Self-Interacting Dark Matter (SIDM), central black hole growth, external tidal forces) where analytical solutions are intractable.
Numerical Implementation
The simulation evolves a system of 𝑁 particles, often representing concentric mass shells. The algorithm proceeds in discrete time steps. At each step:
1. Sorting: Particles are efficiently sorted by their radial coordinate r. This allows for rapid calculation of the mass enclosed within any radius, M(r), which determines the gravitational force. The implementation utilizes optimized sorting algorithms like Quadsort, achieving nearly 𝑁 log 𝑁 or even linear scaling for the nearly-ordered data typical between steps.
2. Force Calculation: The gravitational force on each particle is calculated based solely on the mass M(r) enclosed within its current radius (Newton's Shell Theorem). Centrifugal force due to angular momentum (ℓ²/r³) is added.
3. Integration: Particle states (radius r and radial velocity 𝑣ᵣ) are updated using a numerical integrator. NSphere employs adaptive leapfrog methods, automatically refining the time step for accuracy. For orbits with very low angular momentum approaching the center (r -> 0), where standard integration becomes stiff, a Levi-Civita coordinate transformation (ϱ = √(r)) and fictitious time (dτ = dt/r) are used to regularize the equations of motion and improved stability and accuracy.
This approach significantly reduces computational cost compared to traditional 𝑁² 𝑁-body methods and mitigates issues like two-body relaxation effects, making it suitable for high-precision studies of spherical systems on standard hardware.
For further details on the gravitational algorithm, see Kamionkowski & Sigurdson (2025a). For complete details of the SIDM implementation, see Kamionkowski, Sigurdson & Slone (2025). For the implementation and effects of anisotropic velocity distributions, see Kamionkowski & Sigurdson (2025b).
Key Capabilities
NSphere provides several advanced features for studying spherical dark matter systems:
Profile Support: Initial conditions can be generated for NFW (with power-law cutoff), Cored Plummer-like, or Hernquist density profiles. Each profile supports both isotropic and anisotropic velocity distributions.
Anisotropy Models: Velocity anisotropy can be configured using constant-β models (Hernquist only) or the Osipkov-Merritt model with radially-varying β(r) = r²/(r² + r_a²) (compatible with all profiles). Note that the --writeinit flag outputs initial conditions that, with external format conversion and augmentation by isotropic polar/azimuthal angles, may be used in other N-body codes.
SIDM Physics: Self-interacting dark matter scattering is implemented via direct Monte Carlo with configurable cross-section (σ/m). The parallel implementation uses graph-coloring to eliminate race conditions while maintaining high efficiency. SIDM simulations demonstrate core formation and eventual gravothermal collapse.
Restart & Extension: Interrupted simulations can be resumed with --sim-restart, or completed simulations extended with --sim-extend, and will be bit-for-bit identical to simulations run normally for the desired end time.
Reproducibility: Comprehensive seed management (--master-seed, --init-cond-seed, --sidm-seed, --load-seeds) enables exact reproduction of stochastic processes. All seeds are saved automatically for each run.
Getting Started
Run a basic simulation and generate plots:
./nsphere --nparticles 10000 --tfinal 5
./nsphere_plot
For SIDM physics with core formation:
./nsphere --nparticles 10000 --tfinal 20 --sidm --sidm-kappa 50
./nsphere_animations
See the Command-Line Usage section for all available options.
(For more technical details, see the sections below)