Skip to content

API reference

lccl provides the same library through two surfaces. The C++ surface is the definition, and the Python surface binds it.

Surface How to access Reference
C++ #include "lccl.h" C++ API — based on the comments in the public header
Python import lccl Python API

This API is C-style, but the public header is C++-only (default arguments, nullptr) and the hart headers it includes use C++17 features, so you must compile it as C++17 or later.

Semantics such as the call order across ranks, what groups guarantee, and the state a failure leaves behind are identical on both surfaces and are explained only once, in the Programming guide. This section covers signatures.


Name mapping

A Python function name is the C++ name with the Lccl prefix removed and converted to snake_case. Type names keep the Lccl prefix, and enum values drop only the k (kLcclFloat16 becomes LcclDataType.LcclFloat16).

C++ Python
LcclGetUniqueId() get_unique_id()
LcclCommInitRank() comm_init_rank()
LcclCommInitAll() comm_init_all()
LcclCommDestroy() comm_destroy()
LcclGroupStart() / LcclGroupEnd() group_start() / group_end()
LcclAllReduce() all_reduce()
LcclReduceScatter() reduce_scatter()
LcclSend() / LcclRecv() send() / recv()

Entry points that Python lacks and other exceptions are listed in Differences from the C++ API.


Public header

There is one public header, lccl.h. The communicator, collective, point-to-point, and group calls and the types and helpers are all declared there, and it includes no other LCCL header. The other headers in the source tree, including collectives.h and group.h, are internal.

lccl.h is in lccl/include/ of the site-packages where lccl is installed. lccl.h includes the public header of hart (ha_types.h), so include/ of the hart package must also be on the include path. For how to build and link, see C++ API.


Entry points by area

Area Entry points
Communicator LcclGetUniqueId, LcclCommInitRank, LcclCommInitAll, LcclCommInitRankConfig, LcclCommFinalize, LcclCommDestroy, LcclCommAbort, LcclCommCount, LcclCommUserRank, LcclCommHaDevice, LcclCommGetAsyncError
Buffer registration LcclCommRegister, LcclCommDeregister
Collective operations LcclAllReduce, LcclReduce, LcclReduceScatter, LcclBroadcast, LcclAllGather, LcclGather, LcclScatter, LcclAllToAll
Point-to-point LcclSend, LcclRecv
Group LcclGroupStart, LcclGroupEnd
Types and helpers LcclTypeSize, LcclDataTypeToString, LcclRedOpToString, LcclGetErrorToString

Common semantics

Properties that apply across the whole API. Details for each entry point are in the respective references.

Property Value
Return type Every C++ entry point except the type and string helpers (LcclTypeSize, *ToString) returns LcclResult. Outputs are passed through pointer parameters
Exceptions Not thrown. Python raises RuntimeError
Buffers Device pointers obtained from hart. lccl does not allocate them
count Number of elements, not bytes. 0 returns kLcclInvalidArgument
Order All ranks must call the same collectives in the same order
Unsupported combinations Rejected with kLcclNotSupported at the point of the call (at LcclGroupEnd() inside a group). Nothing is sent. For the LPU's limits, check the Support matrix
Completion timing On a blocking communicator, already complete when the call returns. Not guaranteed to wait for stream work queued before the call
Streams Most take an HaStream_t, which defaults to the calling thread's (per-device) default stream. LcclAllGather, LcclAllToAll, LcclSend, and LcclRecv do not take one
Single rank Handled as a shortcut with a local copy

See also