DNA Loop Extrusion by SMCCs in LAMMPS

Loop extrusion simulation

Installation

Below are instructions to install the smc-lammps python package and a separate LAMMPS executable used to perform simulations.

Python

From PyPI

The code is available as a package on PyPI.

pip install smc-lammps

From Source Using uv (recommended)

git clone https://github.com/LucasDooms/SMC_LAMMPS.git
cd SMC_LAMMPS
uv sync --no-dev
# alternatively, to include optional dependencies
uv sync --all-groups
source .venv/bin/activate

or use uv run <command> without activating the environment.

From Source Using pip

git clone https://github.com/LucasDooms/SMC_LAMMPS.git
cd SMC_LAMMPS
python3 -m venv .venv
source .venv/bin/activate
# get exact versions (recommended)
pip install -r requirements.txt
# or, install from pyproject.toml file
pip install -e .

LAMMPS

You will need a LAMMPS executable with the MOLECULE, EXTRA-MOLECULE, and RIGID packages.
See https://docs.lammps.org/Install.html for more information.

Simple example:

git clone https://github.com/lammps/lammps --depth=1000 mylammps
cd mylammps
git checkout stable # or release for a more recent version
mkdir build && cd build
cmake -D CMAKE_INSTALL_PREFIX="$HOME/lammps" -D PKG_MOLECULE=yes -D PKG_EXTRA-MOLECULE=yes -D PKG_RIGID=yes ../cmake
cmake --build . -j8
make
make install
export PATH="$HOME/lammps/bin:$PATH"

(Optional) VMD

To use the src/smc_lammps/post_process/visualize.py script, you will need VMD,
see https://www.ks.uiuc.edu/Development/Download/download.cgi?PackageName=VMD.

Docker Installation

Alternative: install smc-lammps and LAMMPS in a docker container

You can also use docker to run the code.

Either download the image using

docker pull ghcr.io/lucasdooms/smc-lammps:latest

or build it locally with docker build -t smc-lammps . (replacing ghcr.io/lucasdooms/smc-lammps with smc-lammps for the instructions below).

Now you can run an interactive session using

docker run -it -v .:/data ghcr.io/lucasdooms/smc-lammps

Or, to run directly (see Usage)

docker run -v .:/data ghcr.io/lucasdooms/smc-lammps smc-lammps ...

To run a jupyter notebook session, use

docker run -it -v .:/data -p 127.0.0.1:8888:8888 ghcr.io/lucasdooms/smc-lammps jupyter notebook --allow-root --no-browser --ServerApp.ip=0.0.0.0 /data

and open the displayed link http://127.0.0.1:8888/tree?token=... in your browser.

Note: the docker image does not include VMD.

Usage

1. Create a directory for your simulation using smc-lammps mysim.
2. Define all parameters in mysim/parameters.py (see src/smc_lammps/generate/default_parameters.py for all options).
3. Run smc-lammps [flags] mysim, providing the directory of the parameters file. Use the -g flag to generate the required parameterfile and datafile.

Examples

• smc-lammps mysim -gr to generate and run.
• smc-lammps mysim -grpv to generate, run, post-process, and visualize.
• smc-lammps mysim -grvn to generate, run, and visualize while ignoring errors.
• smc-lammps mysim -v to visualize.
• smc-lammps mysim -vf to visualize a perspective following the SMC.
• smc-lammps mysim -c to continue a run from a restart file.

Help

Show help with smc-lammps --help.

Shell Completion

To get shell completion when using smc-lammps on the command-line run the following:

• For bash or zsh, use eval "$(register-python-argcomplete smc-lammps)"
• For fish, use register-python-argcomplete --shell fish smc-lammps | source

Development

Enable dev dependencies

uv sync --dev

Tests

Run all tests using

pytest

Documentation

Dependencies

To build the documentation, you will need to install graphviz, e.g. sudo apt update && sudo apt install graphviz on Debian/Ubuntu.

Build

Build the documentation using

make -C docs html

(or sphinx-build -b html docs/source docs/build/html)

Now open docs/build/html/index.html in a browser or use python -m http.server -d docs/build/html and browse to http://localhost:8000.

Autobuild

To view new changes made to the documentation automatically, you can use sphinx-autobuild

sphinx-autobuild -b html --watch src/smc_lammps docs/source docs/build/html

Doctests

Run the doctests using

make -C docs doctest

Authors

Original code by Stefanos Nomidis (https://github.com/sknomidis/SMC_LAMMPS).
Modifications by Arwin Goossens.
All commits in this repository by Lucas Dooms.
Released under MIT license.