Installation

This guide explains how to set up CASPULE and compile LAMMPS 3 Mar 2020 with the custom bond/create/random fix used to define intersticker crosslinks, together with the Python tools used for data analysis.

  • Recommended setup using the automated installer script install_caspule_requirements.sh

Note

The bond/create/random fix is not part of vanilla LAMMPS 3 Mar 2020. CASPULE patches it in from the pdebuyl/lammps fbc_random branch.

Quick start (macOS + Linux)

The easiest way to install the CASPULE requirements is to download and run the installer script from the CASPULE GitHub repository.

Before running the script, install Conda if it is not already available on your machine. See the official Conda installation guide here: Installing Conda.

Then download and run the installer:

curl -O https://raw.githubusercontent.com/caspule/caspule/main/install_caspule_requirements.sh
bash install_caspule_requirements.sh

After the script finishes, the new Conda environment will be named caspule and the will be able to run examples from the CASPULE github.

What the installer does

The script performs the following steps automatically:

  1. Creates a new Conda environment named caspule

  2. Installs Packmol

  3. Installs Python 3.11 and the Python analysis packages used by CASPULE:

    • numpy

    • scipy

    • pandas

    • matplotlib

    • networkx

    • tqdm

    • numba

    • h5py

  4. Installs Moltemplate with pip

  5. Installs the Conda-forge build tools needed for LAMMPS on macOS:

    • cxx-compiler

    • cmake=3.31.6

    • openmpi

  6. Creates a local patch_files directory

  7. Downloads the patched files:

    • fix_bond_create_random.cpp

    • fix_bond_create_random.h

  8. Downloads and unpacks LAMMPS 3 Mar 2020

  9. Copies the patched files into src/MC/

  10. Configures and compiles LAMMPS with the required packages enabled:

    • MC

    • MOLECULE

    • USER-MISC

    • USER-COLVARS

  11. Verifies that the custom fix was compiled successfully by checking for bond/create/random in ./lmp -h

Requirements

The installer requires:

  • Conda to be installed and available on your $PATH

  • A standard shell environment with bash, curl, tar, and sysctl available

No additional manual downloads are required for the macOS script workflow.

Sanity check

At the end of the build, the installer checks that the new fix is available by running:

./lmp -h | grep bond/create/random

Expected output:

bond/create/random       Create bonds (random partner selection)  [MC]

Troubleshooting

  • “Conda: command not found” Install Conda first and make sure it is on your $PATH.

  • “Moltemplate not found” Confirm that pip install moltemplate completed successfully inside the CASPULE Conda environment.

  • “Package MC is not enabled” Re-run CMake with -DPKG_MC=on and rebuild.

  • “bond/create/random” not found in ``./lmp -h`` Confirm that the two patched files were copied into src/MC/ before the build and that LAMMPS was rebuilt afterward.

  • “New bond exceeded bonds per atom …” Raise extra bond per atom count in your .data file, and update extra/special/per/atom in the read_data section of your input script.