NVALCHEMY Toolkit Ops

0.3.1 · active · verified Thu Apr 16

NVALCHEMY Toolkit Ops (pypi: `nvalchemi-toolkit-ops`) is a Python library providing high-performance NVIDIA Warp primitives for GPU-enabled computational chemistry and atomistic simulation workflows. It leverages NVIDIA Warp for accelerated calculations. As of version 0.3.1, it is under active development with frequent minor and patch releases, often introducing new features and refactorings.

Common errors

```
ModuleNotFoundError: No module named 'warp'
```
cause The `nvidia-warp-core` package, which provides the `warp` module, is not installed or not accessible.

fix Install the core Warp library: `pip install nvidia-warp-core`.
```
RuntimeError: No CUDA device found. ...
```
cause NVIDIA Warp could not detect a compatible GPU or CUDA installation on your system during `wp.init()`.

fix Verify that you have an NVIDIA GPU, CUDA Toolkit installed, and that your drivers are up to date. Ensure your environment variables are correctly set for CUDA.
```
ImportError: cannot import name 'get_bond_length' from 'toolkit_ops.mol_geom' (.../python3.x/site-packages/toolkit_ops/mol_geom/__init__.py)
```
cause The symbol `get_bond_length` or a similar function has been removed, renamed, or moved to a different submodule in your installed version of `nvalchemi-toolkit-ops`.

fix Consult the `CHANGELOG.md` for your installed version or the official documentation. Upgrade to the latest version and update your import paths if necessary.
```
TypeError: 'numpy.ndarray' object cannot be interpreted as a Warp array
```
cause You are attempting to pass a raw NumPy array directly to a `toolkit_ops` function that expects a `warp.array`.

fix Convert your NumPy array to a `warp.array` using `wp.array(numpy_array, dtype=...)` before passing it to the function.

Warnings

breaking Breaking changes are frequent in 0.x.x releases. Version 0.3.0 introduced a restructuring into the `nvalchemy` namespace, and 0.2.0 removed `WarpFFModel` and `WarpNNModel`.
Fix: Always consult the `CHANGELOG.md` or official documentation when upgrading minor versions. Update import paths and API calls accordingly.
gotcha NVALCHEMY Toolkit Ops requires an NVIDIA GPU with CUDA installed and properly configured, along with the `nvidia-warp-core` package.
Fix: Ensure `pip install nvidia-warp-core` is run and your system has a compatible NVIDIA GPU and CUDA toolkit installed. `wp.init()` must execute successfully before using Warp primitives.
gotcha Python version compatibility is strict. The library currently requires Python >=3.11 and <3.15.
Fix: Use a Python environment that satisfies `Python>=3.11,<3.15` to avoid installation and runtime issues.
gotcha Direct NumPy arrays are not supported as input for most `toolkit_ops` functions. Inputs must first be converted to Warp arrays (e.g., `wp.array(...)`).
Fix: Convert NumPy arrays to `warp.array` instances with the appropriate `dtype` (e.g., `wp.vec3`, `wp.float32`) before passing them to `toolkit_ops` functions.

Install

pip install nvalchemi-toolkit-ops Install latest version

Imports

get_bond_length

from toolkit_ops.mol_geom import get_bond_length

wp
```
import warp as wp
```
The underlying NVIDIA Warp library is typically imported directly as 'wp'.
forcefield
```
from toolkit_ops import forcefield
```
Commonly used for force field definitions and calculations.

Quickstart

This quickstart demonstrates calculating a bond length using `toolkit_ops.mol_geom.get_bond_length`. It initializes NVIDIA Warp, converts a NumPy array of atomic positions to a Warp array, and then performs the calculation. An NVIDIA GPU and CUDA are required for `wp.init()` to succeed.

import warp as wp
from toolkit_ops.mol_geom import get_bond_length
import numpy as np

# Initialize Warp (requires an NVIDIA GPU and CUDA setup)
try:
    wp.init()
except Exception as e:
    print(f"Warning: Could not initialize Warp. GPU operations will fail: {e}")
    # In a real application, you might exit or provide fallback CPU logic here.

# Example usage:
positions_np = np.array([
    [0.0, 0.0, 0.0],
    [1.0, 0.0, 0.0]
], dtype=np.float32)
# Convert numpy array to Warp array
positions = wp.array(positions_np, dtype=wp.vec3)

# Calculate bond length
bond_length = get_bond_length(positions, index_0=0, index_1=1)

print(f"Calculated bond length: {bond_length.numpy()}")

view raw JSON →