API Reference

KUSP exposes a small but powerful Python surface area: decorators for registering models, the TCP server runtime, the CLI entry points, and helpers for installing/removing the bundled KIM artifacts. The sections below mirror those responsibilities.

Model decorators

kusp.kusp.kusp_model(influence_distance: float | float64 | ndarray, species: Tuple[str, ...], strict_arg_check: bool = True, **metadata)

Mark a callable as a KUSP model entry point.

Parameters:

• influence_distance – Cutoff distance advertised to KIM-API.

• species – Tuple of species symbols in the order expected by the model.

• strict_arg_check – Whether to raise instead of warn on signature issues.

• **metadata – Extra attributes stored on the decorated object.

Todo

Add support for units. It is easy, just extra decorator arguments.

Returns:

Decorating function that adds bookkeeping attributes.

TCP server runtime

class kusp.io.IPProtocol(host: str = '127.0.0.1', port: int = 12345, max_connections: int = 1, reuse_address: bool = True, recv_timeout_s: float = 15.0, send_timeout_s: float = 15.0, max_atoms: int = 1000000000, *, model_file: str | None = None, init_kwargs: dict | None = None)

Bases: object

Serve KUSP models over a TCP socket.

serve(handler: Callable | None = None) → None

Run the main accept/response loop.

Parameters:

handler – Optional callable overriding the configured model.

Raises:

RuntimeError – If start has not been called or no handler exists.

start(on_ready: Callable[[], None] | None = None) → None

Bind the listening socket and start accepting clients.

Parameters:

on_ready – Optional callback invoked once the server is bound.

stop() → None

Shut down the server socket and restore the default SIGINT handler.

CLI commands

kusp.cli.main(argv: list[str] | None = None) → int

Execute the CLI and return an exit code.

Parameters:

argv – Optional argument vector override.

Returns:

Process exit code provided by Click.

KIM artifact helpers

Helpers for interacting with bundled KIM artifacts.

class kusp.kim.DeploymentPackage(model_name: str, target_dir: Path, env_file: Path, cmake_file: Path, files_written: Tuple[str, ...])

Bases: object

One stop information about the generated deployment package.

cmake_file: Path

env_file: Path

files_written: Tuple[str, ...]

model_name: str

target_dir: Path

kusp.kim.check_if_driver_installed() → bool

Return True if the bundled driver is already installed.

kusp.kim.check_if_model_installed() → bool

Return True if the bundled Python model is already installed.

kusp.kim.install_kim_driver(collection: str = 'user', installer: str = 'kim-api-collections-management') → bool

Install the native C++ driver that bridges KIM to the TCP server.

Parameters:

• collection – Target KIM collection (ignored for kimitems).

• installer – kim-api-collections-management or kimitems.

Returns:

True once the installation command completes successfully.

kusp.kim.install_kim_model(collection: str = 'user', installer: str = 'kim-api-collections-management') → bool

Install the portable Python reference model for KUSP.

Parameters:

• collection – Target KIM collection (e.g. user or system) if installing via kim-api-collections-management.

• installer – Either kim-api-collections-management or kimitems.

Returns:

True once the installation command completes successfully.

kusp.kim.package_model_for_deployment(model_file: Path, resources: Iterable[Path] = (), *, name: str | None = None, env_mode: str) → DeploymentPackage

Bundle a decorated model and auxiliary files into a deployable package.

Parameters:

• model_file – Path to a Python module containing a @kusp_model entry.

• resources – Extra files copied verbatim into the package directory.

• name – Optional explicit KIM-compliant model name.

• env_mode – ast, pip, or conda env description strategy.

Returns:

DeploymentPackage with paths to all generated artifacts.

kusp.kim.remove_kim_driver(installer: str = 'kim-api-collections-management') → bool

Remove the compiled KIM bridge driver.

Parameters:

installer – kim-api-collections-management or kimitems selector.

Returns:

True after the removal command finishes.

kusp.kim.remove_kim_model(installer: str = 'kim-api-collections-management') → bool

Remove the previously installed portable Python model.

Parameters:

installer – kim-api-collections-management or kimitems selector.

Returns:

True after the removal command finishes.

class kusp.kim.kim_utils.DeploymentPackage(model_name: str, target_dir: Path, env_file: Path, cmake_file: Path, files_written: Tuple[str, ...])

Bases: object

One stop information about the generated deployment package.

cmake_file: Path

env_file: Path

files_written: Tuple[str, ...]

model_name: str

target_dir: Path

kusp.kim.kim_utils.check_if_driver_installed() → bool

Return True if the bundled driver is already installed.

kusp.kim.kim_utils.check_if_model_installed() → bool

Return True if the bundled Python model is already installed.

kusp.kim.kim_utils.package_model_for_deployment(model_file: Path, resources: Iterable[Path] = (), *, name: str | None = None, env_mode: str) → DeploymentPackage

Bundle a decorated model and auxiliary files into a deployable package.

Parameters:

• model_file – Path to a Python module containing a @kusp_model entry.

• resources – Extra files copied verbatim into the package directory.

• name – Optional explicit KIM-compliant model name.

• env_mode – ast, pip, or conda env description strategy.

Returns:

DeploymentPackage with paths to all generated artifacts.