Trajectory analysis from scratch: MSD and diffusion

Problem

I chose trajectory analysis for 3D particle motion. The baseline computes the mean-squared displacement (MSD) as a function of lag time and estimates the diffusion coefficient from the linear MSD regime.

Given unwrapped trajectories (_p(t)) (particle index (p), frame index (t)), the MSD at lag () is

[ ()= _{p=0}{N-1}_{t_0=0}{T-} _p(t_0+)-_p(t_0)^2, ]

where (N) is number of particles and (T) is number of frames.

For ideal 3D Brownian motion, ((t)=6Dt), so if we fit ((t)a t+b) on a user-chosen interval, (D = a/6).

Units and assumptions

Why this is a good baseline for this course

How the baseline code works

File: code/msd_diffusion.cc (self-contained C++17, standard library only).

  1. Parse command-line parameters:
  2. Validate input:
  3. Generate synthetic unwrapped 3D Brownian trajectories:
  4. Compute time-origin/particle-averaged MSD for lags 1..max_lag:
  5. Fit MSD vs time in [fit_start, fit_end] by ordinary least squares:
  6. Write reproducible CSV:
  7. Print timing:

Numerical checks included

The program can run built-in checks (--run-checks 1, default):

  1. Stationary motion (r(t)=const): MSD should be zero.
  2. Constant velocity (r(t)=v t): MSD should equal (|v|^2(dt)^2).
  3. Brownian expectation: mean relative error vs (6Dt) over lags should be within a tolerance (finite-sample variability is expected).

These checks are deterministic (fixed seeds and fixed parameters).

Complexity

This intentionally plain serial implementation is useful as a baseline before parallel optimization.

Build and run

In this course notebook workflow:

Example cells (cd code first):

# compile cell
%%bash
cd code
module purge && module load nvidia/25.9 cuda/12.9 && PATH=/work/gt81/share/env/llvm/bin:$PATH
clang++ -O3 -Wall -std=c++17 msd_diffusion.cc -o msd_diffusion
# one-time initialization cell
%load_ext miyabi
# run cell (compute node)
%%sub
cd code
./msd_diffusion --particles 2000 --frames 2000 --max-lag 400 --dt 0.01 --diffusion 1.0 --seed 12345 --fit-start 50 --fit-end 200 --csv msd.csv --run-checks 1

For quick tests, reduce particles/frames/lags. For heavier serial runs, increase them but keep total runtime within assignment limits.

Verified run on Miyabi

The following numbers are from an actual notebook %%sub run on compute node mg1098 (lecture-mig, job 3750947) with:

Observed checks and outputs:

The estimated diffusion is statistically consistent with the Brownian target in this finite-sample run: D_est is close to D_true = 1, and MSD-vs-time remains near the expected linear trend.

Limitations

Where parallelism is

Major parallel opportunities:

  1. Across particles: MSD contributions are independent per particle.
  2. Across time origins for each lag: independent squared-displacement terms.
  3. Across lags: each lag can be computed independently.

Likely future mappings:

Potential speedup limits:


I should proofread and rewrite this in my own words before submission, because classmates will read it and I am responsible for the final text.