Installation & Usage

This page collects the essential steps to install KUSP, its dependencies, and to get started with the CLI before diving into the detailed examples. The second half walks through the key decorator API so you can turn any Python potential into a KIM-compatible callable.

Prerequisites

  • Python 3.9+ (official support spans CPython 3.9-3.12).

  • KIM-API 2.3 (or newer). Installing via Conda is the most straightforward route:

    conda install -c conda-forge kim-api

  • CMake and a compiler toolchain for building the bundled driver (KUSP__MD_...).

Installing KUSP

From PyPI

pip install kusp

From source (development)

pip install git+https://github.com/openkim/kusp.git

CLI quick start

The kusp CLI orchestrates the entire workflow. Run kusp --help for the latest options.

kusp --help
Usage: kusp [OPTIONS] COMMAND [ARGS]...

  KUSP utilities.

Options:
  -v      Increase verbosity (-v, -vv).
  --help  Show this message and exit.

Commands:
  export   Package a KUSP model and its auxiliary files for exporting.
  install  Install the bundled KUSP KIM model or driver.
  remove   Remove the bundled KUSP KIM model or driver.
  serve    Run a TCP KUSP server from a decorated model file.

1. Install the bridge artifacts

kusp install model   # portable Python model used by the TCP server
kusp install driver  # compiled driver used by 'kusp export'

Options:

  • --installer: choose kim-api-collections-management (default) or kimitems.

  • --collection: target a specific collection when using kim-api-collections-management.

2. Serve a model over TCP

kusp serve path/to/model.py

Typical output:

[KUSP] Config written to /tmp/kusp_config_12345_xxxxxx_yyyyyyyyy.yaml. Export KUSP_CONFIG to point simulators at this server.
[KUSP] TCP server listening on 127.0.0.1:12345

  • xxxxxx is the process ID and yyyyyyyyy the Unix timestamp.

  • Export the printed config path so simulators know how to connect:

    export KUSP_CONFIG=/tmp/kusp_config_12345_2426326_1763914552.yaml

  • Save the Python file and press Ctrl+C once to hot-reload the handler. Press it twice quickly to shut down.

^C[KUSP] Reloading model (Ctrl-C twice quickly to exit).
[KUSP] example.py reloaded

^C[KUSP] Reloading model (Ctrl-C twice quickly to exit).
^C[KUSP] Two Ctrl-C within 2.0s; shutting down.

3. Export a portable model directory

kusp export model.py \
    -n KUSP_example__MO_111111111111_000 \
    --resource extra_file.dat

This snapshots the decorated model, optional resource files, environment manifest, and CMakeLists.txt into a portable directory that you can install via kim-api-collections-management.

Example layout:

KUSP_example__MO_111111111111_000
├── CMakeLists.txt
├── extra_file.dat
├── kusp_env.ast.env
└── @kusp_model_6ea42e7127c5b38b_KUSP_example__MO_111111111111_000.py

  • The @kusp_model_*.py file is the decorated source with a hash prefix (6ea42e...) that captures its contents.

  • kusp_env.ast.env is generated via AST-based dependency analysis. You can instead use --env pip or --env conda if you prefer to snapshot the current environment via pip freeze/conda env export.

4. Remove the artifacts

kusp remove model
kusp remove driver

Because the portable model and driver are regular KIM items, you can also remove them via:

kim-api-collections-management remove KUSP__MO_000000000000_000
kim-api-collections-management remove KUSP__MD_000000000000_000

Environment variables

  • KUSP_CONFIG: path to the YAML config generated by kusp serve.

  • KUSP_PYTHON_EXEC: optional override for the Python interpreter path used by the native driver for environments with multiple Python installs.

Usage: the decorator API

Using KUSP in your code is as simple as importing the decorator and annotating a callable that returns energy and forces. Type hints are strongly recommended (and enforced when strict_arg_check=True).

Minimal example

from pathlib import Path
from typing import Tuple

import numpy as np
from kusp import kusp_model


@kusp_model(influence_distance=2.5, species=("He",))
def lj(species: np.ndarray,
       positions: np.ndarray,
       contributing: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
    energy = np.zeros(1, dtype=np.float64)
    forces = np.zeros_like(positions, dtype=np.float64)
    return energy, forces

Key parameters:

  • influence_distance: Cutoff distance (in Å) that KIM consumes.

  • species: Tuple of chemical symbols in the order expected by the callable.

  • strict_arg_check: When True (default), the decorator validates the signature and return annotations.

  • metadata: Additional keyword arguments stored on the decorated object (e.g., units).

Strict validation requires:

  • A callable accepting exactly three positional arguments: (species, positions, contributing).

  • Return annotations specifying Tuple[np.ndarray, np.ndarray].

Once decorated, you can point kusp serve or kusp export at the module containing this callable and the CLI will pick it up automatically.

Currently only units supported are eV for energy and Å for distance. More units will be supported in near future. Please check the examples for more detailed usecases.