Installation

PIMMS is distributed from GitHub and installed with pip (or uv). Because the performance-critical parts of PIMMS are written in Cython, installing PIMMS compiles native C extensions on your machine - this happens automatically, but it means you need a working C compiler and the build dependencies described below.

Note

PIMMS was recently added to PyPI (1.0.x release); let us know if you have any issues.

Requirements

  • Python ≥ 3.8 (3.10+ recommended; the development/test environment is 3.12).

  • A C compiler (clang on macOS, gcc on Linux).

  • The build/runtime Python packages: numpy, scipy, cython, versioningit and mdtraj (the last provides the XTC trajectory backend).

We strongly recommend installing into a clean, dedicated environment.

# with conda
conda create -n pimms python=3.12 -y
conda activate pimms

# ...or with uv
uv venv --python 3.12
source .venv/bin/activate

Step 1 - install the dependencies

pip install numpy scipy cython versioningit
pip install mdtraj

(With uv, use uv pip install ... instead of pip install ....)

Step 2 - install PIMMS

Install from PyPI:

pip install idptools-pimms

Install directly from GitHub:

pip install --no-build-isolation git+https://github.com/holehouse-lab/PIMMS.git

Note

The --no-build-isolation flag is optional. PIMMS’ pyproject.toml declares its build dependencies (Cython, NumPy, versioningit), so pip’s default isolated build already has what it needs. Passing --no-build-isolation simply tells pip to build against the packages you installed in Step 1 rather than fetching them again into a throwaway build environment - slightly faster, and the reason Step 1 installs the build tools up front.

Or clone and install from source (recommended if you intend to develop PIMMS):

git clone https://github.com/holehouse-lab/PIMMS.git
cd PIMMS
pip install -e . --upgrade --force-reinstall          # editable install
# ...or, with uv:
uv pip install -e . --no-deps --reinstall

Do I need to run build.sh?

No - not for a normal install. PIMMS’ setup.py declares all of its Cython modules as ext_modules via cythonize(...), so pip install (whether from the GitHub URL or from source) compiles every extension automatically. There is nothing extra to run.

build.sh is a developer convenience for rebuilding after you edit a .pyx file. Cython skips regenerating a .c file that is newer than its .pyx and build_ext reuses cached object files, so a plain reinstall may not pick up .pyx edits. build.sh forces a clean rebuild by deleting the generated C (pimms/*.c), the compiled extensions (pimms/*.so) and the build/ cache, then reinstalling:

./build.sh        # clean rebuild + editable reinstall (development only)

The compiled modules include the serial and parallel move kernels (mega_crank, mega_crank_2D and mega_crank_fast - the last holding the multi-threaded crankshaft, slither and pull kernels), the energy inner loops (inner_loops, inner_loops_hardwall) and several utilities. On macOS the multi-threaded kernels use OpenMP via Homebrew libomp if present, and degrade gracefully (single-threaded) if not.

Verifying the installation

Open a new terminal, activate the environment, and check the CLI:

PIMMS --version          # prints the installed version
PIMMS --info             # lists every keyfile keyword, grouped
PIMMS --info DIMENSIONS  # full details on one keyword

Note

The very first PIMMS invocation may take 5-10 seconds while Python initialises; subsequent calls are fast.

You can also confirm the package imports from Python:

python -c "import pimms; print(pimms.__version__)"

Finally, run a bundled demo. Each directory under demo_keyfiles/ contains a KEYFILE.kf (simulation configuration) and a params.prm (force field):

cd demo_keyfiles/single_chain_polymer
PIMMS -k KEYFILE.kf

This writes ENERGY.dat, a START.pdb/traj.xtc trajectory, and the requested analysis files into the working directory (see Output files).

Running the tests

PIMMS ships with an extensive test suite. From a source checkout:

pytest -m "not slow" pimms/tests/      # fast suite
pytest pimms/tests/                    # full suite (incl. slow detailed-balance tests)
pytest --cov=pimms pimms/tests/        # with coverage

The slow marker (defined in pyproject.toml) tags the heavier detailed-balance tests; deselect them with -m "not slow" for quick iteration. A clean run of the full suite is the strongest confirmation that the Cython extensions built correctly and PIMMS is behaving as expected.