# 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:

  ```bash
  conda install -c conda-forge kim-api
  ```

- **CMake** and a compiler toolchain for building the bundled driver (`KUSP__MD_...`).

## Installing KUSP

### From PyPI

```bash
pip install kusp
```

### From source (development)


```bash
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.

```shell
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

```bash
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

```bash
kusp serve path/to/model.py
```

Typical output:

```text
[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:
  ```bash
  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.

```text
^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

```bash
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:

```text
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

```bash
kusp remove model
kusp remove driver
```

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

```bash
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

```python
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.