Struct PartitionedSum 

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

A PauliSum split across the partitions of a PartitionRuntime, held across calls so a driver scatters and gathers once.

Between calls every partition’s sum holds only keys of its own partition and shares one hash and bucket count with its peers (PartitionedSum::assert_invariants). B is where a partition lives: host memory by default, a CUDA device for gpu::GpuPartitionedSum.

Implementations

impl<const W: usize, B> PartitionedSum<W, B>

pub fn num_partitions(&self) -> usize

Partitions this sum is split across.

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

The rows deciding which partition a key belongs to.

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

The runtime this sum runs on, for handing to another PartitionedSum.

pub fn enable_trace(&mut self)

Start recording a PartitionTrace on every later propagation; idempotent.

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

Drain the per-layer records, or None if tracing was never enabled; tracing stays enabled.

impl<const W: usize, B: PartitionStorage<W>> PartitionedSum<W, B>

pub fn len(&self) -> usize

Terms in the whole sum, summed over partitions.

pub fn is_empty(&self) -> bool

Whether every partition is empty.

pub fn bits(&self) -> u8

The bucket bits every partition currently holds.

pub fn num_qubits(&self) -> usize

Qubits the sum is over.

impl<const W: usize> PartitionedSum<W>

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

Splits sum across the partitions config places, by the default rows (PartitionRowPolicy::Seeded at the sum’s own hash seed); other rows go through scatter_with.

Errors

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

Panics

In debug builds, if the partition rows are not independent of the sum’s hash rows.

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

scatter onto a caller-built runtime, split by the rows options names; at P = 1 the scatter changes nothing.

Panics

If the rows do not name the runtime’s partition count, or as PartitionRows::cut. In debug builds, if the rows are not independent of the sum’s hash rows, which costs load balance but not correctness.

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

where T: TruncationPolicy<W> + ?Sized,

Propagates through circuit under policy, in place; see propagate_with.

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

where T: TruncationPolicy<W> + ?Sized,

Propagates through circuit under policy with explicit PropagateOptions, as propagate_with does unpartitioned.

The per-layer DEBUG log line comes once per partition, tagged partition r/P, from that partition’s own thread.

Panics

If options fail PropagateOptions::validate, or a channel’s preparation declines, as the unpartitioned engine does. Before the first layer, above one partition, unless policy.supports_partitioned() — exact TopN is not yet supported partitioned. A panic in any partition is re-raised on the calling thread.

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

Merges the partitions back into one sum on the calling thread, leaving self intact.

pub fn into_gathered(self) -> PauliSum<W>

gather by value — no clone of the parts.

pub fn partition(&self, r: usize) -> &PauliSum<W>

Partition r’s share of the sum.

Panics

If r is not a partition of this sum.

pub fn expectation_product(&self, basis: &ProductBasis<W>) -> Complex64

⟨ψ|O|ψ⟩ in the product state basis, the partitions’ own values added in rank order.

pub fn assert_invariants(&self)

Checks every invariant a partitioned sum holds between calls, in O(terms); release builds skip the per-partition structural check.

Panics

If a partition’s sum is internally inconsistent, holds a key of another partition, or disagrees with partition 0 about the hash rows, the bucket count or the qubit count.