Installation and pixi basics¶

This page gets SAMMD installed and explains the pixi commands used in the other tutorials.

SAMMD uses pixi instead of conda or mamba environment YAML files. Pixi reads pixi.toml and pixi.lock from this repository and creates the requested environment from conda-forge packages.

1. Install pixi¶

Install pixi once on your machine:

curl -fsSL https://pixi.sh/install.sh | sh

Restart your shell if the installer asks you to.

2. Clone SAMMD¶

git clone https://github.com/joelaforet/SAMMD.git
cd SAMMD

3. Use the default environment¶

The default environment is for YAML files, validation, builds, testing, and docs. It includes the OpenFF-related packages used by SAMMD build/export and does not need a GPU.

pixi install
pixi shell -e default

After pixi shell -e default, the sammd command is available directly:

sammd init -o sammd-project
sammd validate sammd-project/sammd.yaml
sammd build sammd-project/sammd.yaml --output-dir sammd-project/outputs --overwrite

Leave the pixi shell with:

exit

4. Run one command without entering a shell¶

If you are not inside a pixi shell, prefix commands with pixi run:

pixi run sammd validate sammd-project/sammd.yaml

For a named environment, add -e:

pixi run sammd build sammd-project/sammd.yaml --output-dir sammd-project/outputs --overwrite

5. Switch environments¶

Pixi does not use conda activate. Use pixi shell -e ENV_NAME instead.

pixi shell -e default
exit

pixi shell -e cuda-12-4
exit

pixi shell -e cuda-12-6

6. Choose a CUDA environment¶

OpenMM GPU support depends on the NVIDIA driver and CUDA version available on the machine. On a GPU node or workstation, run:

nvidia-smi

Use an environment whose CUDA version is not newer than the CUDA version shown by nvidia-smi.

SAMMD pixi environments¶
Environment	Use case	CUDA line	OpenMM pin
`default`	config, validation, builds, tests	none	none
`docs`	Sphinx documentation builds	none	none
`cuda-12-4`	GPU OpenMM work on CUDA 12.4 driver line	12.4	`openmm=8.1.2`
`cuda-12-6`	GPU OpenMM work on CUDA 12.6 driver line	12.6	`openmm=8.4.0`
`cuda-13-0`	GPU OpenMM work on CUDA 13.0 driver line	13.0	`openmm=8.5.1`

Known examples:

CU Boulder Blanca older-GPU nodes: cuda-12-4
PSC Bridges2: cuda-12-6

All SAMMD pixi environments include OpenFF, RDKit, mBuild, and PACKMOL for sammd build export. When unsure for GPU OpenMM work, choose the older compatible CUDA environment.

7. Use pixi environments as VSCode notebook kernels¶

VSCode’s Python extension can often detect Pixi environments from the .pixi/envs folder in the repository. If it does not, run Python: Select Interpreter from the Command Palette and choose a Python executable such as .pixi/envs/default/bin/python or .pixi/envs/cuda-12-4/bin/python.

For notebooks, register each Pixi environment as a Jupyter kernel once. The --name value is the internal kernel ID; --display-name is what VSCode shows in the notebook kernel picker.

pixi run -e default python -m ipykernel install --user \
  --name sammd-default \
  --display-name "Python (SAMMD default)"

pixi run -e cuda-12-4 python -m ipykernel install --user \
  --name sammd-cuda-12-4 \
  --display-name "Python (SAMMD cuda-12-4)"

Use sammd-default for normal notebooks that initialize, validate, and build SAMMD systems. Use a CUDA-labeled kernel, for example sammd-cuda-12-4, when a notebook needs a specific GPU OpenMM pin for downstream MD work.

To use a notebook in VSCode:

Open the SAMMD repository folder in VSCode.
Install the Microsoft Python and Jupyter extensions if VSCode asks for them.
Open a notebook from notebooks/.
Click the kernel name in the upper-right corner of the notebook.
Choose Python (SAMMD default) or the matching CUDA kernel.

If you update or recreate Pixi environments later, rerun the same python -m ipykernel install command for the kernel you use.

8. Next step¶

After installation, continue to Recommended build-to-OpenMM workflow to build your first SAMMD system.