Collective dynamics of trail-interacting particles

Collective Dynamics of Trail-Interacting Particles This repository accompanies the paper on the collective dynamics of trail-interacting particles. It contains the simulation code (Julia), analytical derivations (Mathematica), and plotting notebooks (Python/Jupyter) needed to reproduce the results. Repository Structure /├── Julia_DRWs/ # 1D simulations│ ├── DRWsEngine.jl # Core engine: data structures, Gillespie stepper│ ├── Trajectories.jl # Mid-level routines: observables, I/O│ ├── Launching_functions.jl # High-level launchers (steady states, DSF, …)│ └── Launching_file.jl # Entry point — edit parameters and run this│├── 2d_Julia_DRWs/ # 2D simulations (L×L periodic grid)│ ├── 2d_DRWsEngine.jl # Core engine for the 2D model│ ├── 2d_Trajectories.jl # Mid-level routines for 2D│ ├── 2d_Launching_functions.jl # High-level launchers for 2D│ ├── 2d_Launching_file.jl # Entry point for 2D│ └── Launch.sh # SLURM batch script (HPC cluster)│├── Collective_dynamics_of_trail_interacting_particles.nb # Mathematica notebook for the caclulations done in the paper└── Notebook_plots_article.ipynb # Python notebook — figures for the paper Physical Model Particles perform continuous-time random walks on a periodic 1D chain (or 2D square lattice) of $N$ sites. Each particle leaves a *trail* (local time / deposition count $\phi_i$) that biases the jump rates of all particles. The jump rate from site $i$ to a neighbouring site $j$ is: $$r(i \to j) = 2 \, k_\text{tr} \, \frac{w(j)}{w(i) + w(j)}, \qquad w(n) = e^{-h \, n}$$ where $n$ is the local trail depth and $h$ is the **interaction strength**: | Sign of $h$ | Interpretation | BE CAREFUL, THE SIGN OF $h$ IS THE OPPOSITE IN THE MAIN TEXT.|-------------|----------------|| $h < 0$ | Repulsive trails — particles avoid previously visited sites || $h > 0$ | Attractive trails — particles are drawn to previously visited sites | > **Note:** the sign convention of $h$ in the code is the **opposite** of the one used in the paper. Set `h = -0.1` in the code to match $h = +0.1$ in the paper. In addition to hopping, each particle deposits at rate $k_d$, incrementing $\phi_i$ by 1. Events are selected with a Gillespie (continuous-time Monte Carlo) algorithm accelerated by a waypoint / row-waypoint data structure that reduces the event-selection cost to $O(\sqrt{N_\text{sites}})$ per step. Prerequisites ### Julia (≥ 1.9) Install the required packages once: ```juliausing PkgPkg.add(["Random", "FFTW", "LinearAlgebra", "CSV", "DataFrames", "NPZ", "BenchmarkTools", "ThreadsX", "Dates", "Printf"])``` ### Python (for the plotting notebook) ```bashpip install numpy matplotlib scipy pandas jupyter``` Quick Start 1D simulations Open `Julia_DRWs/Launching_file.jl`, adjust the parameters at the top: ```juliaNsites = 256 # Number of lattice sitesh = -0.1 # Interaction strength (h < 0 ↔ repulsive; note sign convention above)ktr = 1.0 # Hopping ratekd = 1.0 # Deposition raterho0 = 1.0 # Mean particle densityNsims = 100 # Number of independent realisations``` Then run from the terminal: ```bashjulia Julia_DRWs/Launching_file.jl``` Uncomment the desired launcher call to choose the workflow. 2D simulations Same workflow with `2d_Julia_DRWs/2d_Launching_file.jl`. The grid size is controlled by parameter `L` (total sites = $L^2$). ```bashjulia 2d_Julia_DRWs/2d_Launching_file.jl``` ### HPC cluster (SLURM) `2d_Julia_DRWs/Launch.sh` is a ready-made SLURM array job script. Adjust the partition and memory settings to match your cluster, then submit with: ```bashsbatch 2d_Julia_DRWs/Launch.sh``` --- ## Available Workflows | Function | Description ||---|---|| `Generate_Steady_State_h_negative` | Run until the repulsive ($h<0$) steady state is reached and save density + local time || `Launch_GeneratePermanentState_h_positive` | Find the permanent (frozen) state for attractive trails ($h>0$) || `Launch_DSF` | Compute the **dynamic structure factor** $S(q,\omega)$ from previously saved steady-state snapshots || `Launch_Snapped_SF` | Record the structure factor $S(q)$ at regular step intervals (time-resolved) || `Launch_Snapped_SF_Poisson` | Same as above but starting from a Poisson-distributed initial condition || `make_trajectories_from_given_density` | Generate full particle trajectories for visualisation / videos | All output data are saved automatically in organised subdirectories under the folder from which the script is run, following the naming convention: ``` / /From /h= /ktr= _kd= /rho= _Nsites= _nsim= /``` --- ## Output Format Results are written as CSV files (via `CSV.jl` / `DataFrames.jl`) and `.npy` arrays (via `NPZ.jl`): | File | Content ||---|---|| `density.csv` | Particle density field $\rho_i$ for each simulation || `local_time.csv` | Trail field $\phi_i$ for each simulation || `time.csv` | Physical time reached at the end of each run || `Sqw.csv` | Dynamic structure factor $S(q,\omega)$ || `SF_rho.csv` / `SF_phi.csv` | Static structure factors of $\rho$ and $\phi$ | Mathematica Notebook Wolfram Mathematica ≥ 14 is required to open and evaluate the `.nb` file. `Collective_dynamics_of_trail_interacting_particles.nb` derives analytical results presented in the paper, including: - The Green function of the linearised hydrodynamic equation - The density and trail structure factor $S(q)$ - The scaling solution in 2d Plotting Notebook `Notebook_plots_article.ipynb` loads the simulation data and reproduces the figures in the paper. Citation If you use this code, please cite: > *Collective Dynamics of Trail-Interacting Particles*, (authors), (journal), (year). DOI: ... License This project is released under the Creative Commons Attribution 4.0 International License