Free chiral Hexbugs compared to active Brownian circle swimmers (data)

# Hexbugs_as_ABC_Project

Reproducible analysis and figure generation for HexBug experiments/simulations:

- ISF 3‑panel plots per dataset

- Dual MSD plot (FreeHexbug + MDF2)

- Propagator 2×2 panel (short/long lags)

- Optional: run native C++ simulator via GNU screen

- Precomputed standard deviations for MSD/ISF are included to save time

Quickstart

----------

```bash

# 1) Environment

conda create -n hexbugs python=3.10 -y

conda activate hexbugs

pip install numpy scipy matplotlib lmfit

# 2) System deps (Ubuntu)

sudo apt-get install -y g++ screen texlive-latex-base dvipng

# 3) Set project root (recommended)

export HEXBUGS_PROJECT_DIR=/absolute/path/to/Hexbugs_as_ABC_Project

# 4) Put raw .mat files into:

# data/mdf2/trajectories/RawData/

# data/FreeHexbug/trajectories/RawData/

# 5) Run the pipeline

python PythonScripts/1_io.py

python PythonScripts/2_process_trajectories.py

python PythonScripts/3_MSD.py

python PythonScripts/4_ISF.py

python PythonScripts/5_plots.py

```

Project layout

--------------

```

Hexbugs_as_ABC_Project/

├─ C++/

│ ├─ build/ # compile.sh (build + run via screen)

│ ├─ hexbugs

│ ├─ include

│ └─ src

├─ data/

│ ├─ FreeHexbug/

│ │ └─ trajectories/RawData/ # put nocubes14.mat here

│ ├─ inertia/

│ └─ mdf2/

│ └─ trajectories/RawData/ # put tr_cm_*.mat here

├─ imgs/

│ ├─ FreeHexbug/

│ ├─ inertia/

│ └─ mdf2/

└─ PythonScripts/

├─ 1_io.py

├─ 2_process_trajectories.py # can build & launch C++ via screen

├─ 3_MSD.py

├─ 4_ISF.py

└─ 5_plots.py # main paper figures

```

Requirements

------------

- Python ≥ 3.9 (tested with 3.10)

- Python packages:

- numpy, scipy, matplotlib, lmfit

- Optional (for paper-quality fonts in figures):

- LaTeX: texlive-latex-base, dvipng (or set text.usetex=False in the scripts)

- Optional (for C++ simulator):

- g++ (C++17), GNU screen

Configuration

-------------

- Path resolution:

- If $HEXBUGS_PROJECT_DIR is set, scripts use it.

- Otherwise they resolve the project folder relative to their file location.

- Set it explicitly (recommended):

```bash

export HEXBUGS_PROJECT_DIR=/absolute/path/to/Hexbugs_as_ABC_Project

```

Data input

----------

- MDF2 raw .mat files → data/mdf2/trajectories/RawData/

- FreeHexbug raw .mat → data/FreeHexbug/trajectories/RawData/

- 1_io.py creates missing folders and converts .mat → .dat trajectories.

Expected formats used later

- msd_isf_*.dat (tab-delimited with header): lag col 0, MSD col 1, ISF cols 5..19, counter in last col

- STD_deviation_python*.dat (CSV header): lag, msd, msd_std, count

- STD_deviation_ISF_python*.dat (CSV header): q, lag, ISF, ISF_std, count

Precomputed standard deviations (included)

------------------------------------------

- To save time, precomputed standard deviation files are shipped with the repository:

- MSD std: data/*/STD_deviation_python*.dat

- ISF std: data/*/STD_deviation_ISF_python*.dat

- You can delete these files to force recomputation (3_MSD.py for MSD std, 4_ISF.py for ISF std). Be aware: recomputation can take a long time.

How to run (VS Code and terminal)

---------------------------------

VS Code:

- Open the repo, select conda env (Python 3.10), click Run (“Play”) in order:

1) 1_io.py

2) 2_process_trajectories.py

3) 3_MSD.py

4) 4_ISF.py

5) 5_plots.py

Terminal (same order):

```bash

python PythonScripts/1_io.py

python PythonScripts/2_process_trajectories.py

python PythonScripts/3_MSD.py

python PythonScripts/4_ISF.py

python PythonScripts/5_plots.py

```

What each script does

---------------------

- 1_io.py

- Ensures folder structure under data/*/trajectories[/RawData]

- Converts MDF2 and FreeHexbug .mat → per‑trajectory .dat files

- 2_process_trajectories.py

- Loads .dat trajectories, crops/filters, combines

- Produces:

- data/FreeHexbug/FreeHexbug_cropped_combined_filtered.dat

- data/FreeHexbug/FreeHexbug_cropped_distinct.dat

- data/mdf2/MDF2_cropped_combined_filtered.dat

- data/mdf2/MDF2_cropped_distinct.dat

- Optionally compiles and launches the C++ simulator via C++/build/compile.sh

- 3_MSD.py

- Computes MSD std if missing from trajectories (skips if STD_deviation_python*.dat exists)

- Fits the MSD model; writes fit reports to:

- data/FreeHexbug/msd_fit_report_FreeHexbug.txt

- data/mdf2/msd_fit_report_mdf2.txt

- 4_ISF.py

- Computes ISF std if missing (skips if STD_deviation_ISF_python*.dat exists); fits ISF across k-values

- Saves per‑k diagnostics to imgs/isf_fitting_helper/

- Writes fit reports:

- data/FreeHexbug/isf_fit_report_FreeHexbug.txt

- data/mdf2/isf_fit_report_mdf2.txt

- 5_plots.py

- Builds final figures:

- imgs/FreeHexbug/ISF/ISF_isffit_msdfit_exp.pdf

- imgs/mdf2/ISF/ISF_isffit_msdfit_exp.pdf

- imgs/MSD_dual_plot.pdf

- imgs/propagator_2x2.pdf

- imgs/inertia/propagator_inertia.pdf

- Caches analytic ISF curves under data/<dataset>/isf_data/ on first run

C++ simulator details (optional)

--------------------------------

Build and run via script (recommended):

```bash

cd C++/build

chmod +x compile.sh

./compile.sh

```

- Starts a screen session hexbugs_session with multiple parallel runs (num_screens in compile.sh).

- Each tab runs: ./hexbugs <RANK> <SIZE>

Screen basics:

- attach: screen -r hexbugs_session

- next tab: Ctrl+a, n | previous: Ctrl+a, p | detach: Ctrl+a, d | quit: screen -S hexbugs_session -X quit

Manual build/run:

```bash

g++ -I C++/include C++/src/hexbugs.cpp C++/src/nrutil.cpp C++/src/random_mars.cpp -o C++/build/hexbugs -O2 -w

C++/build/hexbugs 0 9 # RANK SIZE

```

Inputs (hexbugs.cpp → filepaths)

- data/FreeHexbug/FreeHexbug_cropped_distinct.dat

- data/mdf2/MDF2_cropped_distinct.dat

- data/FreeHexbug/FreeHexbug_cropped_combined_filtered.dat

- data/mdf2/MDF2_cropped_combined_filtered.dat

- data/Simulation_data/Noise/combined/{1..4}.dat, Data.dat

Input formats

- RANK 0/1 (distinct): “x y t trajnum”

- RANK 2/3 (combined filtered): “x y t”

- RANK 4–8 (sim): “t x y”

- Missing frames handled by ceil(t) + NaN gaps to keep integer time steps.

Outputs

- msd_isf_<basename>.dat with header:

- lag, msd, mqd, ngp, skewness,

- isfx[<L1..L15>], isfy[<L1..L15>], isfr[<L1..L15>],

- isfx_im[<L1..L15>], isfy_im[<L1..L15>], isfr_im[<L1..L15>],

- counter

Notes

- In modify_filepath (RANK 4–8) some absolute paths are hardcoded (e.g., /home/tom/...). Adjust if needed.

- <bits/stdc++.h> is GCC‑specific; on non‑GCC compilers include headers individually.

- N = 10,000,000 is predefined → high RAM use; reduce if needed.

Troubleshooting

---------------

- Matplotlib LaTeX errors: install texlive-latex-base + dvipng, or in the scripts:

```python

import matplotlib as mpl

mpl.rcParams.update({'text.usetex': False})

```

- Path issues: verify $HEXBUGS_PROJECT_DIR and the folder structure.

- First run is slow: analytic ISF curves are generated and cached; re‑runs are faster.

- Recompute stds: delete data/*/STD_deviation_python*.dat and/or data/*/STD_deviation_ISF_python*.dat to recompute (time‑consuming).

- Array alignment: ensure masks are created on the correct lag axis (handled in the scripts).

Reproducibility

---------------

- Freeze current environment:

```bash

pip freeze > requirements.txt

```

- Reproduce:

```bash

pip install -r requirements.txt

```

- Or with conda:

```bash

conda env export > environment.yml

conda env create -f environment.yml

```

Citation

--------

Code for the theoretical intermediate scattering function is taken from:

- Rusch, R. (2024). Intermediate scattering function of a gravitactic circle swimmer. Universität Innsbruck. https://doi.org/10.48323/pykgf-vhf05

If you use this repository, please also cite the associated manuscript.