Data and Results Flow
=====================

The NSphere workflow typically involves simulation followed by analysis:

1.  **Simulation (``./nsphere``):** The C executable, ``./nsphere``, handles the core physics simulation. It takes command-line arguments or reads configuration to set up parameters like particle count, simulation time, and physics models. It may read initial particle configurations from the ``init/`` directory (if present and configured). During execution, it calculates particle trajectories under self-gravity and any additional physics, outputting results primarily to the ``data/`` directory (created in the current working directory if it doesn't exist). This output includes time-series data, particle snapshots at specified intervals (``Rank_Mass_Rad_VRad*.dat``), and potentially theoretically calculated profiles (``massprofile*.dat``, etc.). A ``lastparams*.dat`` file is often written to record key parameters of the run. When SIDM is enabled, seed files (``last_initial_seed*.dat``, ``last_sidm_seed*.dat``) are saved for reproducibility.

2.  **Visualization/Analysis (``./nsphere_plot`` and wrappers):** The Python executable, ``./nsphere_plot``, along with its convenience wrappers, processes the files generated by the simulation, expecting them in the ``data/`` directory relative to the current working directory. It typically uses a ``--suffix`` argument to identify the specific simulation run's data files. Based on command-line flags, these scripts read the relevant data, perform analysis, and use the Matplotlib library to generate various outputs (plots as ``.png`` files, animations as ``.gif`` files) which are saved to the ``results/`` directory (also created in the current working directory if needed).

Output File Reference
=====================

NSphere produces multiple binary output files. Understanding their structure is useful for custom analysis beyond the provided Python tools.

**Primary Evolution Data** (``data/`` directory):

  **all_particle_data<suffix>.dat**: Complete particle state at each write interval (every dtwrite timesteps). Stores 16 bytes per particle per snapshot: rank (int32, 4 bytes), R (float32, 4 bytes), Vrad (float32, 4 bytes), L (float32, 4 bytes). Data is written in step-major order, meaning all particles for snapshot 0 are contiguous, followed by all particles for snapshot 1, and so on. This is the primary file for restart/extend operations and detailed post-processing. Total file size is npts × 16 × num_snapshots bytes.

  **all_particle_phi<suffix>.dat**: Azimuthal angle φ for perpendicular velocity orientation. Stores 4 bytes (float32) per particle per snapshot, written in step-major order. Used with all_particle_data for complete 3D velocity reconstruction, particularly important for SIDM simulations where φ tracks orientation changes due to scattering.

  **all_particle_ids<suffix>.dat**: Original particle IDs for tracking through sorting operations. Stores 4 bytes (int32) per particle per snapshot. Enables identification of specific particles across snapshots despite radius-based sorting rearranging array positions.

  **all_particle_scatter_counts<suffix>.dat**: SIDM scatter event counts (created only when ``--sidm`` is enabled). Stores cumulative scatter count as 4 bytes (int32) per particle per snapshot, tracking how many times each particle has scattered.

**Trajectory Tracking** (``data/`` directory):

  **trajectories<suffix>.dat**: Time-series data for multiple particles (default: first 10 by original ID). Each timestep record contains time (float32, 4 bytes) followed by R, Vrad, mu for each tracked particle (3 float32 values, 12 bytes per particle). Record size is 4 + N×12 bytes where N is the number of tracked particles.

  **single_trajectory<suffix>.dat**: Similar to trajectories but tracks only the first particle. Each timestep is 16 bytes: time, R, Vrad, mu (all float32).

  **lowest_l_trajectories<suffix>.dat** or **chosen_l_trajectories<suffix>.dat**: Tracks particles with lowest angular momentum, or if ``--lvals-target`` is specified, those closest to the target value. Stores time (4 bytes) plus R, E, L for each particle (12 bytes each) per timestep. Filename depends on selection mode.

  **energy_and_angular_momentum_vs_time<suffix>.dat**: Evolution of E and L for tracked particles. Each timestep stores time followed by E, E_initial, L, L_initial for each tracked particle (float32 format).

**Snapshot Data Products** (``data/`` directory, generated during post-processing):

  **Rank_Mass_Rad_VRad_sorted_t<snap><suffix>.dat**: Detailed particle data sorted by radius at major snapshot times (controlled by ``--nout``). Each particle entry contains 8 fields totaling 32 bytes: rank (int32), mass_enclosed (float32), R (float32), Vrad (float32), PsiA (float32), E (float32), L (float32), density (float32). The E field contains epsilon (ε = Ψ - KE), not total energy. Separate file created for each snapshot number (t00000, t00001, etc.).

  **Rank_Mass_Rad_VRad_unsorted_t<snap><suffix>.dat**: Similar to sorted version but in original particle ID order. Contains 7 fields (28 bytes per particle, no density field).

**Auxiliary and Configuration Files**:

  **chosen_particles<suffix>.dat**: Records which particles are tracked in trajectory files. File format is 8-byte header (nlowest and n_traj as int32) followed by particle ID arrays (4 bytes per ID). Essential for maintaining consistent tracking across restart/extend operations.

  **double_buffer_all_particle_data<suffix>.dat** and **double_buffer_all_particle_phi<suffix>.dat**: Maintain last 4 snapshots in full double precision (avoiding float32 conversion). Used automatically during restart/extend to prevent precision loss. Data file stores rank (int32) + R, Vrad, L (all double, 8 bytes each) = 28 bytes per particle. Phi file stores 8 bytes (double) per particle. These files enable bit-for-bit restart accuracy.

  **lastparams<suffix>.dat** and **lastparams.dat**: Records run parameters in single-line format: npts, Ntimes, tfinal_factor, optional_tag. The unsuffixed version (``lastparams.dat``) is a symlink (Unix) or copy (Windows) pointing to the most recent suffixed version, allowing plotting scripts to automatically find the last run's parameters.

  **last_initial_seed<suffix>.dat** and **last_sidm_seed<suffix>.dat**: Random number generator seeds (unsigned long integer, one per file). Saved automatically after each run. Can be loaded with ``--load-seeds`` to reproduce stochastic processes exactly. For parallel SIDM, per-thread generators are seeded deterministically from the base SIDM seed.

**Theoretical Profile Files** (``data/`` directory):

Files like ``massprofile<suffix>.dat``, ``Psiprofile<suffix>.dat``, ``density_profile*.dat``, ``f_of_E*.dat``, and ``df_fixed_radius.dat`` contain theoretical calculations from the initial conditions setup. These are formatted via fprintf_bin (binary float32 values) and typically contain 2-3 columns per line. Diagnostic versions with varied numerical parameters (e.g., ``massprofile_Ni1000_Ns1000.dat``) may also be created when debugging is enabled.