{"id":9143,"library":"nvalchemi-toolkit-ops","title":"NVALCHEMY Toolkit Ops","description":"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.","status":"active","version":"0.3.1","language":"en","source_language":"en","source_url":"https://github.com/NVALCHEMY/toolkit-ops","tags":["GPU","NVIDIA Warp","computational chemistry","atomistic simulation","high-performance computing","chemistry"],"install":[{"cmd":"pip install nvalchemi-toolkit-ops","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for Warp GPU computations. Must be installed separately.","package":"nvidia-warp-core","optional":false}],"imports":[{"symbol":"get_bond_length","correct":"from toolkit_ops.mol_geom import get_bond_length"},{"note":"The underlying NVIDIA Warp library is typically imported directly as 'wp'.","symbol":"wp","correct":"import warp as wp"},{"note":"Commonly used for force field definitions and calculations.","symbol":"forcefield","correct":"from toolkit_ops import forcefield"}],"quickstart":{"code":"import warp as wp\nfrom toolkit_ops.mol_geom import get_bond_length\nimport numpy as np\n\n# Initialize Warp (requires an NVIDIA GPU and CUDA setup)\ntry:\n    wp.init()\nexcept Exception as e:\n    print(f\"Warning: Could not initialize Warp. GPU operations will fail: {e}\")\n    # In a real application, you might exit or provide fallback CPU logic here.\n\n# Example usage:\npositions_np = np.array([\n    [0.0, 0.0, 0.0],\n    [1.0, 0.0, 0.0]\n], dtype=np.float32)\n# Convert numpy array to Warp array\npositions = wp.array(positions_np, dtype=wp.vec3)\n\n# Calculate bond length\nbond_length = get_bond_length(positions, index_0=0, index_1=1)\n\nprint(f\"Calculated bond length: {bond_length.numpy()}\")","lang":"python","description":"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."},"warnings":[{"fix":"Always consult the `CHANGELOG.md` or official documentation when upgrading minor versions. Update import paths and API calls accordingly.","message":"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`.","severity":"breaking","affected_versions":"<0.3.0"},{"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.","message":"NVALCHEMY Toolkit Ops requires an NVIDIA GPU with CUDA installed and properly configured, along with the `nvidia-warp-core` package.","severity":"gotcha","affected_versions":"All"},{"fix":"Use a Python environment that satisfies `Python>=3.11,<3.15` to avoid installation and runtime issues.","message":"Python version compatibility is strict. The library currently requires Python >=3.11 and <3.15.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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(...)`).","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the core Warp library: `pip install nvidia-warp-core`.","cause":"The `nvidia-warp-core` package, which provides the `warp` module, is not installed or not accessible.","error":"ModuleNotFoundError: No module named 'warp'"},{"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.","cause":"NVIDIA Warp could not detect a compatible GPU or CUDA installation on your system during `wp.init()`.","error":"RuntimeError: No CUDA device found. ..."},{"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.","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`.","error":"ImportError: cannot import name 'get_bond_length' from 'toolkit_ops.mol_geom' (.../python3.x/site-packages/toolkit_ops/mol_geom/__init__.py)"},{"fix":"Convert your NumPy array to a `warp.array` using `wp.array(numpy_array, dtype=...)` before passing it to the function.","cause":"You are attempting to pass a raw NumPy array directly to a `toolkit_ops` function that expects a `warp.array`.","error":"TypeError: 'numpy.ndarray' object cannot be interpreted as a Warp array"}]}