Data and Results Flow

The NSphere workflow typically involves simulation followed by analysis:

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.
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.