Chromatin_MSM

Python package combining sampling of chromatin structures and recording features:

• Chromatin_MSM.adaptive — adaptive MSM sampling pipeline
• Chromatin_MSM.feature_writer — PLUMED collective-variable feature generator

The MSM construction, validation and analysis can be found in MSM_analysis/MSM_FMRC.ipynb

Installation

git clone https://github.com/CollepardoLab/Chromatin_MSM.git
cd Chromatin_MSM
pip install -e .

Required packages

Core dependencies (install via pip/conda): numpy, pandas, matplotlib, scipy, networkx, mdtraj

Versioned dependencies:

• python (3.9+)
• openmm (8.1.2)
• plumed (2.9.2 / py-plumed 2.9.2)
• pytorch (2.7.1 with CUDA 12.6 support)
• deeptime

Manual installation required:

• OpenCGChromatin

External algorithm:

• FMRC (original implementation)

Usage

# Generate PLUMED CV definitions 
nucleosome-feature-writer --pdb ref/15/15rep.pdb --linker-length 15

# Run the adaptive MSM sampling pipeline
nucleosome-adaptive-sampling --n-rounds 8 --n-seed-per-round 16 --linker-length 15

# PolyA / polyAT linker systems use the ref/<L>_A and ref/<L>_AT references
nucleosome-feature-writer --pdb ref/25_AT/25rep.pdb --linker-length 25
nucleosome-adaptive-sampling --linker-length 25 --linker-seq polyAT

--linker-seq selects the linker DNA used to build new seed simulations: ACTG (default, ACTGACTG...), polyA (AAAA...) or polyAT (ATAT...). It also selects the reference directory: ref/<L>/, ref/<L>_A/ or ref/<L>_AT/. The feature writer takes the RMSD references (DNA.pdb, core_all.pdb) from the same directory as --pdb (override with --ref-dir); these paths are resolved relative to where PLUMED runs, so run the writer from the run directory.

Before running nucleosome-adaptive-sampling

adaptive.py reads several inputs as paths relative to the current working directory, and does not create or fetch them for you. Before invoking the CLI, the run directory must contain:

Path	Required content
./traj_dat/*.xtc	Original seed trajectories (320 by default, see --n-original-sims in the code / n_original_sims)
./ref/<linker-length>[_A|_AT]/<linker-length>rep.pdb	Reference topology. Default derived from --linker-length and --linker-seq (e.g. --linker-length 15 -> ref/15/15rep.pdb, --linker-length 25 --linker-seq polyAT -> ref/25_AT/25rep.pdb); override with --topology-file if your structure lives elsewhere
./ref/<linker-length>[_A|_AT]/DNA.pdb, core_all.pdb	RMSD references read by PLUMED for the rmsd feature
./mdp_features.dat	PLUMED CV definitions, generated with nucleosome-feature-writer (defaults to mdp_features.dat, matching what adaptive.py expects; override with --output on the writer and --feature-file on adaptive.py if you want a different name/path)

See scripts/new.sh for an example SLURM submission script for the adaptive-sampling pipeline on a GPU cluster, which uses CUDA Multi-Process Service (MPS) to share each GPU between several simulations, following OPIG blog post.

Detailed docs

• docs/adaptive.md — adaptive MSM sampling pipeline
• docs/feature_writer.md — PLUMED feature generator
• docs/reference_structures.md - reference structure generation method

Layout

Chromatin_MSM/
├── pyproject.toml
├── docs/
│   ├── adaptive.md              # adaptive sampling docs
│   ├── feature_writer.md        # feature generation docs
│   └── reference_structures.md  # reference structure generation docs
├── scripts/
│   ├── new.sh                   # SLURM submission script
│   └── setup_adaptive_run.sh    # stage ref/mdp_features.dat/traj_dat for a run dir
├── src/Chromatin_MSM/
│   ├── __init__.py
│   ├── adaptive.py               # adaptive MSM sampling pipeline
│   └── feature_writer.py         # PLUMED feature generator
├── ref/                          # reference structures, by linker length (bp) and DNA seqs
│   ├── 15/15rep.pdb, core1-4.pdb, DNA.pdb, htail*_A-D.pdb, ...
│   ├── 20/ ... 22/ ... 25/ ... 25_A/ ... 25_AT/ ... 26/ ... 27/ ...
│   └── 28/ ... 29/ ... 30/ ... 30_A/ ... 30_AT/ ... 58/ ...  (_A = polyA, _AT = polyAT linkers)
└── MSM_analysis/                 # MSM construction, validation and analysis notebooks
    └── MSM_FMRC.ipynb

Citation

Please cite: Chen, Y., Huertas, J., Maristany, M.J., Russell, K., Zhang, M., Farr, S.E., Espinosa, J.R., and Collepardo-Guevara, R. (2026). A Spectrum of Free Energy Landscape Topologies Encodes Chromatin Polymorphism and Phase Separation. bioRxiv. https://doi.org/10.64898/2026.06.19.733383