.. NSphere documentation master file, created by
   sphinx-quickstart on <date>.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

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) <https://arxiv.org/abs/2504.13996>`_. For complete details of the SIDM implementation, see `Kamionkowski, Sigurdson & Slone (2025) <https://arxiv.org/abs/2506.04334>`_. For the implementation and effects of anisotropic velocity distributions, see `Kamionkowski & Sigurdson (2025b) <https://arxiv.org/abs/PLACEHOLDER>`_.

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:

.. code-block:: bash

   ./nsphere --nparticles 10000 --tfinal 5
   ./nsphere_plot

For SIDM physics with core formation:

.. code-block:: bash

   ./nsphere --nparticles 10000 --tfinal 20 --sidm --sidm-kappa 50
   ./nsphere_animations

See the :doc:`command_line/index` section for all available options.

*(For more technical details, see the sections below)*

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   command_line/index
   data_flow/index
   c_api/index
   python_api/index
   examples/index

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`