Skip to content

python_api.md

Latest commit

 

History

History
64 lines (44 loc) · 2.44 KB

python_api.md

File metadata and controls

64 lines (44 loc) · 2.44 KB
Raw

NIXL Python API

The Python API can be found at src/api/python/_api.py. These are the pythonic APIs for NIXL, if more direct access to C++ style methods are desired, the exact header implementation of src/api/cpp is done through pybind11 that can be found in src/bindings/python.

Python API Features

The Python bindings provide access to the full NIXL API including:

  • Agent Management: Create and configure NIXL agents
  • Memory Registration: Register and deregister memory/storage
  • Transfer Operations: Create and manage data transfers
  • QueryMem API: Query memory/storage information and accessibility
  • Backend Management: Create and configure different backends (UCX, GDS, etc.)

Installation

From PyPI

The nixl python API and libraries, including UCX, are available directly through PyPI:

pip install nixl

From Source

To build from source, follow the main build instructions in the README.md, then install the Python bindings:

# From the root nixl directory
pip install .

Backend initialization parameters

Backends expose their initialization parameters through get_plugin_params(backend), which returns the defaults. Override the values you need before passing the map to create_backend:

from nixl import nixl_agent, nixl_agent_config

# backends=[] leaves backend creation to the caller. The default config
# initializes UCX, and a backend can only be created once per agent.
agent = nixl_agent("example_agent", nixl_agent_config(backends=[]))

params = agent.get_plugin_params("UCX")
params["ucx_error_handling_mode"] = "peer"   # or "none"
agent.create_backend("UCX", params)

See UCX backend initialization options for the supported UCX keys and their semantics. Note that ucx_error_handling_mode influences UCP transport lane selection in addition to error reporting.

Examples

See the Python examples directory for complete working examples including: