FHElium

Appearance

fhelium.distributed._value_collectives ​

Typed whole-value broadcast, scatter, gather, and all-gather.

broadcast_ciphertext ​

function View source

python
def broadcast_ciphertext(value_or_none: Ciphertext | None, *, src: int=0, group: torch.distributed.ProcessGroup | None=None) -> Ciphertext: ...

Broadcast one complete ciphertext and allocate non-source receivers.

A small internal object descriptor carries shape and CKKS metadata; the dense payload then uses the ordinary tensor broadcast. No placement or owner policy is inferred. The operation is synchronous: it accepts no async_op argument and returns no torch.distributed.Work.

Parameters

  • value_or_none: Ciphertext supplied only by src. Every non-source rank must pass None.
  • src: Global rank of the source process, which must belong to group. This is not a process-group-relative rank.
  • group: Participating process group. None selects the default process group.

Returns

The source's original ciphertext on src and a newly allocated, metadata-equivalent ciphertext on every other group rank. For a world-size-one group, the source object is returned unchanged and no payload communication or receiver allocation occurs.

Raises

  • ValueError: If src is outside group or ranks violate the source/non-source argument rules.
  • RuntimeError: If distributed communication is uninitialized, the caller is not a group member, or a valid transfer descriptor cannot be exchanged.

broadcast_plaintext ​

function View source

python
def broadcast_plaintext(value_or_none: Plaintext | None, *, src: int=0, group: torch.distributed.ProcessGroup | None=None) -> Plaintext: ...

Broadcast one complete plaintext and allocate non-source receivers.

The message or encoded data representation and its arithmetic metadata are preserved. The operation does not mutate the source plaintext, accepts no async_op argument, and returns no torch.distributed.Work.

Parameters

  • value_or_none: Plaintext supplied only by src. Every non-source rank must pass None.
  • src: Global rank of the source process, which must belong to group. This is not a process-group-relative rank.
  • group: Participating process group. None selects the default process group.

Returns

The source's original plaintext on src and a newly allocated, metadata-equivalent plaintext on every other group rank. For a world-size-one group, the source object is returned unchanged without payload communication or receiver allocation.

Raises

  • ValueError: If src is outside group or ranks violate the source/non-source argument rules.
  • RuntimeError: If distributed communication is uninitialized, the caller is not a group member, or a valid transfer descriptor cannot be exchanged.

broadcast_compressed_plaintext ​

function View source

python
def broadcast_compressed_plaintext(value_or_none: CompressedPlaintext | None, *, src: int=0, group: torch.distributed.ProcessGroup | None=None) -> CompressedPlaintext: ...

Broadcast one compressed plaintext with typed allocation.

The compact tensor, ring dimension, encoded repetition layout, and all arithmetic metadata are preserved. The operation is synchronous.

broadcast_key ​

function View source

python
def broadcast_key(key_or_none: _KeyT | None, *, src: int=0, group: torch.distributed.ProcessGroup | None=None) -> _KeyT: ...

Broadcast selected key material with typed allocation.

The function performs no key generation, owner inference, or automatic placement. Calling it is the program's visible decision to communicate one selected key. It is synchronous, accepts no async_op argument, and returns no torch.distributed.Work.

Parameters

  • key_or_none: Supported dense FHElium key supplied only by src. Every non-source rank must pass None.
  • src: Global rank of the source process, which must belong to group. This is not a process-group-relative rank.
  • group: Participating process group. None selects the default process group.

Returns

The source's original key object on src and a newly allocated key of the same concrete type and metadata on every other group rank. For a world-size-one group, the source object is returned unchanged and no payload communication or receiver allocation occurs.

Raises

  • ValueError: If src is outside group, the source value is not a supported key, or ranks violate the source/non-source argument rules.
  • RuntimeError: If distributed communication is uninitialized, the caller is not a group member, or a valid transfer descriptor cannot be exchanged.

scatter_ciphertexts ​

function View source

python
def scatter_ciphertexts(values_or_none: Sequence[Ciphertext] | None, *, src: int=0, group: torch.distributed.ProcessGroup | None=None) -> Ciphertext: ...

Scatter caller-prepared ciphertext values from one source.

The source supplies the values to send, whether independent workload items or views it has already prepared. This interface performs no slicing or reconstruction. This is representation-preserving transport, not an arithmetic operation. Sequence position is process-group-rank order even though src is a global rank. The operation is synchronous, accepts no async_op argument, and returns no torch.distributed.Work.

Parameters

  • values_or_none: On src, one prepared ciphertext per group rank in process-group-rank order. Every non-source rank must pass None.
  • src: Global rank of the source process, which must belong to group.
  • group: Participating process group. None selects the default process group.

Returns

The ciphertext assigned to the caller's process-group rank. The source receives its existing sequence element; other ranks receive newly allocated ciphertexts. For world size one, values_or_none[0] is returned unchanged without communication or allocation.

Raises

  • ValueError: If src is outside group; the source does not provide exactly one ciphertext per group rank; a non-source rank supplies values; or rank-local arguments disagree.
  • RuntimeError: If distributed communication is uninitialized or the caller is not a member of group.

gather_ciphertexts ​

function View source

python
def gather_ciphertexts(value: Ciphertext, *, dst: int=0, group: torch.distributed.ProcessGroup | None=None) -> list[Ciphertext] | None: ...

Gather independent ciphertexts in process-group rank order.

This is representation-preserving transport, not an algebraic reduction. Use reduce_ciphertext when the inputs are additive partials of one logical encrypted value. The operation is synchronous, accepts no async_op argument, and returns no torch.distributed.Work.

Parameters

  • value: One independent rank-local ciphertext. It is read but not mutated.
  • dst: Global rank that receives the list, which must belong to group. This is not a process-group-relative rank.
  • group: Participating process group. None selects the default process group.

Returns

On dst, one ciphertext per group rank in process-group-rank order; the destination's list entry is its original object and other entries are newly allocated. Other ranks return None. For world size one, the sole rank returns [value] with the original object.

Raises

  • ValueError: If dst is outside group, a rank does not provide a ciphertext, or rank-local arguments disagree.
  • RuntimeError: If distributed communication is uninitialized or the caller is not a member of group.

all_gather_ciphertexts ​

function View source

python
def all_gather_ciphertexts(value: Ciphertext, *, group: torch.distributed.ProcessGroup | None=None) -> list[Ciphertext]: ...

All-gather independent ciphertexts with one identical layout.

Equality covers context, depth, scale, components, prime IDs, domain, basis, Montgomery state, degree, shape, and dtype. Rank-local CUDA device indices may differ because descriptors intentionally preserve device type rather than one global device index. This is transport of independent values, not algebraic reduction. The operation is synchronous, accepts no async_op argument, and returns no torch.distributed.Work.

Parameters

  • value: One independent rank-local ciphertext. All group ranks must provide ciphertexts with identical layout metadata. The input is read but not mutated.
  • group: Participating process group. None selects the default process group. No root rank is used.

Returns

A newly allocated list on every rank containing one ciphertext per group rank in process-group-rank order. Entries, including the caller's entry, are new ciphertext objects whose tensors use the same device as the caller's input. For world size one, a one-element copied result is returned.

Raises

  • TypeError: If value is not a ciphertext.
  • ValueError: If ciphertext shapes or arithmetic metadata differ across group ranks.
  • RuntimeError: If distributed communication is uninitialized or the caller is not a member of group.

all_gather_plaintexts ​

function View source

python
def all_gather_plaintexts(value: Plaintext, *, group: torch.distributed.ProcessGroup | None=None) -> list[Plaintext]: ...

All-gather independent plaintexts with one arithmetic state.

Every rank must provide the same message/encoded representation kind, shape, dtype, context, depth, scale, layout, domain, basis, Montgomery state, and prime IDs. This is representation-preserving transport, not an arithmetic operation. It is synchronous, accepts no async_op argument, and returns no torch.distributed.Work.

Parameters

  • value: One independent rank-local plaintext. It is read but not mutated.
  • group: Participating process group. None selects the default process group. No root rank is used.

Returns

A newly allocated list on every rank containing one plaintext per group rank in process-group-rank order. Entries, including the caller's entry, are new plaintext objects whose tensors use the same device as the caller's input. For world size one, a one-element copied result is returned.

Raises

  • TypeError: If value is not a plaintext.
  • ValueError: If plaintext representations, shapes, or arithmetic metadata differ across group ranks.
  • RuntimeError: If distributed communication is uninitialized or the caller is not a member of group.

all_gather_compressed_plaintexts ​

function View source

python
def all_gather_compressed_plaintexts(value: CompressedPlaintext, *, group: torch.distributed.ProcessGroup | None=None) -> list[CompressedPlaintext]: ...

All-gather independent compressed plaintexts sharing one layout.