Add alias sampling

[wsttiger]

Summary

Adds AliasSamplingPrepare, an implementation of the PREPARE-with-garbage construction described by Babbush et al. in arXiv:1805.03662, Sec. III.D.

Given nonnegative weights w_k, the primitive prepares a state whose index-register measurement probabilities exactly match an integer-discretized alias table. This construction is a standard state-preparation component for qubitized quantum simulation.

The implementation builds on the arithmetic primitives introduced earlier in this PR stack:

• QROM loads the (alias, keep) pair associated with each bin.
• A CDKM comparator compares the keep threshold with a uniform reference register.
• Controlled swaps replace rejected bins with their aliases.
• A hand-written adjoint reverses the complete preparation.

This PR is stacked on the reversible-arithmetic PR.

Exact, bounded discretization

The input weights are discretized to mu bits using an integer version of Vose's alias-table algorithm.

The resulting quantum circuit realizes the discretized distribution exactly. Tests compare against exact rational probabilities rather than relying only on floating-point tolerances.

For K bins, the error for each probability is bounded by

1.5 / (K * 2^mu).

The module docstring derives this bound, including why the residual-redistribution cursor cannot wrap around. Zero-weight entries and bins introduced through power-of-two padding receive exactly zero probability.

Resource costs and register layout

The implementation exposes and tests the following resource contract:

• Toffoli count:

  qrom.toffoli_count + 4 * (mu + 1)

• Fredkin count:

  num_index

The resource tests validate these formulas against the compiled kernel using cudaq.estimate_resources. They also cross-check the QROM object's reported costs against the compiled QROM circuit.

The garbage-register layout is documented field by field. Its total width is

num_garbage = num_index + 2 * mu + 4 + qrom.num_ladder.

Because qrom.num_ladder depends on the selected QROM implementation, the garbage width automatically reflects the chosen variant.

The internal QROM accepts variant= and block_size= options. The default "auto" mode evaluates the available constructions and selects the lowest-cost option. Tests also force the select_swap variant to verify that both PREPARE and its adjoint are independent of the selected QROM implementation, including clean-ladder reuse during uncomputation.

PREPARE-with-garbage contract

AliasSamplingPrepare guarantees the probability associated with each index value. It does not guarantee clean state preparation of the form

sum_k sqrt(p_k) |k>|0>.

Instead, the prepared state generally has the form

sum_k sqrt(p_k) |k>|G_k>,

where the conditional garbage states |G_k> need not be mutually orthogonal. Consequently, the reduced state of the index register is not necessarily diag(p_k).

This is sufficient for the qubitization identity

<0| PREP^dag SELECT PREP |0> = sum_k p_k U_k.

Because SELECT is diagonal in the index basis, index orthogonality eliminates cross terms regardless of overlaps between the garbage states. The class documentation states this contract explicitly so consumers do not assume clean amplitude preparation or a diagonal reduced index state.

Validation

The test suite includes:

• Exact index-marginal comparisons against independently generated alias tables.
• Brute-force enumeration of every (bin, reference) branch and comparison with circuit results.
• PREPARE-followed-by-adjoint identity checks.
• Resource-identity checks for both the default and forced QROM variants.
• Exact checks that zero-weight and padded bins remain zero.
• An independent adversarial sweep over approximately 4,000 weight tables, including:
  • Dynamic ranges from exp(-18) through exp(4).
  • Irrational weights.
  • Tables containing many zeros.
  • Precision values through mu = 8.

The adversarial sweep found no discretization-bound violations, and padded bins remained exactly zero.

At this branch tip:

• 26 tests are added by this PR.
• The complete suite reports 560 passed and 3 skipped.

Deferred work

The following extensions are deliberately left for future changes:

• Sub-bit-precision variants.
• Measurement-assisted QROM uncomputation.

Both can be introduced behind the existing QROM interface when a consumer requires the associated resource tradeoff.

[smcardleQ]

Minor comments on coherent alias sampling, otherwise looks good to merge. I have not checked the arithmetic primitives yet.

[wsttiger]

Rebased onto main now that #47 (reversible arithmetic) has merged. The two arithmetic commits this branch was stacked on are dropped, so the diff is now alias-sampling only (+707/−0 across _alias_sampling.py, its test, and the primitives/__init__ export).

One re-pricing followed from the merge: #47 landed with the one-Toffoli comparator saving (cmp_ge_register is now 2n−1, not 2n), so the PREPARE's documented Toffoli cost is qrom.toffoli_count + 2·mu − 1 — docstring and resource tests updated accordingly (the 2·mu register widths/offsets are unchanged).

Green: 26/26 test_primitives_alias_sampling.py on 0.15.1 / qpp-cpu, and yapf-clean. Ready for review.