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 |