Installation#

Prerequisites#

What you need in place before installing cemd:

  • Python 3.11 or later — required.

  • Conda — recommended for creating the environment (Miniconda or Anaconda), though a plain venv works too.

  • VMD — optional, and only for view(), which opens the system in VMD (download). It must be on your $PATH. The graphical interface renders with PyVista and needs no VMD.

Packmol does not need installing: it is a dependency of cemd, and pip puts its binary in your environment alongside the Python packages. Install it yourself, and put it on your $PATH, only if no wheel matches your platform.

User Installation#

It is strongly recommended to install cemd in a dedicated virtual environment.

Create a virtual environment#

cemd pulls in pymatgen, MDAnalysis and RDKit, each of which pins versions of its own. Installing it beside unrelated work asks pip to satisfy every project’s constraints at once, which is where incompatibilities appear. A dedicated environment avoids the question entirely.

Option 1: Using conda (recommended)

conda create -n cemd python=3.11
conda activate cemd

Option 2: Using venv (Python built-in)

python -m venv cemd
source cemd/bin/activate          # Linux/macOS
# cemd\Scripts\activate           # Windows

Install the package#

Once your environment is active, install cemd from PyPI:

pip install cemd

For GUI support:

pip install "cemd[gui]"

That installs a cemd-gui command, which opens the interface:

cemd-gui

Developer Installation#

If you plan to contribute to cemd development, clone the repository and install in editable mode:

git clone https://github.com/cemd-dev/cemd.git
cd cemd

Then create the development environment. This installs cemd editable, with the test, GUI and documentation extras, so there is nothing to run afterwards:

conda env create -f environment.yml
conda activate cemd

Editable means the environment points at your working copy: an edit to the source is visible on the next import, with no reinstall.

Without conda, the same thing in a virtual environment:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,gui,docs]"

Note

Do not also add the repository to PYTHONPATH. It would make cemd importable from every environment on the machine, including the throwaway ones used to check what a user actually receives – and those checks then silently test the working copy instead of the installed package.

Verifying the Installation#

Run the following to confirm that cemd is correctly installed:

import cemd
from cemd import AtomicSystem
print(f"CEMD {cemd.__version__} is ready.")