Struct DistributedSum 

pub struct DistributedSum<const W: usize, X: Transport, B = HostPartition<W>> { /* private fields */ }

One process’s partition of a sum split across a Transport’s group, held across calls so a driver scatters once, steps many times and gathers once.

The input is replicated: every rank scatters the same sum and keeps its own partition. gather returns Some on rank 0 only, and a PartitionTrace holds this rank’s counts only. B is where the partition lives: host memory, or a CUDA device under the cuda feature (gpu::GpuDistributedSum).

Implementations

impl<const W: usize, X: Transport, B> DistributedSum<W, X, B>

pub fn rank(&self) -> u32

This rank’s index in the group.

pub fn size(&self) -> u32

Ranks in the group, which is also the partition count.

pub fn transport(&self) -> &X

This rank’s endpoint, for a collective of the caller’s own.

pub fn rows(&self) -> &PartitionRows<W>

The rows deciding which rank a key belongs to.

pub fn runtime(&self) -> &Arc<PartitionRuntime>

The runtime this rank’s work runs on, for handing to another DistributedSum.

pub fn enable_trace(&mut self)

Start recording a PartitionTrace of this rank’s layers on every later propagation; idempotent.

pub fn take_trace(&mut self) -> Option<PartitionTrace>

Drain this rank’s per-layer records, or None if tracing was never enabled; tracing stays enabled.

terms_in, terms_out and rows_received have one entry, while rows_sent[0] and bytes_sent[0] are indexed by destination rank.

impl<const W: usize, X: Transport, B: PartitionStorage<W>> DistributedSum<W, X, B>

pub fn len(&self) -> usize

Terms in the whole sum. Collective.

pub fn is_empty(&self) -> bool

Whether the whole sum is empty. Collective, via len.

pub fn bits(&self) -> u8

The bucket bits, equal on every rank.

pub fn num_qubits(&self) -> usize

Qubits the sum is over.

impl<const W: usize, X: Transport> DistributedSum<W, X>

pub fn scatter( sum: PauliSum<W>, transport: X, config: &PartitionConfig, ) -> Result<Self, TopologyError>

Split the replicated sum across transport’s group by the default rows (PartitionRowPolicy::Seeded at the sum’s own hash seed), keeping this rank’s share on the one-partition runtime config describes.

Errors

TopologyError if config cannot be resolved or the pool cannot be built.

Panics

If config asks for more than one partition, or if the group size is not a power of two.

pub fn scatter_with( sum: PauliSum<W>, transport: X, options: ScatterOptions<W>, ) -> Self

scatter onto a caller-built runtime, split by the rows options names.

ScatterRows::Explicit rows must be the same on every rank; nothing checks it, and a disagreement misroutes an exchange.

Panics

If the runtime has more than one partition, if the group size is not a power of two, if the rows do not name one partition per rank or are for a different qubit count than sum, or as PartitionRows::cut. In debug builds, if the rows are not independent of the sum’s hash rows.

pub fn propagate<T>( &mut self, circuit: &Circuit<W>, policy: &T, direction: Direction, )

where T: TruncationPolicy<W> + ?Sized,

propagate_with under PropagateOptions::default().

pub fn propagate_with<T>( &mut self, circuit: &Circuit<W>, policy: &T, direction: Direction, options: PropagateOptions, )

where T: TruncationPolicy<W> + ?Sized,

Propagate through circuit under policy, in place. Collective: every rank passes the same circuit, direction and options.

A shape fingerprint of the run (channel count, direction, options, qubit count, W) is checked across ranks first; channel contents are not.

Panics

If options fail PropagateOptions::validate, if a channel’s preparation declines, or if the ranks disagree about the run’s shape. Before the first layer, above one rank, unless policy.supports_partitioned() — exact TopN is not yet supported partitioned.

pub fn gather(&self) -> Option<PauliSum<W>>

Collect the whole sum on rank 0, None elsewhere, leaving self intact. Collective.

pub fn local(&self) -> &PauliSum<W>

This rank’s share, a valid PauliSum under the group’s shared hash.

pub fn assert_invariants(&self)

Panic unless this rank’s share is well-formed and holds only its own keys; O(terms), local only.