Add alias sampling

python/cudaq_algorithms/primitives/__init__.py

@@ -1,6 +1,6 @@
 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
-"""Fault-tolerant circuit primitives: unary iteration and QROM.
+"""Fault-tolerant circuit primitives: unary iteration, QROM, arithmetic.
 
 ``unary_iteration_kernels`` mints unary iteration (Babbush et al.,
 `arXiv:1805.03662`, Fig. 7) in its strictly unitary form — no
@@ -19,15 +19,55 @@
 minted kernels actually have, and the resource tests pin them against
 the compiler.
 
+The reversible integer arithmetic device kernels (:mod:`._arithmetic`)
+are the in-place little-endian adders and comparators the lookup-based
+constructions compose with: the CDKM/Cuccaro ripple-carry family
+(``add_register`` / ``subtract_register``, ``add_constant`` /
+``subtract_constant``, ``cmp_ge_constant``, and the register-register
+comparators ``cmp_ge_register`` / ``cmp_gt_register``) and the ancilla-free Draper
+QFT family (``qft`` / ``iqft``, ``add_constant_qft`` /
+``subtract_constant_qft``, the ``cmp_ge_constant_qft`` /
+``cmp_ge_constant_qft_adj`` pair). Every inverse is hand-written and the
+gate prices are compiler-pinned by the resource tests.
+
+``AliasSamplingPrepare`` composes both: the coherent alias-sampling
+PREPARE-with-garbage of Babbush et al. (`arXiv:1805.03662`, Sec. III.D)
+— integer Vose preprocessing, a QROM lookup of the (alias, keep) table
+priced by ``variant="auto"``, and the CDKM comparator — realizing a
+weighted index-register marginal exactly, up to a derived ``mu``-bit
+discretization bound.
+
 Import the subpackage directly (``from cudaq_algorithms.primitives
 import QROM``); nothing here is re-exported from the package root.
 """
 
+from ._alias_sampling import AliasSamplingPrepare
+from ._arithmetic import (add_constant, add_constant_qft, add_register,
+                          cmp_ge_constant, cmp_ge_constant_qft,
+                          cmp_ge_constant_qft_adj, cmp_ge_register,
+                          cmp_gt_register, iqft, phase_add_constant, qft,
+                          subtract_constant, subtract_constant_qft,
+                          subtract_register)
 from ._qrom import QROM
 from ._unary_iteration import UnaryIterationKernels, unary_iteration_kernels
 
 __all__ = [
+    "AliasSamplingPrepare",
     "QROM",
     "UnaryIterationKernels",
+    "add_constant",
+    "add_constant_qft",
+    "add_register",
+    "cmp_ge_constant",
+    "cmp_ge_constant_qft",
+    "cmp_ge_constant_qft_adj",
+    "cmp_ge_register",
+    "cmp_gt_register",
+    "iqft",
+    "phase_add_constant",
+    "qft",
+    "subtract_constant",
+    "subtract_constant_qft",
+    "subtract_register",
     "unary_iteration_kernels",
 ]