Python SDK

voltsdk is VOLT's Python SDK. It has two halves:

• a client for a VOLT server, VoltClient, authenticated with a team secret key;
• local tools that need no server: PluginHub, which downloads published plugins from the registry and runs them on files on your machine, SpatialAssembler, which builds GLB models from exporter payloads, open_in_volt, which opens GLB files in VOLT's canvas, and msgpack_as_df.

Its source is packages/sdk/python in the VOLT monorepo; this page describes version 3.1.1.

Install

pip install voltsdk
pip install "voltsdk[ovito]"   # with the OVITO integration

It needs Python 3.10 or later. PyPI has platform wheels for linux_x86_64 (built on Ubuntu 24.04, so older glibc releases are not supported), macosx_14_0_arm64 and win_amd64. Each wheel bundles VOLT's native runtime libraries under voltsdk/native/{bin,lib,share}, which voltsdk.native_root() returns. Its dependencies are msgpack, pandas, pyarrow, requests, zstandard, semver and, except under Emscripten, volt-spatial-assembler.

VOLT's notebooks run on the app's own Python runtime, built on Pyodide. It carries the SDK of the VOLT build it belongs to as a pure-Python wheel in /usr/local/share/python-wheels, and pip install voltsdk (or %pip install voltsdk) without a version installs that wheel rather than PyPI's. Its version ends in a digest of its files, such as 3.1.1+afe0a4816516. Each notebook kernel installs it when it starts, and gets VOLT_BASE_URL and VOLT_SECRET_KEY from the server, so VoltClient.from_env() works there with no setup. SpatialAssembler is unavailable in that runtime, because volt-spatial-assembler has no Pyodide build.

Connecting to a server

from voltsdk import VoltClient

client = VoltClient(secret_key='vsk_...', base_url='https://volt.example.com')
print(client.team)   # the secret key: its team, role, name, keyPrefix, ...

base_url may be the server's origin or end in /api; the client adds /api when it is missing. VoltClient.from_env(), the same as VoltClient(), reads the configuration from the environment, which VOLT's notebooks set for you:

VoltClient(secret_key=None, base_url=None, *, plugin_registry_url=None, plugin_registry_token=None, plugin_cache_dir=None) raises ValueError when it ends up without a key or a URL. The plugin_* arguments configure client.plugins.

Requests send Authorization: Bearer <key>, time out after 30 seconds, and retry GETs up to three times on 502, 503 and 504. A response whose envelope is not status: "success" raises:

All of them derive from VoltError.

Resources

Plugin hub

PluginHub downloads plugin bundles from the registry into a local cache and runs them as subprocesses on your files, with no VOLT server involved.

from voltsdk import PluginHub

hub = PluginHub(default_publisher='voltlabs')
hub.versions('coordination-analysis')       # ['1.0.1', ..., '2.1.1']
hub.install('coordination-analysis')        # Path to the extracted bundle

PluginHub(registry=None, *, url=None, cache_dir=None, default_publisher=None, token=None):

Keys are @scope/name, or a bare name when the hub has a default_publisher. A version is exact, a dist-tag such as latest (the default), or a caret range such as ^2.0.0. The platform is <system>-<machine>, such as linux-x86_64 or darwin-arm64.

Failures raise subclasses of PluginError: PluginNotFoundError (no such package or version, or no bundle for the platform), PluginYankedError, PluginVerificationError (the download does not match its SHA-256) and NetworkError.

Running a plugin

A Plugin is called like a function: the input, then its parameters as keyword arguments. help(plugin) lists them, with what the plugin requires and provides.

ptm = hub.get('polyhedral-template-matching')
dxa = hub.get('opendxa')

ptm_run = ptm('dump', output_dir='output/ptm-dxa', crystal_structure='FCC', rmsd=0.10)
dxa_run = dxa(ptm_run, output_dir='output/ptm-dxa', reference_topology='fcc')

print(dxa_run['dislocation_summary'].df('main_listing'))
print(dxa_run['dislocation_summary'].df('sub_listings.burgers_families'))
print(dxa_run['dislocations'].df().head())   # one row per dislocation line
dxa_run['dislocations'].open_in_volt()

plugin(source, *, output_dir=None, output_name=None, timeout=None, **kwargs):

• runs the bundle's program with the input path, an output prefix, the flags wired from upstream runs, and <flag> <value> for each parameter you pass. The program is the single file in the bundle's bin/, or the one named after the plugin when there are several, else the single file in scripts/ (a .py script runs with the current interpreter). It runs in the bundle's directory, with the bundle's bin/ and lib/ and the SDK's native runtime prepended to PATH, LD_LIBRARY_PATH and DYLD_LIBRARY_PATH;
• uses <output_dir>/<output_name> as the output prefix, where output_name defaults to the plugin's name, or, without output_dir, the input path without its extension. The plugin writes <prefix>_<suffix> files, such as output/ptm-dxa/opendxa_dislocations.parquet;
• waits up to timeout seconds, or indefinitely;
• returns a PluginRun, or raises PluginError (with the run as error.run) when the program exits with a non-zero status. Unknown keyword arguments raise PluginError listing the accepted ones.

The interface block

Passing ptm_run to OpenDXA works through the optional interface block of plugin.json, which only the SDK and VPM read:

"interface": {
  "version": 2,
  "requires": [
    { "id": "structure", "capability": "volt/structure-identification@1",
      "bind": { "clusters_table": "--clusters_table", "cluster_transitions": "--clusters_transitions", "neighbor_lattice": "--neighbor_lattice" } }
  ],
  "input": { "from": "structure", "port": "annotated_dump" },
  "provides": {
    "volt/dislocation-network@1": { "dislocations": "dislocations.parquet" },
    "volt/per-atom-properties@1": { "atoms": "atoms.parquet" }
  }
}

The SDK reads plugin.json from the bundle and refuses one without an interface block of version 2. You pass an upstream PluginRun as the input or as <requirement id>=run, and the SDK passes each bound port's file to its flag (comma-separated when multiple). It refuses a plain path where a capability is required, and a run where the input is a file.

SpatialAssembler

SpatialAssembler builds GLB models from the payloads that VOLT's exporters read (see export), so you can render a plugin's output without a server:

from voltsdk import SpatialAssembler, open_in_volt

glb_path = SpatialAssembler().lines_glb(
    'output/ptm-dxa/opendxa_dislocations.parquet',
    output_path='output/ptm-dxa/opendxa_dislocations.glb',
    color_by='burgers_family',
)
open_in_volt(glb_path)

source is a dict, or a .json or .msgpack file holding the payload itself or an export object with it under the exporter's name, or a Parquet lines table (id and points columns). Each method returns the GLB as bytes, or the written Path when you pass output_path; an empty payload gives an empty GLB.

open_in_volt

open_in_volt(source, *, title=None, volt_url=None, open_browser=True) opens GLB files in VOLT's canvas, at /canvas/glb, and returns the URL it opened. source is a path or URL, a list of them (one per timestep, in order), or a { timestep: path } mapping; several frames are written into a manifest with title.

Local files are served by a file server it starts on 127.0.0.1, so the browser must run on the same machine. In a notebook with VOLT_PUBLIC_BASE_PATH and VOLT_NOTEBOOK_PATH set, it copies them under .voltsdk-viewer/ in the notebook's directory and serves them through Jupyter instead. The app's URL is volt_url, else VOLT_APP_URL, else VOLT_BASE_URL without its /api, else https://app.voltcloud.dev.

Other helpers

Developing the SDK

cd packages/sdk/python
pip install -e .
pytest

pypi-voltsdk.yml builds the platform wheels on voltsdk-py-* releases. It downloads the published native bundles from the registry with scripts/download_native_bundles.py, stages them into voltsdk/native, builds a wheel tagged for the platform (VOLTSDK_PLATFORM_TAG), and smoke-tests it with scripts/smoke_native_plugins.py before publishing.