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

<current_directory>/
├── 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:

```julia
using Pkg
Pkg.add(["Random", "FFTW", "LinearAlgebra",
         "CSV", "DataFrames", "NPZ",
         "BenchmarkTools", "ThreadsX",
         "Dates", "Printf"])
```

### Python (for the plotting notebook)

```bash
pip install numpy matplotlib scipy pandas jupyter
```

Quick Start

1D simulations

Open `Julia_DRWs/Launching_file.jl`, adjust the parameters at the top:

```julia
Nsites = 256    # Number of lattice sites
h      = -0.1  # Interaction strength (h < 0 ↔ repulsive; note sign convention above)
ktr    = 1.0   # Hopping rate
kd     = 1.0   # Deposition rate
rho0   = 1.0   # Mean particle density
Nsims  = 100   # Number of independent realisations
```

Then run from the terminal:

```bash
julia 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$).

```bash
julia 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:

```bash
sbatch 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:

```
<Observable>/<sign_h>/From<InitialCondition>/h=<h>/ktr=<ktr>_kd=<kd>/rho=<rho>_Nsites=<N>_nsim=<Nsims>/
```

---

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