Installation

FlashCart requires Python 3.10 or newer and PyTorch 2.9 or newer. Install it in a virtual environment to keep its dependencies separate from other projects.

Prepare the environment

For example, on Linux or macOS:

python3 -m venv .venv
source .venv/bin/activate

Choose a PyTorch build for your hardware using the PyTorch installation instructions before installing FlashCart. For example, the following command installs a PyTorch build for CUDA 12.8:

python -m pip install "torch>=2.9" --index-url https://download.pytorch.org/whl/cu128

For a CPU or Apple Silicon installation, use the command appropriate to your platform from the PyTorch instructions.

Install FlashCart

From PyPI

python -m pip install flashcart

From source

Clone the repository and install FlashCart from the local source directory. The -e option makes Python use this directory directly, so edits to the Python source take effect without reinstalling:

git clone https://github.com/inm-leibniz/flashcart.git
cd flashcart
python -m pip install -e .

Check the installation

Run the following Python code to check that FlashCart imports and display its version, the PyTorch version, and the available hardware backends:

import torch
import flashcart
from flashcart.calculators import FlashCartCalculator

print("FlashCart:", flashcart.__version__)
print("PyTorch:", torch.__version__)
print("CUDA available:", torch.cuda.is_available())
print("MPS available:", torch.backends.mps.is_available())

A value of False for CUDA or MPS means that backend is unavailable in the current environment. You can still run FlashCart on the CPU. See Quickstart to train and use a model.

Hardware support

On NVIDIA GPUs, FlashCart can evaluate tensor products, Cartesian tensor expansions, and equivariant linear maps with fused Triton kernels. CPUs and Apple Silicon (device=mps) use PyTorch implementations of these operations. Setting use_triton=False also selects the PyTorch implementations on CUDA devices.

Both implementations evaluate the same mathematical expressions. Their results can differ because of floating-point rounding.

The first import can take longer while FlashCart generates and caches kernel source files. GPU compilation and autotuning can add further overhead on the first evaluation. See Kernel generation and compilation for details.

Optional components

Running FlashCart in LAMMPS requires a LAMMPS build with Python-enabled ML-IAP. GPU simulations also require Kokkos and CuPy, as described in Build LAMMPS.

For container-based use, the repository provides a Dockerfile that builds an image containing CUDA 12.8, PyTorch, and FlashCart.

Development and tests

From the repository root, install the development dependencies:

python -m pip install -e ".[dev]"

These include the testing and packaging tools. To also install the tools needed to build the documentation, use python -m pip install -e ".[dev,docs]".

Run the tests with:

python -m pytest
python -m pytest -m slow

The first command excludes tests marked slow. The second runs only those tests, which cover the command-line tools, multi-process training, and compilation. CUDA-dependent tests are skipped when CUDA is unavailable. Use python -m pytest -m "" to run both groups together.