Quantum Arithmetic and State Organization¶
Quantum Arithmetic (SparQ/include/quantum_arithmetic.h)¶
Quantum arithmetic operations definitions.
Implements various quantum arithmetic operations, including flip, shift, multiplication, addition, comparison, etc.
Unitarity notes¶
Quantum operators must satisfy the unitary property (U^†U = I), which requires operations to be reversible. The operators in this file fall into two categories:
Out-of-place operations (e.g. Add_UInt_UInt):
The result is stored in a separate output register
Unitarity is guaranteed by bitwise XOR: result ^= f(inputs)
Unitarity is automatic because XOR is self-inverse
In-place operations (e.g. Add_UInt_UInt_InPlace, Add_ConstUInt_InPlace):
The result directly modifies the input register
An explicit dagger() method is required to guarantee reversibility
The inverse operation is usually implemented with modular arithmetic: y = (y + (2^N - x)) % 2^N
Type safety notes¶
All operators check the following in debug mode (non-QRAM_Release):
Types of input/output registers (UnsignedInteger/SignedInteger/Boolean/Rational)
Whether register sizes match
Valid ranges of operands (e.g. the number of bits to shift)
In Release mode these checks are compiled out for the best performance.
-
namespace qram_simulator
QRAM sparse state simulator namespace.
Contains all classes, functions, and data structures related to quantum computing simulation
Typedefs
-
using GenericArithmetic = std::function<std::vector<size_t>(const std::vector<size_t>&)>¶
Generic arithmetic function type.
-
using AddAssign_AnyInt_AnyInt_InPlace = Add_AnyInt_AnyInt_InPlace¶
-
using Div_Sqrt_Arccos_Int_Int = Div_Sqrt_Arccos_UInt_UInt¶
-
using Sqrt_Div_Arccos_Int_Int = Sqrt_Div_Arccos_Int_UInt¶
-
struct Abs_SInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Signed integer absolute value operation (Out-of-place)
Implements out-of-place absolute value: res ^= |reg|, where reg is read with two’s complement sign extension
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: reg must be SignedInteger, res must be UnsignedInteger
Note
Width and truncation: reg is sign-extended to 64 bits, then the absolute value is taken; the result is then XORed into res after taking mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Note
Boundary behavior: when the input is the most negative value (INT64_MIN for w = 64), -v still wraps to itself, and the output keeps the bit pattern of the most negative value
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Abs_SInt(std::string_view reg_, std::string_view res_)¶
Constructor (name version)
- Parameters:
reg_ – Input register name
res_ – Result register name
-
inline Abs_SInt(size_t reg_, size_t res_)¶
Constructor (ID version)
- Parameters:
reg_ – Input register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the absolute value operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
struct Add_AnyInt_AnyInt_InPlace : public qram_simulator::BaseOperator¶
- #include <quantum_arithmetic.h>
Arbitrary integer accumulation operation (In-place)
Implements in-place addition: lhs += rhs, supporting signed and unsigned integers
This is an in-place operation; an explicit dagger implementation is required to guarantee unitarity. dagger implementation: lhs -= rhs (mod 2^N)
- Example
auto lhs = System::add_register("lhs", UnsignedInteger, 4); auto rhs = System::add_register("rhs", UnsignedInteger, 4); Init_Unsafe(lhs, 8); // lhs = 8 Init_Unsafe(rhs, 6); // rhs = 6 // lhs = (8 + 6) % 16 = 14 Add_AnyInt_AnyInt_InPlace("lhs", "rhs"); // dagger: lhs = (14 - 6) % 16 = 8 (restores the original value) op.dag(state);
Note
Unitarity: bijectivity is guaranteed by modular arithmetic
Note
Data type: lhs and rhs may be UnsignedInteger or SignedInteger
Note
Overflow behavior: the result wraps around modulo 2^N at the lhs register size
Note
Type combination: mixed types are supported (e.g. lhs is SignedInteger, rhs is UnsignedInteger)
Note
Read extension (width and truncation convention): rhs is extended per its declared register type – UnsignedInteger is zero-extended and SignedInteger sign-extended; width and type are read at execution time, not snapshotted at construction time
Warning
Overflow behavior of signed integers is undefined (C++ standard); use with caution
- Pre:
lhs and rhs must be of integer type (UnsignedInteger or SignedInteger, debug checked)
- Pre:
lhs and rhs must not be the same register (alias check, always-on)
- Pre:
all registers must be active
Public Functions
-
inline Add_AnyInt_AnyInt_InPlace(std::string_view reg_lhs, std::string_view reg_rhs)¶
Constructor (name version)
- Parameters:
reg_lhs – Left operand register name
reg_rhs – Right operand register name
-
inline Add_AnyInt_AnyInt_InPlace(size_t reg_lhs, size_t reg_rhs)¶
Constructor (ID version)
- Parameters:
reg_lhs – Left operand register ID
reg_rhs – Right operand register ID
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
virtual void operator()(std::vector<System> &state) const¶
Apply the accumulate operation.
- Parameters:
state – System state vector
-
virtual void dag(std::vector<System> &state) const¶
Apply the dagger operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Static Functions
-
static uint64_t _extended_rhs(const System &s, size_t id)¶
Read the right operand with extension according to the register’s declared type.
UnsignedInteger is zero-extended; SignedInteger is sign-extended (two’s complement bit pattern). Width and type are read at execution time (width and truncation convention).
- Parameters:
s – Current basis vector
id – Right operand register ID
- Returns:
The extended 64-bit bit pattern
-
struct Add_ConstUInt_InPlace : public qram_simulator::BaseOperator¶
- #include <quantum_arithmetic.h>
Add-constant operation (In-place)
Implements in-place add-constant: reg_in += add_int (mod 2^N)
This is an in-place operation; an explicit dagger implementation is required to guarantee unitarity. dagger implementation: reg_in += (2^N - add_int) mod 2^N, where N is the register bit width
- Example
auto reg = System::add_register("reg", UnsignedInteger, 4); Init_Unsafe(reg, 12); // reg = 12 // reg = (12 + 3) % 16 = 15 Add_ConstUInt_InPlace("reg", 3); // dagger: reg = (15 + 13) % 16 = 12 (restores the original value) op.dag(state);
Note
Unitarity: bijectivity is guaranteed by modular addition
Note
Data type: reg_in is recommended to be UnsignedInteger
Note
Overflow behavior: the result wraps around modulo 2^N at the register size
- Pre:
reg_in must be active
- Pre:
add_int should be less than 2^N (N is the register bit width), otherwise the behavior depends on modular arithmetic
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Add_ConstUInt_InPlace(std::string_view reg_in_, size_t add)¶
Constructor (name version)
- Parameters:
reg_in_ – Input register name (result stored here)
add – Addend constant
- Throws:
Throws – an exception when a register type is not an integer type
-
inline Add_ConstUInt_InPlace(size_t reg_in, size_t add)¶
Constructor (ID version)
- Parameters:
reg_in – Input register ID (result stored here)
add – Addend constant
- Throws:
Throws – an exception when a register type is not an integer type
-
virtual void operator()(std::vector<System> &state) const¶
Apply the add-constant operation.
- Parameters:
state – System state vector
-
virtual void dag(std::vector<System> &state) const¶
Apply the dagger operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Add_Mult_UInt_ConstUInt_InPlace : public qram_simulator::BaseOperator¶
- #include <quantum_arithmetic.h>
Accumulate multiply-by-constant operation (In-place)
Implements in-place accumulate-multiply: res += lhs * mult (mod 2^N) Note: the lhs register is not modified; only res is updated.
This is an in-place operation; an explicit dagger implementation is required to guarantee unitarity. Forward: res += lhs * mult (mod 2^N) [lhs unchanged] Dagger: res -= lhs * mult (mod 2^N) [lhs unchanged]
- Example
auto lhs = System::add_register("lhs", UnsignedInteger, 4); auto res = System::add_register("res", UnsignedInteger, 4); Init_Unsafe(lhs, 2); // lhs = 2 Init_Unsafe(res, 3); // res = 3 // res = 3 + (2 * 4) = 11 Add_Mult_UInt_ConstUInt_InPlace("lhs", 4, "res");
Note
Unitarity: lhs is unchanged, only res is updated via modular addition/subtraction; bijectivity is guaranteed by the range of lhs
Note
Data type: lhs and res should both be UnsignedInteger
Note
Overflow behavior: the result wraps around modulo 2^N at the res register size
- Pre:
the res register must have enough bits to store the result
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Add_Mult_UInt_ConstUInt_InPlace(std::string_view reg_in, size_t mult, std::string_view reg_out)¶
Constructor (name version)
- Parameters:
reg_in – Input register name
mult – Multiplier constant
reg_out – Output register name (result accumulated here)
- Throws:
Throws – an exception when a register type is not UnsignedInteger
-
inline Add_Mult_UInt_ConstUInt_InPlace(size_t reg_in, size_t mult, size_t reg_out)¶
Constructor (ID version)
- Parameters:
reg_in – Input register ID
mult – Multiplier constant
reg_out – Output register ID (result accumulated here)
- Throws:
Throws – an exception when a register type is not UnsignedInteger
-
virtual void operator()(std::vector<System> &state) const¶
Apply the accumulate-multiply operation.
- Parameters:
state – System state vector
-
virtual void dag(std::vector<System> &state) const¶
Apply the dagger operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Add_UInt_ConstUInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Unsigned integer add-constant operation (Out-of-place)
Implements out-of-place add-constant: res ^= lhs + add_int
Unitary guarantee: implemented via XOR, res = res ⊕ (lhs + add_int) Applied twice: res ⊕ (lhs + add_int) ⊕ (lhs + add_int) = res
- Example
auto lhs = System::add_register("lhs", UnsignedInteger, 4); auto res = System::add_register("res", UnsignedInteger, 4); Init_Unsafe(lhs, 6); // lhs = 6 // res = 0 ⊕ (6 + 4) = 10 Add_UInt_ConstUInt("lhs", 4, "res");
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs and res must both be UnsignedInteger
Note
Overflow behavior: the addition result is truncated to the output register size before the XOR
- Pre:
the lhs and res registers must be of UnsignedInteger type
- Pre:
all registers must be active
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Add_UInt_ConstUInt(std::string_view reg_in, size_t add, std::string_view reg_out)¶
Constructor (name version)
- Parameters:
reg_in – Input register name
add – Addend constant
reg_out – Output register name
-
inline Add_UInt_ConstUInt(size_t reg_in, size_t add, size_t reg_out)¶
Constructor (ID version)
- Parameters:
reg_in – Input register ID
add – Addend constant
reg_out – Output register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the add-constant operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Add_UInt_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Unsigned integer addition operation (Out-of-place)
Implements out-of-place addition: res ^= lhs + rhs
Unitary guarantee: implemented via XOR, res = res ⊕ (lhs + rhs) Applied twice: res ⊕ (lhs + rhs) ⊕ (lhs + rhs) = res, i.e. U^2 = I
- Example
auto lhs = System::add_register("lhs", UnsignedInteger, 4); auto rhs = System::add_register("rhs", UnsignedInteger, 4); auto res = System::add_register("res", UnsignedInteger, 4); Init_Unsafe(lhs, 3); // lhs = 3 Init_Unsafe(rhs, 5); // rhs = 5 // res = 0 ⊕ (3 + 5) = 8 Add_UInt_UInt("lhs", "rhs", "res");
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must all be UnsignedInteger
Note
Overflow behavior: the addition result is truncated to the output register size before the XOR
- Pre:
the lhs, rhs, and res registers must be of UnsignedInteger type
- Pre:
all registers must be active
- Pre:
the res register is usually initialized to 0, but may hold any value (XOR semantics)
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Add_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_)¶
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Result register name
-
inline Add_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_)¶
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the addition operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Add_UInt_UInt_InPlace : public qram_simulator::BaseOperator¶
- #include <quantum_arithmetic.h>
In-place unsigned integer addition operation (In-place)
Implements in-place addition: rhs += lhs
This is an in-place operation; an explicit dagger implementation is required to guarantee unitarity. dagger implementation: rhs += (2^N - lhs) mod 2^N, where N is the rhs register bit width
- Example
auto lhs = System::add_register("lhs", UnsignedInteger, 4); auto rhs = System::add_register("rhs", UnsignedInteger, 4); Init_Unsafe(lhs, 7); // lhs = 7 Init_Unsafe(rhs, 3); // rhs = 3 // rhs = 3 + 7 = 10 Add_UInt_UInt_InPlace("lhs", "rhs"); // dagger: rhs = 10 + (16 - 7) % 16 = 3 (restores the original value) op.dag(state);
Note
Unitarity: bijectivity is guaranteed by modular addition
Note
Data type: lhs and rhs should both be UnsignedInteger
Note
Overflow behavior: the result wraps around modulo 2^N at the rhs register size
Note
lhs and rhs may have different sizes; lhs is read as an integer, and rhs undergoes modular addition at its own bit width.
- Pre:
lhs and rhs must be active
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Add_UInt_UInt_InPlace(std::string_view lhs_, std::string_view rhs_)¶
Constructor (name version)
- Parameters:
lhs_ – Left operand register name (addend)
rhs_ – Right operand register name (augend; result stored here)
- Throws:
Throws – an exception when a register type is not UnsignedInteger or sizes do not match
-
inline Add_UInt_UInt_InPlace(size_t lhs_, size_t rhs_)¶
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID (addend)
rhs_ – Right operand register ID (augend; result stored here)
- Throws:
Throws – an exception when a register type is not UnsignedInteger or sizes do not match
-
virtual void operator()(std::vector<System> &state) const¶
Apply the in-place addition operation.
- Parameters:
state – System state vector
-
virtual void dag(std::vector<System> &state) const¶
Apply the dagger operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct And_UInt_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Unsigned integer bitwise AND operation (Out-of-place)
Implements out-of-place bitwise AND: res ^= lhs & rhs
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must all be UnsignedInteger
Note
Width and truncation: operands are zero-extended; the result is then XORed into res after taking mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline And_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_)¶
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Result register name
-
inline And_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_)¶
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the bitwise AND operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
struct Assign : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Assignment operation (Out-of-place)
Implements register copy: register_2 ^= register_1
This is the standard implementation of the “copy” operation in quantum computing. Implemented via XOR; applying it twice restores the original value.
- Example
auto src = System::add_register("src", UnsignedInteger, 4); auto dst = System::add_register("dst", UnsignedInteger, 4); Init_Unsafe(src, 7); // src = 7 Init_Unsafe(dst, 0); // dst = 0 // dst = 0 ⊕ 7 = 7 Assign("src", "dst"); // Applied again: dst = 7 ⊕ 7 = 0 (restores the original value) Assign("src", "dst");
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: any type, as long as the two registers have the same size
Note
Semantics: register_2 = register_2 ⊕ register_1 If register_2 is initially 0, the effect is register_2 = register_1
- Pre:
register_1 and register_2 must have the same size
- Pre:
all registers must be active
Public Functions
-
inline Assign(std::string_view reg1, std::string_view reg2)¶
Constructor (name version)
- Parameters:
reg1 – First register name
reg2 – Second register name
-
inline Assign(size_t reg1, size_t reg2)¶
Constructor (ID version)
- Parameters:
reg1 – First register ID
reg2 – Second register ID
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
virtual void operator()(std::vector<System> &state) const¶
Apply the assignment operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Carry_UInt_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Unsigned addition carry flag operation (Out-of-place flag operator)
Reports the carry-out of lhs + rhs relative to res width w: flag ^= carry_out_w(lhs + rhs)
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must be UnsignedInteger, flag must be Boolean (width 1)
Note
The out parameter only provides the width and its value is never read: res is only used to determine the target width w of the carry test, this operator does not read or write res (docs/operators.md “Width and Truncation Convention”)
Note
The predicate is evaluated on the full-precision domain: when w = 64 it is decided by 64-bit wraparound, when w < 64 it is decided by a + b >= 2^w
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Carry_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_, std::string_view flag_)¶
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Name of the out register providing the target width
flag_ – Register name of the carry result flag
-
inline Carry_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_, size_t flag_)¶
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – ID of the out register providing the target width
flag_ – Register ID of the carry result flag
-
virtual void operator()(std::vector<System> &state) const¶
Apply the carry flag operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
struct Compare_UInt_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Unsigned integer comparison operation (Out-of-place)
Compares two unsigned integers, outputting the less-than and equal flags
Implementation:
compare_less_id ^= (left < right)
compare_equal_id ^= (left == right)
- Example
auto left = System::add_register("left", UnsignedInteger, 4); auto right = System::add_register("right", UnsignedInteger, 4); auto less = System::add_register("less", Boolean, 1); auto equal = System::add_register("equal", Boolean, 1); Init_Unsafe(left, 3); Init_Unsafe(right, 5); // less = (3 < 5) = 1, equal = (3 == 5) = 0 Compare_UInt_UInt("left", "right", "less", "equal");
Note
Unitarity: self-adjoint operator, implemented via XOR
Note
Data type: left_id and right_id must be UnsignedInteger; compare_less_id and compare_equal_id must be Boolean
Note
Semantics: the output flags are XORed into the result registers; if initially 0, the comparison result is stored directly
- Pre:
left_id and right_id must be of UnsignedInteger type
- Pre:
compare_less_id and compare_equal_id must be of Boolean type (size 1)
- Pre:
all registers must be active
Public Functions
-
inline Compare_UInt_UInt(std::string_view left_register, std::string_view right_register, std::string_view compare_less, std::string_view compare_equal)¶
Constructor (name version)
- Parameters:
left_register – Left operand register name
right_register – Right operand register name
compare_less – Register name of the less-than result
compare_equal – Register name of the equality result
-
inline Compare_UInt_UInt(size_t lreg, size_t rreg, size_t compare_less, size_t compare_equal)¶
Constructor (ID version)
- Parameters:
lreg – Left operand register ID
rreg – Right operand register ID
compare_less – Register ID of the less-than result
compare_equal – Register ID of the equality result
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
virtual void operator()(std::vector<System> &state) const¶
Apply the comparison operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct CustomArithmetic : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Custom arithmetic operation (Out-of-place)
Allows the user to define a custom arithmetic function and apply it to the quantum state
The user can provide a function func: vector<size_t> -> vector<size_t>, The operation passes the input register values to func and then XORs the output into the output registers.
────────────────────────────────────────────────────────────────────────
The current implementation is a **”simulator privilege” primitive**: on each basis state of the
SparseState it directly calls a host C++ / Python callback func, XORing f(x) into the output register. This is equivalent to an idealized oracle U_f|x⟩|y⟩ = |x⟩|y ⊕ f(x)⟩, but with no corresponding physical quantum circuit – real hardware cannot “read out basis state values and then call an arbitrary function”. Therefore:- Design notes: the “simulator privilege” semantics of CustomArithmetic and its future evolution
CustomArithmetic is only meaningful in a sparse state simulator;
Any pass that “lowers an algorithm to a physical backend / Clifford+T / OriginIR” should not treat CustomArithmetic as a valid target primitive;
Upper-layer DSLs (e.g. qec_compiler/dsl_runtime/dsl) should not allow YAML composites to reference CustomArithmetic directly, otherwise the compiled circuit cannot be physically executed.
By analogy with the C standard library: sin/exp/log in math.h are not CPU instructions; libm implements them with a software library from a small set of ALU primitives (+, −, ×, ÷, FMA, sqrt) + range reduction + polynomial approximation + table lookup. Similarly, in the quantum world we should:
- Future evolution: build quantum-libm + intelligent lowering strategy
┌──────────────────────────────────────────────────────────────────┐ │ Tier 0 — quantum arithmetic ISA: │ │ QAdd / QSub / QMul / QDiv / QMod / QShift / QSwap / Toffoli / │ │ multi-controlled X, Clifford+T basis, and other existing primitives │ ├──────────────────────────────────────────────────────────────────┤ │ Tier 1 — reciprocal / square root / modular inverse (Newton iteration over Tier 0) │ ├──────────────────────────────────────────────────────────────────┤ │ Tier 2 — elementary functions: sin/cos/exp/log via range reduction + │ │ polynomial + QROM coefficient table lookup + Horner (all composed from Tier 0 / Tier 1) │ ├──────────────────────────────────────────────────────────────────┤ │ Tier 3 — black-box lookup tables: QROM / SELECT-SWAP (Babbush et al. 2018) │ │ Suitable for small discrete domains; expands into an O(2^n) multi-controlled X chain │ └──────────────────────────────────────────────────────────────────┘
Under this architecture, CustomArithmetic is no longer an endpoint but a trait interface:
It accepts the user-provided func along with metadata such as domain / precision / target backend;
An intelligent lowering strategy selector chooses the landing path based on this information:
Domain <= 2^k (k small, typically k <= 8) -> QROM expansion
func is a polynomial / analytic smooth function -> polynomial approximation + Horner
func is structured arithmetic such as modular exponentiation / modular multiplication -> use dedicated primitives such as Mod_Mult directly
Simulator-only target and func is hard to decompose -> keep as a host callback (i.e. current behavior)
The selector need not be simple code, but a cost model considering N (bit width), ε (error budget), T-count budget, fault tolerance, and other multi-dimensional constraints.
The controlled modular exponentiation in Shor’s algorithm should not take the CustomArithmetic route – it is essentially a controlled-Mod_Mult chain (an in-place operation), whereas CustomArithmetic’s XOR semantics only describe the out-of-place |x⟩|y⟩→|x⟩|y⊕f(x)⟩, and LUT expansion would prevent Shor from scaling to 2048 bits. The correct approach is to call Mod_Mult_UInt_ConstUInt_InPlace directly, accumulating the product over j = 0..2n-1 of a^(2^j) mod N, each factor controlled by bit j of work_reg. Shor’s lowering optimizations (windowed arithmetic, Beauregard, Häner-Roetteler- Soeken, etc.) are all built on this in-place chain rather than on LUTs.
- Special note on Shor (mod-pow)
- Example
// Custom function: output = input * 2 GenericArithmetic double_func = [](const std::vector<size_t>& inputs) { return std::vector<size_t>{inputs[0] * 2}; }; auto inp = System::add_register("inp", UnsignedInteger, 4); auto out = System::add_register("out", UnsignedInteger, 4); Init_Unsafe(inp, 7); // inp = 7 std::vector<std::string> regs = {"inp", "out"}; CustomArithmetic arith(regs, 1, 1, double_func); // out = 0 ⊕ (7 * 2) = 14 arith(state);
Note
Unitarity: self-adjoint operator (U^† = U), because it is implemented with XOR
Note
Constraint: func must be a deterministic pure function, otherwise unitarity cannot be guaranteed
Warning
Until this architecture lands, please treat CustomArithmetic as a “simulator-only oracle”; do not reference it in algorithm descriptions targeting physical hardware (DSL composites, IR codegen passes). ────────────────────────────────────────────────────────────────────────
Warning
The user is responsible for ensuring func does not cause information loss (i.e. func should be a deterministic function of its input)
- Pre:
the numbers of input and output registers must be correctly specified in the constructor
- Pre:
func must be deterministic (the same input always produces the same output)
- Pre:
all registers must be active
Public Functions
-
inline CustomArithmetic(const std::vector<size_t> &input_registers, size_t input_size, size_t output_size, GenericArithmetic func)¶
Constructor (ID version)
- Parameters:
input_registers – List of input register IDs
input_size – Number of input registers
output_size – Number of output registers
func – Custom arithmetic function
- Throws:
Throws – an exception when input and output sizes do not match
-
inline CustomArithmetic(const std::vector<std::string> &input_registers, size_t input_size, size_t output_size, GenericArithmetic func)¶
Constructor (name version)
- Parameters:
input_registers – List of input register names
input_size – Number of input registers
output_size – Number of output registers
func – Custom arithmetic function
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline virtual void operator()(std::vector<System> &state) const¶
Apply the custom arithmetic operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
GenericArithmetic func¶
Custom arithmetic function.
-
struct Div_Sqrt_Arccos_UInt_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Division square-root arccosine operation (Out-of-place)
Implements: res ^= arccos(sqrt(lhs / rhs)) / π / 2
Used to compute quantum rotation angles, common in quantum machine learning algorithms.
- Mathematical formula
output = arccos(√(lhs / rhs)) / (2π)
- Example
auto lhs = System::add_register("lhs", UnsignedInteger, 4); auto rhs = System::add_register("rhs", UnsignedInteger, 4); auto res = System::add_register("res", Rational, 8); Init_Unsafe(lhs, 1); // lhs = 1 Init_Unsafe(rhs, 4); // rhs = 4 // res = arccos(sqrt(1/4)) / 2π = arccos(0.5) / 2π = 1/6 ≈ 0.167 Div_Sqrt_Arccos_UInt_UInt("lhs", "rhs", "res");
Note
Unitarity: self-adjoint operator, implemented via XOR
Note
Data type: lhs and rhs must be UnsignedInteger, res must be Rational
Note
Numeric range: the result is in [0, 0.5], encoded as a rational
- Pre:
lhs and rhs must be of UnsignedInteger type
- Pre:
res must be of Rational type
- Pre:
lhs < rhs (otherwise the sqrt argument exceeds the [0,1] range and may produce NaN)
- Pre:
all registers must be active
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Div_Sqrt_Arccos_UInt_UInt(std::string_view register_lhs, std::string_view register_rhs, std::string_view register_out)¶
Constructor (name version)
- Parameters:
register_lhs – Left operand register name
register_rhs – Right operand register name
register_out – Output register name
-
inline Div_Sqrt_Arccos_UInt_UInt(size_t reg_lhs, size_t reg_rhs, size_t reg_out)¶
Constructor (ID version)
- Parameters:
reg_lhs – Left operand register ID
reg_rhs – Right operand register ID
reg_out – Output register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the arithmetic operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Div_UInt_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Unsigned integer division operation (Out-of-place)
Implements out-of-place division: res ^= lhs / rhs (integer division, rounding down)
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must all be UnsignedInteger
Note
Total domain: when the divisor is zero the quotient is 0 and no domain exception is thrown (reversibility requires the operator to be a deterministic function on all basis vectors; docs/operators.md “Width and Truncation Convention”); overflow information is reported separately by dedicated flag operators
Note
Width and truncation: operands are zero-extended, quotient domain <= 64 bits, then XORed into res after taking mod 2^res_width
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Div_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_)¶
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Result register name
-
inline Div_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_)¶
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the division operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
struct FlipBools : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Boolean flip operation.
Flips all bits in the register (bitwise NOT), implementing y = ~y
- Example
// 4-bit register, initial value 0b1010 (10) FlipBools("reg"); // Result: 0b0101 (5)
Note
Unitarity: self-adjoint operator (SelfAdjointOperator), i.e. U^† = U
Note
Data type: any integer type (UnsignedInteger/SignedInteger)
Note
Overflow behavior: only bits within the register size are affected; high bits are flipped but truncated by the mask
- Pre:
the input register must be active
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline FlipBools(size_t id_)¶
Constructor (ID version)
- Parameters:
id_ – Register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the flip operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct GetMid_UInt_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Get midpoint operation (Out-of-place)
Computes the midpoint of two unsigned integers: mid ^= (left + right) / 2
Commonly used for binary search and midpoint computation in quantum algorithms.
- Example
auto left = System::add_register("left", UnsignedInteger, 4); auto right = System::add_register("right", UnsignedInteger, 4); auto mid = System::add_register("mid", UnsignedInteger, 4); Init_Unsafe(left, 0); Init_Unsafe(right, 10); // mid = (0 + 10) / 2 = 5 GetMid_UInt_UInt("left", "right", "mid");
Note
Unitarity: self-adjoint operator, implemented via XOR
Note
Data type: left_id, right_id, and mid_id must all be UnsignedInteger
Note
Overflow behavior: the addition may overflow, but the result after division is correct (integer division, rounding down)
- Pre:
left_id, right_id, and mid_id must be of UnsignedInteger type
- Pre:
the three registers must have the same size
- Pre:
all registers must be active
Public Functions
-
inline GetMid_UInt_UInt(std::string_view left_register_, std::string_view right_register_, std::string_view mid_register_)¶
Constructor (name version)
- Parameters:
left_register_ – Left operand register name
right_register_ – Right operand register name
mid_register_ – Midpoint result register name
-
inline GetMid_UInt_UInt(size_t left_register_, size_t right_register_, size_t mid_register_)¶
Constructor (ID version)
- Parameters:
left_register_ – Left operand register ID
right_register_ – Right operand register ID
mid_register_ – Midpoint result register ID
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
virtual void operator()(std::vector<System> &state) const¶
Apply the midpoint computation operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct GetRotateAngle_Int_Int : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Get rotation angle operation (Out-of-place)
Computes the polar angle from lhs to rhs: res ^= atan2(rhs, lhs) / (2π)
Converts the Cartesian coordinates (lhs, rhs) to a polar angle; the result is encoded in the range [0, 1).
- Mathematical formula
If lhs == 0 and rhs >= 0: output = 0.25 (90°)
If lhs == 0 and rhs < 0: output = 0.75 (270°)
Otherwise: output = atan2(rhs, lhs) / (2π) normalized to [0,1)
- Example
auto lhs = System::add_register("lhs", SignedInteger, 4); auto rhs = System::add_register("rhs", SignedInteger, 4); auto res = System::add_register("res", Rational, 8); Init_Unsafe(lhs, 1); // lhs = 1 Init_Unsafe(rhs, 1); // rhs = 1 // res = atan2(1, 1) / 2π = 0.125 (45°) GetRotateAngle_Int_Int("lhs", "rhs", "res");
Note
Unitarity: self-adjoint operator, implemented via XOR
Note
Data type: lhs and rhs may be SignedInteger or UnsignedInteger, res must be Rational
Note
Numeric range: the result is in [0, 1) (a normalized angle)
- Pre:
res must be of Rational type
- Pre:
all registers must be active
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline GetRotateAngle_Int_Int(std::string_view reg_lhs, std::string_view reg_rhs, std::string_view reg_out)¶
Constructor (name version)
- Parameters:
reg_lhs – Left operand register name
reg_rhs – Right operand register name
reg_out – Output register name
-
inline GetRotateAngle_Int_Int(size_t reg_lhs, size_t reg_rhs, size_t reg_out)¶
Constructor (ID version)
- Parameters:
reg_lhs – Left operand register ID
reg_rhs – Right operand register ID
reg_out – Output register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the arithmetic operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct IsZero_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Unsigned integer zero-test operation (Out-of-place flag operator)
Implements out-of-place zero test: flag ^= (reg == 0)
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: reg must be UnsignedInteger, flag must be Boolean (width 1)
Note
The predicate is evaluated on the full-precision domain: operands are zero-extended and compared with 0 (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline IsZero_UInt(std::string_view reg_, std::string_view flag_)¶
Constructor (name version)
- Parameters:
reg_ – Input register name
flag_ – Register name of the zero-test result flag
-
inline IsZero_UInt(size_t reg_, size_t flag_)¶
Constructor (ID version)
- Parameters:
reg_ – Input register ID
flag_ – Register ID of the zero-test result flag
-
virtual void operator()(std::vector<System> &state) const¶
Apply the zero-test operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
struct Less_SInt_SInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Signed integer less-than comparison operation (Out-of-place)
Implements out-of-place signed comparison: flag ^= (lhs < rhs)
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs and rhs must be SignedInteger, flag must be Boolean (width 1)
Note
The predicate is evaluated on the full-precision domain: operands are sign-extended to 64 bits and then compared (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Less_SInt_SInt(std::string_view lhs_, std::string_view rhs_, std::string_view flag_)¶
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
flag_ – Register name of the less-than result flag
-
inline Less_SInt_SInt(size_t lhs_, size_t rhs_, size_t flag_)¶
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
flag_ – Register ID of the less-than result flag
-
virtual void operator()(std::vector<System> &state) const¶
Apply the signed less-than comparison operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
struct Less_UInt_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Less-than comparison operation (Out-of-place)
Compares two unsigned integers, outputting only the less-than flag
Implementation: compare_less_id ^= (left < right)
- Example
auto left = System::add_register("left", UnsignedInteger, 4); auto right = System::add_register("right", UnsignedInteger, 4); auto less = System::add_register("less", Boolean, 1); Init_Unsafe(left, 3); Init_Unsafe(right, 5); // less = (3 < 5) = 1 Less_UInt_UInt("left", "right", "less");
Note
Unitarity: self-adjoint operator, implemented via XOR
Note
Data type: left_id and right_id must be UnsignedInteger, compare_less_id must be Boolean
Note
Semantics: the output flags are XORed into the result registers; if initially 0, the comparison result is stored directly
- Pre:
left_id and right_id must be of UnsignedInteger type
- Pre:
compare_less_id must be of Boolean type (size 1)
- Pre:
all registers must be active
Public Functions
-
inline Less_UInt_UInt(std::string_view lreg, std::string_view rreg, std::string_view compare_less)¶
Constructor (name version)
- Parameters:
lreg – Left operand register name
rreg – Right operand register name
compare_less – Register name of the less-than result
-
inline Less_UInt_UInt(size_t lreg, size_t rreg, size_t compare_less)¶
Constructor (ID version)
- Parameters:
lreg – Left operand register ID
rreg – Right operand register ID
compare_less – Register ID of the less-than result
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
virtual void operator()(std::vector<System> &state) const¶
Apply the less-than comparison operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Mod_Mult_UInt_ConstUInt_InPlace : public qram_simulator::BaseOperator¶
- #include <quantum_arithmetic.h>
Modular multiplication.
Computes |y⟩ → |y * a^(2^x) mod N⟩
When a and N are coprime, Mod_Mult_UInt_ConstUInt_InPlace is a unitary operation.
Unitarity notes for Mod_Mult_UInt_ConstUInt_InPlace¶
Unitarity conditions for Mod_Mult_UInt_ConstUInt_InPlace:
a and N must be coprime (gcd(a, N) = 1)
When the condition holds, the inverse operation is y * a^(2^x*(N-2)) mod N (Fermat’s little theorem)
Usage example¶
auto reg = System::add_register("y", UnsignedInteger, 4); auto cond = System::add_register("ctrl", Boolean, 1); Mod_Mult_UInt_ConstUInt_InPlace(reg, 7, 2, 15).conditioned_by_all_ones(cond)(state); // Computes: y = y * 7^4 mod 15 = y * 4 mod 15
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
Mod_Mult_UInt_ConstUInt_InPlace(std::string_view reg_name, uint64_t a, uint64_t x, uint64_t N)¶
Constructor (name version)
- Parameters:
reg_name – Operand register name
a – Base
x – Exponent bit
N – Modulus
- Throws:
Throws – an exception when a and N are not coprime
-
Mod_Mult_UInt_ConstUInt_InPlace(size_t reg_id, uint64_t a, uint64_t x, uint64_t N)¶
Constructor (ID version)
- Parameters:
reg_id – Operand register ID
a – Base
x – Exponent bit
N – Modulus
- Throws:
Throws – an exception when a and N are not coprime
-
virtual void operator()(std::vector<System> &state) const¶
Execute the modular multiplication.
- Parameters:
state – System state vector
-
virtual void dag(std::vector<System> &state) const¶
Execute the inverse modular multiplication.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Mul_UInt_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Unsigned integer multiplication operation (Out-of-place)
Implements out-of-place multiplication: res ^= lhs * rhs
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must all be UnsignedInteger
Note
Width and truncation: operands are zero-extended; the low 64 bits of the full-precision 128-bit product are taken, then XORed into res after taking mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Mul_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_)¶
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Result register name
-
inline Mul_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_)¶
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the multiplication operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
struct MulOverflow_UInt_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Unsigned multiplication overflow flag operation (Out-of-place flag operator)
Reports whether lhs * rhs exceeds the representable range of res width w: flag ^= (lhs * rhs not contained in w bits)
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must be UnsignedInteger, flag must be Boolean (width 1)
Note
The out parameter only provides the width and its value is never read: res is only used to determine the target width w of the overflow test, this operator does not read or write res (docs/operators.md “Width and Truncation Convention”)
Note
The predicate is evaluated on the full-precision domain: the product is decomposed into 64-bit high/low halves (equivalent to 128-bit precision), overflow is decided when the high 64 bits are nonzero or the low 64 bits exceed the w-bit range
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline MulOverflow_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_, std::string_view flag_)¶
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Name of the out register providing the target width
flag_ – Register name of the overflow result flag
-
inline MulOverflow_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_, size_t flag_)¶
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – ID of the out register providing the target width
flag_ – Register ID of the overflow result flag
-
virtual void operator()(std::vector<System> &state) const¶
Apply the multiplication overflow flag operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
struct Mult_UInt_ConstUInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Unsigned integer multiply-by-constant operation (Out-of-place)
Implements out-of-place multiplication: res ^= lhs * mult
Unitary guarantee: implemented via XOR, res = res ⊕ (lhs * mult) Applied twice: res ⊕ (lhs * mult) ⊕ (lhs * mult) = res, i.e. U^2 = I
- Example
auto lhs = System::add_register("lhs", UnsignedInteger, 4); auto res = System::add_register("res", UnsignedInteger, 4); Init_Unsafe(lhs, 3); // lhs = 3 // res = 0 ⊕ (3 * 4) = 12 Mult_UInt_ConstUInt("lhs", 4, "res");
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: both input and output must be UnsignedInteger
Note
Overflow behavior: the multiplication result is truncated to the output register size
- Pre:
the lhs and res registers must be of UnsignedInteger type
- Pre:
all registers must be active
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Mult_UInt_ConstUInt(std::string_view reg_in, size_t mult, std::string_view reg_out)¶
Constructor (name version)
- Parameters:
reg_in – Input register name
mult – Multiplier constant
reg_out – Output register name
-
inline Mult_UInt_ConstUInt(size_t reg_in, size_t mult, size_t reg_out)¶
Constructor (ID version)
- Parameters:
reg_in – Input register ID
mult – Multiplier constant
reg_out – Output register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the multiplication operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Neg_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Unsigned integer negation operation (Out-of-place)
Implements out-of-place negation: res ^= 0 - reg
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: reg and res must both be UnsignedInteger
Note
Width and truncation: operands are zero-extended; negative values are evaluated on the unsigned 64-bit wrapping domain (equivalent to 64-bit two’s complement negation), then XORed into res after mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Neg_UInt(std::string_view reg_, std::string_view res_)¶
Constructor (name version)
- Parameters:
reg_ – Input register name
res_ – Result register name
-
inline Neg_UInt(size_t reg_, size_t res_)¶
Constructor (ID version)
- Parameters:
reg_ – Input register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the negation operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
struct Negative_SInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Signed integer negative-test operation (Out-of-place flag operator)
Implements out-of-place negative test: flag ^= (reg < 0)
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: reg must be SignedInteger, flag must be Boolean (width 1)
Note
The predicate is evaluated on the full-precision domain: operands are two’s complement sign-extended and compared with 0 (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Negative_SInt(std::string_view reg_, std::string_view flag_)¶
Constructor (name version)
- Parameters:
reg_ – Input register name
flag_ – Register name of the negative-test result flag
-
inline Negative_SInt(size_t reg_, size_t flag_)¶
Constructor (ID version)
- Parameters:
reg_ – Input register ID
flag_ – Register ID of the negative-test result flag
-
virtual void operator()(std::vector<System> &state) const¶
Apply the negative-test operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
struct Or_UInt_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Unsigned integer bitwise OR operation (Out-of-place)
Implements out-of-place bitwise OR: res ^= lhs | rhs
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must all be UnsignedInteger
Note
Width and truncation: operands are zero-extended; the result is then XORed into res after taking mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Or_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_)¶
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Result register name
-
inline Or_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_)¶
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the bitwise OR operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
struct Overflow_SInt_SInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Signed addition overflow flag operation (Out-of-place flag operator)
Reports signed overflow of lhs + rhs relative to res width w: flag ^= overflow_w(lhs + rhs)
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs and rhs must be SignedInteger, res must be UnsignedInteger, flag must be Boolean (width 1)
Note
The out parameter only provides the width and its value is never read: res is only used to determine the target width w of the overflow test, this operator does not read or write res (docs/operators.md “Width and Truncation Convention”)
Note
The predicate is evaluated on the full-precision domain: operands are sign-extended, truncated to w bits, and decided by same-sign addition with the result changing sign
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Overflow_SInt_SInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_, std::string_view flag_)¶
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Name of the out register providing the target width
flag_ – Register name of the overflow result flag
-
inline Overflow_SInt_SInt(size_t lhs_, size_t rhs_, size_t res_, size_t flag_)¶
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – ID of the out register providing the target width
flag_ – Register ID of the overflow result flag
-
virtual void operator()(std::vector<System> &state) const¶
Apply the overflow flag operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
struct Select_Bool_UInt_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Boolean conditional select operation (Out-of-place)
Implements out-of-place two-way select: res ^= (cond ? lhs : rhs), cond reads bit 0
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: cond must be Boolean (width 1), lhs, rhs, and res must all be UnsignedInteger
Note
Width and truncation: operands are zero-extended; the selected value is then XORed into res after taking mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Select_Bool_UInt_UInt(std::string_view cond_, std::string_view lhs_, std::string_view rhs_, std::string_view res_)¶
Constructor (name version)
- Parameters:
cond_ – Condition register name
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Result register name
-
inline Select_Bool_UInt_UInt(size_t cond_, size_t lhs_, size_t rhs_, size_t res_)¶
Constructor (ID version)
- Parameters:
cond_ – Condition register ID
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the conditional select operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
struct ShiftLeft_InPlace : public qram_simulator::BaseOperator¶
- #include <quantum_arithmetic.h>
Rotate-left operation.
Rotates the register value left by the specified number of bits; the overflowing high bits wrap around to the low bits
Mathematical definition: y = (y << digit) | (y >> (N - digit)), where N is the register bit width
- Example
// 4-bit register, initial value 0b1010 ShiftLeft_InPlace("reg", 1); // Result: 0b0101 (rotate left by 1 bit) ShiftLeft_InPlace("reg", 2); // Result: 0b1010 (rotate left by 2 bits)
Note
Unitarity: rotation is a bijection, guaranteeing unitarity
Note
dagger operation: the dagger of a left rotation by d bits is a right rotation by d bits (or a left rotation by N-d bits)
Note
Data type: UnsignedInteger recommended, may also be used with SignedInteger
- Pre:
register_1 must be active
- Pre:
digit <= register size (digit == size is equivalent to the identity operation)
Public Functions
-
virtual void dag(std::vector<System> &state) const¶
Apply the dagger operation (calls ShiftRight_InPlace)
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline ShiftLeft_InPlace(std::string_view reg1, size_t d)¶
Constructor (name version)
- Parameters:
reg1 – Register name
d – Number of bits to shift
- Throws:
Throws – an exception when a register type is not an integer type
-
inline ShiftLeft_InPlace(size_t reg1, size_t d)¶
Constructor (ID version)
- Parameters:
reg1 – Register ID
d – Number of bits to shift
- Throws:
Throws – an exception when a register type is not an integer type
-
struct ShiftRight_InPlace : public qram_simulator::BaseOperator¶
- #include <quantum_arithmetic.h>
Rotate-right operation.
Rotates the register value right by the specified number of bits; the overflowing low bits wrap around to the high bits
Mathematical definition: y = (y >> digit) | (y << (N - digit)), where N is the register bit width
- Example
// 4-bit register, initial value 0b1010 ShiftRight_InPlace("reg", 1); // Result: 0b0101 (rotate right by 1 bit)
Note
Unitarity: rotation is a bijection, guaranteeing unitarity
Note
dagger operation: the dagger of a right rotation by d bits is a left rotation by d bits (or a right rotation by N-d bits)
Note
Data type: UnsignedInteger recommended, may also be used with SignedInteger
- Pre:
register_1 must be active
- Pre:
digit <= register size (digit == size is equivalent to the identity operation)
Public Functions
-
virtual void dag(std::vector<System> &state) const¶
Apply the dagger operation (calls ShiftLeft_InPlace)
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline ShiftRight_InPlace(std::string_view reg1, size_t d)¶
Constructor (name version)
- Parameters:
reg1 – Register name
d – Number of bits to shift
- Throws:
Throws – an exception when a register type is not an integer type
-
inline ShiftRight_InPlace(size_t reg1, size_t d)¶
Constructor (ID version)
- Parameters:
reg1 – Register ID
d – Number of bits to shift
- Throws:
Throws – an exception when a register type is not an integer type
-
struct Sqrt_Div_Arccos_Int_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Square-root division arccosine operation (Out-of-place)
Implements: res ^= arccos(lhs / sqrt(rhs)) / π / 2
Used to compute quantum rotation angles, common in quantum amplitude encoding.
- Mathematical formula
output = arccos(lhs / √rhs) / (2π)
- Example
auto lhs = System::add_register("lhs", SignedInteger, 4); auto rhs = System::add_register("rhs", UnsignedInteger, 4); auto res = System::add_register("res", Rational, 8); Init_Unsafe(lhs, 1); // lhs = 1 Init_Unsafe(rhs, 4); // rhs = 4 // res = arccos(1/2) / 2π = 1/6 ≈ 0.167 Sqrt_Div_Arccos_Int_UInt("lhs", "rhs", "res");
Note
Unitarity: self-adjoint operator, implemented via XOR
Note
Data type: lhs must be SignedInteger, rhs must be UnsignedInteger, res must be Rational
Note
Numeric range: the result is in [0, 1), encoded as a rational
- Pre:
lhs must be of SignedInteger type
- Pre:
rhs must be of UnsignedInteger type
- Pre:
res must be of Rational type
- Pre:
|lhs| <= sqrt(rhs) (guarantees the arccos argument is within [-1,1])
- Pre:
all registers must be active
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Sqrt_Div_Arccos_Int_UInt(std::string_view lhs, std::string_view rhs, std::string_view out)¶
Constructor (name version)
- Parameters:
lhs – Left operand register name
rhs – Right operand register name
out – Output register name
-
inline Sqrt_Div_Arccos_Int_UInt(size_t reg_lhs, size_t reg_rhs, size_t reg_out)¶
Constructor (ID version)
- Parameters:
reg_lhs – Left operand register ID
reg_rhs – Right operand register ID
reg_out – Output register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the arithmetic operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Sqrt_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Unsigned integer square root operation (Out-of-place)
Implements out-of-place square root: res ^= floor(sqrt(reg))
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: reg and res must both be UnsignedInteger
Note
Implementation detail: a pure integer bit-by-bit square root algorithm (isqrt_u64) with no floating point involved, CPU and CUDA results are bit-for-bit identical
Note
Width and truncation: operands are zero-extended, quotient domain <= 64 bits, then XORed into res after taking mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Sqrt_UInt(std::string_view reg_, std::string_view res_)¶
Constructor (name version)
- Parameters:
reg_ – Input register name
res_ – Result register name
-
inline Sqrt_UInt(size_t reg_, size_t res_)¶
Constructor (ID version)
- Parameters:
reg_ – Input register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the square root operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
struct Sub_UInt_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Unsigned integer subtraction operation (Out-of-place)
Implements out-of-place subtraction: res ^= lhs - rhs
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must all be UnsignedInteger
Note
Width and truncation: operands are zero-extended; the difference is evaluated on the unsigned 64-bit wrapping domain, then XORed into res after taking mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Sub_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_)¶
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Result register name
-
inline Sub_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_)¶
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the subtraction operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
struct Swap_Bool_Bool : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Two-bit swap operation.
Swaps single bits at the specified positions of two registers
Implementation: swaps the values of the specified bits of the two registers using a temporary variable This is a self-adjoint operation; applying it twice yields the identity operation
- Example
// reg1 = 0b1010, reg2 = 0b0101 Swap_Bool_Bool("reg1", 0, "reg2", 1); // Swaps bit 0 of reg1 and bit 1 of reg2
Note
Unitarity: self-adjoint operator, Swap^2 = I
Note
Data type: boolean bits of registers of any type
- Pre:
the lhs and rhs registers must be active
- Pre:
digit1 and digit2 must be within the valid bit range of their registers [0, size)
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Swap_Bool_Bool(std::string_view reg1, size_t d1, std::string_view reg2, size_t d2)¶
Constructor (name version)
- Parameters:
reg1 – First register name
d1 – First bit index
reg2 – Second register name
d2 – Second bit index
- Throws:
Throws – an exception when a bit index is out of the register size
-
inline Swap_Bool_Bool(size_t id1, size_t d1, size_t id2, size_t d2)¶
Constructor (ID version)
- Parameters:
id1 – First register ID
d1 – First bit index
id2 – Second register ID
d2 – Second bit index
- Throws:
Throws – an exception when a bit index is out of the register size
-
virtual void operator()(std::vector<System> &state) const¶
Apply the swap operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Swap_General_General : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
General swap operation (In-place)
Swaps the complete values of two registers
Implementation: swaps the value fields of the two registers using std::swap. This is a self-adjoint operation; applying it twice yields the identity operation.
- Example
auto reg1 = System::add_register("reg1", UnsignedInteger, 4); auto reg2 = System::add_register("reg2", UnsignedInteger, 4); Init_Unsafe(reg1, 5); // reg1 = 5 Init_Unsafe(reg2, 10); // reg2 = 10 // After the swap: reg1 = 10, reg2 = 5 Swap_General_General("reg1", "reg2");
Note
Unitarity: self-adjoint operator, Swap^2 = I
Note
Data type: any type, but the two registers must have the same size
Note
Implementation detail: register values are swapped directly, without XOR or arithmetic operations
- Pre:
id1 and id2 must have the same size
- Pre:
all registers must be active
Public Functions
-
inline Swap_General_General(std::string_view regname1, std::string_view regname2)¶
Constructor (name version)
- Parameters:
regname1 – First register name
regname2 – Second register name
- Throws:
Throws – an exception when register sizes do not match
-
inline Swap_General_General(size_t regname1, size_t regname2)¶
Constructor (ID version)
- Parameters:
regname1 – First register ID
regname2 – Second register ID
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
virtual void operator()(std::vector<System> &state) const¶
Apply the swap operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Xor_UInt_UInt : public qram_simulator::SelfAdjointOperator¶
- #include <quantum_arithmetic.h>
Unsigned integer bitwise XOR operation (Out-of-place)
Implements out-of-place bitwise XOR: res ^= lhs ^ rhs
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must all be UnsignedInteger
Note
Width and truncation: operands are zero-extended; the result is then XORed into res after taking mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Xor_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_)¶
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Result register name
-
inline Xor_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_)¶
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the bitwise XOR operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
using GenericArithmetic = std::function<std::vector<size_t>(const std::vector<size_t>&)>¶
Parallel Phase Operations (SparQ/include/parallel_phase_operations.h)¶
Parallel phase operation definitions.
Implements parallel conditional phase flips and global phase operations, supporting zero-conditional phase flips, range-conditional phase flips and reflection operations
-
namespace qram_simulator
QRAM sparse state simulator namespace.
Contains all classes, functions, and data structures related to quantum computing simulation
Typedefs
-
using GlobalPhase_Int = GlobalPhase¶
-
struct GlobalPhase : public qram_simulator::BaseOperator¶
- #include <parallel_phase_operations.h>
Global phase operation (integer register)
Applies a global phase to the whole state
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline GlobalPhase(complex_t c_)¶
Constructor.
- Parameters:
c_ – Phase factor
-
virtual void operator()(std::vector<System> &state) const¶
Apply the global phase operation.
- Parameters:
state – System state vector
-
virtual void dag(std::vector<System> &state) const¶
Apply the dagger operation (conjugate phase)
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
struct RangeConditionalPhaseFlip : public qram_simulator::SelfAdjointOperator¶
- #include <parallel_phase_operations.h>
Range-conditional phase flip.
Applies a phase flip when the register value is within the specified range
Public Functions
-
inline RangeConditionalPhaseFlip(size_t id_, size_t range_)¶
Constructor (ID version)
- Parameters:
id_ – Register ID
range_ – Value range
-
inline RangeConditionalPhaseFlip(std::string_view reg_, size_t range_)¶
Constructor (name version)
- Parameters:
reg_ – Register name
range_ – Value range
-
virtual void operator()(std::vector<System> &state) const¶
Apply the phase flip operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline RangeConditionalPhaseFlip(size_t id_, size_t range_)¶
-
struct Reflection_Bool : public qram_simulator::SelfAdjointOperator¶
- #include <parallel_phase_operations.h>
Boolean reflection operation.
Implements the Grover reflection operation: (I - 2|0><0|) or (2|0><0| - I)
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline Reflection_Bool(std::string_view reg_, bool inverse_ = false)¶
Constructor (single register name version)
- Parameters:
reg_ – Register name
inverse_ – Whether to use the inverse form (default false)
-
inline Reflection_Bool(size_t id_, bool inverse_ = false)¶
Constructor (single register ID version)
- Parameters:
id_ – Register ID
inverse_ – Whether to use the inverse form (default false)
-
inline Reflection_Bool(const std::vector<std::string> ®s_, bool inverse_ = false)¶
Constructor (multiple register names version)
- Parameters:
regs_ – List of register names
inverse_ – Whether to use the inverse form (default false)
-
inline Reflection_Bool(const std::vector<size_t> &ids_, bool inverse_ = false)¶
Constructor (multiple register IDs version)
- Parameters:
ids_ – List of register IDs
inverse_ – Whether to use the inverse form (default false)
-
virtual void operator()(std::vector<System> &state) const¶
Apply the reflection operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
bool inverse¶
Whether to use the inverse form (true: I-2|0><0|, false: 2|0><0|-I)
-
inline void clear_control_nonzeros()¶
-
struct ZeroConditionalPhaseFlip : public qram_simulator::SelfAdjointOperator¶
- #include <parallel_phase_operations.h>
Zero-conditional phase flip.
Applies a phase flip when the specified registers are all zero
Public Functions
-
inline void clear_control_nonzeros()¶
-
inline auto &conditioned_by_nonzeros(size_t cond)¶
-
inline void clear_control_all_ones()¶
-
inline auto &conditioned_by_all_ones(size_t cond)¶
-
inline void clear_control_by_bit()¶
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)¶
-
inline void clear_control_by_value()¶
-
inline auto &conditioned_by_value(size_t cond, size_t pos)¶
-
inline ZeroConditionalPhaseFlip(const std::vector<size_t> ®s_)¶
Constructor (ID list version)
- Parameters:
regs_ – List of register IDs
-
inline ZeroConditionalPhaseFlip(const std::vector<std::string> ®s_)¶
Constructor (name list version)
- Parameters:
regs_ – List of register names
-
virtual void operator()(std::vector<System> &state) const¶
Apply the phase flip operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()¶
-
using GlobalPhase_Int = GlobalPhase¶
State Sorting (SparQ/include/sort_state.h)¶
State sorting definitions.
Implements various sorting operations on quantum states, supporting sorting by key, unconditional sorting, sorting by amplitude, and other sorting modes
-
namespace qram_simulator
QRAM sparse state simulator namespace.
Contains all classes, functions, and data structures related to quantum computing simulation
Functions
-
inline uint64_t make_mask(const std::set<size_t> &qubit_ids)¶
Create a bit mask.
- Parameters:
qubit_ids – Set of qubit IDs
- Returns:
Bit mask
-
bool compare_equal(const System &a, const System &b, size_t out_id)¶
Compare two systems for equality (excluding a specified key)
Used by CondRot_General_Bool, CondRot_General_Bool_QW, Hadamard_Int, etc.
- Parameters:
a – First system
b – Second system
out_id – Excluded key (register ID)
- Returns:
Whether they are equal
-
bool compare_equal2(const System &a, const System &b, size_t out_id1, size_t out_id2)¶
Compare two systems for equality (excluding two specified keys)
Used by QRAM::set_branches
- Parameters:
a – First system
b – Second system
out_id1 – First excluded key (register ID)
out_id2 – Second excluded key (register ID)
- Returns:
Whether they are equal
-
bool compare_equal_rot(const System &a, const System &b, size_t out_id, uint64_t mask)¶
Compare two systems for equality (excluding a specified key and masked bits)
- Parameters:
a – First system
b – Second system
out_id – Excluded key (register ID)
mask – Bit mask
- Returns:
Whether they are equal
-
bool compare_equal_hadamard(const System &a, const System &b, size_t out_id, uint64_t mask)¶
Compare two systems for equality (Hadamard version)
Used by Hadamard_Partial; excludes the target qubit and the masked bits when comparing
- Parameters:
a – First system
b – Second system
out_id – Excluded key (register ID)
mask – Bit mask
- Returns:
Whether they are equal
-
struct SortByAmplitude : public qram_simulator::SelfAdjointOperator¶
- #include <sort_state.h>
Sort by amplitude.
Sorts the system states by amplitude
Public Functions
-
inline SortByAmplitude()¶
Default constructor.
-
virtual void operator()(std::vector<System> &states) const¶
Apply the sorting operation.
- Parameters:
states – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline SortByAmplitude()¶
-
struct SortByKey : public qram_simulator::SelfAdjointOperator¶
- #include <sort_state.h>
Sort by key.
Sorts by the value of the specified register
Public Functions
-
SortByKey(size_t key)¶
Constructor (ID version)
- Parameters:
key – Register ID
-
virtual void operator()(std::vector<System> &state) const¶
Apply the sorting operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
size_t register_key¶
Sort key (register ID)
-
SortByKey(size_t key)¶
-
struct SortByKey2 : public qram_simulator::SelfAdjointOperator¶
- #include <sort_state.h>
Two-key sorting.
Sorts by the values of two registers
Public Functions
-
inline SortByKey2(std::string_view key1_, std::string_view key2_)¶
Constructor (name version)
- Parameters:
key1_ – Name of the first register
key2_ – Name of the second register
-
inline SortByKey2(size_t key1_, size_t key2_)¶
Constructor (ID version)
- Parameters:
key1_ – ID of the first register
key2_ – ID of the second register
-
virtual void operator()(std::vector<System> &states) const¶
Apply the sorting operation.
- Parameters:
states – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline SortByKey2(std::string_view key1_, std::string_view key2_)¶
-
struct SortExceptBit : public qram_simulator::SelfAdjointOperator¶
- #include <sort_state.h>
Sort excluding a bit.
Excludes the specified bit of a register during sorting
Public Functions
-
inline SortExceptBit(std::string_view key_, size_t digit_)¶
Constructor (name version)
- Parameters:
key_ – Register name
digit_ – Bit index
-
inline SortExceptBit(size_t key_, size_t digit_)¶
Constructor (ID version)
- Parameters:
key_ – Register ID
digit_ – Bit index
-
virtual void operator()(std::vector<System> &states) const¶
Apply the sorting operation.
- Parameters:
states – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline SortExceptBit(std::string_view key_, size_t digit_)¶
-
struct SortExceptKey : public qram_simulator::SelfAdjointOperator¶
- #include <sort_state.h>
Sort excluding a key.
Excludes the specified key during sorting, so that it is moved to the end
Public Functions
-
inline SortExceptKey(std::string_view key_)¶
Constructor (name version)
- Parameters:
key_ – Register name
-
inline SortExceptKey(size_t key_)¶
Constructor (ID version)
- Parameters:
key_ – Register ID
-
virtual void operator()(std::vector<System> &states) const¶
Apply the sorting operation.
- Parameters:
states – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
size_t id¶
Excluded key (register ID)
-
inline SortExceptKey(std::string_view key_)¶
-
struct SortExceptKeyHadamard : public qram_simulator::SelfAdjointOperator¶
- #include <sort_state.h>
Hadamard sort-except-key.
Excluded-key sorting optimized for the Hadamard operation
Public Functions
-
inline SortExceptKeyHadamard(std::string_view key_, std::set<size_t> qubit_ids_)¶
Constructor (name version)
- Parameters:
key_ – Register name
qubit_ids_ – Set of qubit IDs
-
inline SortExceptKeyHadamard(size_t key_, std::set<size_t> qubit_ids_)¶
Constructor (ID version)
- Parameters:
key_ – Register ID
qubit_ids_ – Set of qubit IDs
-
size_t remove_digits(size_t val) const¶
Remove the specified bit.
- Parameters:
val – Original value
- Returns:
Value with the bit removed
-
virtual void operator()(std::vector<System> &states) const¶
Apply the sorting operation.
- Parameters:
states – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline SortExceptKeyHadamard(std::string_view key_, std::set<size_t> qubit_ids_)¶
-
struct SortUnconditional : public qram_simulator::SelfAdjointOperator¶
- #include <sort_state.h>
Unconditional sorting.
Performs unconditional parallel sorting of the system states
Public Functions
-
inline SortUnconditional()¶
Default constructor.
-
virtual void operator()(std::vector<System> &states) const¶
Apply the sorting operation.
- Parameters:
states – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline SortUnconditional()¶
-
inline uint64_t make_mask(const std::set<size_t> &qubit_ids)¶
Dark Magic Operators (SparQ/include/dark_magic.h)¶
Internal optimized operations definitions.
Contains low-level optimized operations such as normalization and unsafe initialization; these operations are usually used for internal implementations, use them with care
-
namespace qram_simulator
QRAM sparse state simulator namespace.
Contains all classes, functions, and data structures related to quantum computing simulation
-
struct Init_Unsafe : public qram_simulator::SelfAdjointOperator¶
- #include <dark_magic.h>
Unsafe initialization operation.
Directly sets a register to the specified value without safety checks
Warning
This operation does not check whether the value exceeds the register range; use it with care
Public Functions
-
inline Init_Unsafe(int id_, size_t value_)¶
Constructor (ID version)
- Parameters:
id_ – Register ID
value_ – Value to set
-
inline Init_Unsafe(std::string_view reg, size_t value_)¶
Constructor (name version)
- Parameters:
reg – Register name
value_ – Value to set
-
virtual void operator()(std::vector<System> &system_states) const¶
Apply the unsafe initialization operation.
- Parameters:
system_states – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline Init_Unsafe(int id_, size_t value_)¶
-
struct Normalize : public qram_simulator::SelfAdjointOperator¶
- #include <dark_magic.h>
Normalization operation.
Normalizes a quantum state so that the total probability is 1
Public Functions
-
virtual void operator()(std::vector<System> &state) const¶
Apply the normalization operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override¶
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override¶
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
virtual void operator()(std::vector<System> &state) const¶
-
struct Init_Unsafe : public qram_simulator::SelfAdjointOperator¶
中文版 ===
量子算术与状态整理¶
量子算术（SparQ/include/quantum_arithmetic.h）¶
Quantum arithmetic operations definitions.
Implements various quantum arithmetic operations, including flip, shift, multiplication, addition, comparison, etc.
Unitarity notes¶
Quantum operators must satisfy the unitary property (U^†U = I), which requires operations to be reversible. The operators in this file fall into two categories:
Out-of-place operations (e.g. Add_UInt_UInt):
The result is stored in a separate output register
Unitarity is guaranteed by bitwise XOR: result ^= f(inputs)
Unitarity is automatic because XOR is self-inverse
In-place operations (e.g. Add_UInt_UInt_InPlace, Add_ConstUInt_InPlace):
The result directly modifies the input register
An explicit dagger() method is required to guarantee reversibility
The inverse operation is usually implemented with modular arithmetic: y = (y + (2^N - x)) % 2^N
Type safety notes¶
All operators check the following in debug mode (non-QRAM_Release):
Types of input/output registers (UnsignedInteger/SignedInteger/Boolean/Rational)
Whether register sizes match
Valid ranges of operands (e.g. the number of bits to shift)
In Release mode these checks are compiled out for the best performance.
-
namespace qram_simulator
QRAM sparse state simulator namespace.
Contains all classes, functions, and data structures related to quantum computing simulation
Typedefs
-
using GenericArithmetic = std::function<std::vector<size_t>(const std::vector<size_t>&)>
Generic arithmetic function type.
-
using AddAssign_AnyInt_AnyInt_InPlace = Add_AnyInt_AnyInt_InPlace
-
using Div_Sqrt_Arccos_Int_Int = Div_Sqrt_Arccos_UInt_UInt
-
using Sqrt_Div_Arccos_Int_Int = Sqrt_Div_Arccos_Int_UInt
-
struct Abs_SInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Signed integer absolute value operation (Out-of-place)
Implements out-of-place absolute value: res ^= |reg|, where reg is read with two’s complement sign extension
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: reg must be SignedInteger, res must be UnsignedInteger
Note
Width and truncation: reg is sign-extended to 64 bits, then the absolute value is taken; the result is then XORed into res after taking mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Note
Boundary behavior: when the input is the most negative value (INT64_MIN for w = 64), -v still wraps to itself, and the output keeps the bit pattern of the most negative value
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Abs_SInt(std::string_view reg_, std::string_view res_)
Constructor (name version)
- Parameters:
reg_ – Input register name
res_ – Result register name
-
inline Abs_SInt(size_t reg_, size_t res_)
Constructor (ID version)
- Parameters:
reg_ – Input register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the absolute value operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()
-
struct Add_AnyInt_AnyInt_InPlace : public qram_simulator::BaseOperator
- #include <quantum_arithmetic.h>
Arbitrary integer accumulation operation (In-place)
Implements in-place addition: lhs += rhs, supporting signed and unsigned integers
This is an in-place operation; an explicit dagger implementation is required to guarantee unitarity. dagger implementation: lhs -= rhs (mod 2^N)
- Example
auto lhs = System::add_register("lhs", UnsignedInteger, 4); auto rhs = System::add_register("rhs", UnsignedInteger, 4); Init_Unsafe(lhs, 8); // lhs = 8 Init_Unsafe(rhs, 6); // rhs = 6 // lhs = (8 + 6) % 16 = 14 Add_AnyInt_AnyInt_InPlace("lhs", "rhs"); // dagger: lhs = (14 - 6) % 16 = 8 (restores the original value) op.dag(state);
Note
Unitarity: bijectivity is guaranteed by modular arithmetic
Note
Data type: lhs and rhs may be UnsignedInteger or SignedInteger
Note
Overflow behavior: the result wraps around modulo 2^N at the lhs register size
Note
Type combination: mixed types are supported (e.g. lhs is SignedInteger, rhs is UnsignedInteger)
Note
Read extension (width and truncation convention): rhs is extended per its declared register type – UnsignedInteger is zero-extended and SignedInteger sign-extended; width and type are read at execution time, not snapshotted at construction time
Warning
Overflow behavior of signed integers is undefined (C++ standard); use with caution
- Pre:
lhs and rhs must be of integer type (UnsignedInteger or SignedInteger, debug checked)
- Pre:
lhs and rhs must not be the same register (alias check, always-on)
- Pre:
all registers must be active
Public Functions
-
inline Add_AnyInt_AnyInt_InPlace(std::string_view reg_lhs, std::string_view reg_rhs)
Constructor (name version)
- Parameters:
reg_lhs – Left operand register name
reg_rhs – Right operand register name
-
inline Add_AnyInt_AnyInt_InPlace(size_t reg_lhs, size_t reg_rhs)
Constructor (ID version)
- Parameters:
reg_lhs – Left operand register ID
reg_rhs – Right operand register ID
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
virtual void operator()(std::vector<System> &state) const
Apply the accumulate operation.
- Parameters:
state – System state vector
-
virtual void dag(std::vector<System> &state) const
Apply the dagger operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
size_t lhs_id
Left operand register ID.
-
size_t rhs_id
Right operand register ID.
-
std::vector<size_t> condition_variable_nonzeros
-
std::vector<size_t> condition_variable_all_ones
Public Static Functions
-
static uint64_t _extended_rhs(const System &s, size_t id)
Read the right operand with extension according to the register’s declared type.
UnsignedInteger is zero-extended; SignedInteger is sign-extended (two’s complement bit pattern). Width and type are read at execution time (width and truncation convention).
- Parameters:
s – Current basis vector
id – Right operand register ID
- Returns:
The extended 64-bit bit pattern
-
struct Add_ConstUInt_InPlace : public qram_simulator::BaseOperator
- #include <quantum_arithmetic.h>
Add-constant operation (In-place)
Implements in-place add-constant: reg_in += add_int (mod 2^N)
This is an in-place operation; an explicit dagger implementation is required to guarantee unitarity. dagger implementation: reg_in += (2^N - add_int) mod 2^N, where N is the register bit width
- Example
auto reg = System::add_register("reg", UnsignedInteger, 4); Init_Unsafe(reg, 12); // reg = 12 // reg = (12 + 3) % 16 = 15 Add_ConstUInt_InPlace("reg", 3); // dagger: reg = (15 + 13) % 16 = 12 (restores the original value) op.dag(state);
Note
Unitarity: bijectivity is guaranteed by modular addition
Note
Data type: reg_in is recommended to be UnsignedInteger
Note
Overflow behavior: the result wraps around modulo 2^N at the register size
- Pre:
reg_in must be active
- Pre:
add_int should be less than 2^N (N is the register bit width), otherwise the behavior depends on modular arithmetic
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Add_ConstUInt_InPlace(std::string_view reg_in_, size_t add)
Constructor (name version)
- Parameters:
reg_in_ – Input register name (result stored here)
add – Addend constant
- Throws:
Throws – an exception when a register type is not an integer type
-
inline Add_ConstUInt_InPlace(size_t reg_in, size_t add)
Constructor (ID version)
- Parameters:
reg_in – Input register ID (result stored here)
add – Addend constant
- Throws:
Throws – an exception when a register type is not an integer type
-
virtual void operator()(std::vector<System> &state) const
Apply the add-constant operation.
- Parameters:
state – System state vector
-
virtual void dag(std::vector<System> &state) const
Apply the dagger operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Add_Mult_UInt_ConstUInt_InPlace : public qram_simulator::BaseOperator
- #include <quantum_arithmetic.h>
Accumulate multiply-by-constant operation (In-place)
Implements in-place accumulate-multiply: res += lhs * mult (mod 2^N) Note: the lhs register is not modified; only res is updated.
This is an in-place operation; an explicit dagger implementation is required to guarantee unitarity. Forward: res += lhs * mult (mod 2^N) [lhs unchanged] Dagger: res -= lhs * mult (mod 2^N) [lhs unchanged]
- Example
auto lhs = System::add_register("lhs", UnsignedInteger, 4); auto res = System::add_register("res", UnsignedInteger, 4); Init_Unsafe(lhs, 2); // lhs = 2 Init_Unsafe(res, 3); // res = 3 // res = 3 + (2 * 4) = 11 Add_Mult_UInt_ConstUInt_InPlace("lhs", 4, "res");
Note
Unitarity: lhs is unchanged, only res is updated via modular addition/subtraction; bijectivity is guaranteed by the range of lhs
Note
Data type: lhs and res should both be UnsignedInteger
Note
Overflow behavior: the result wraps around modulo 2^N at the res register size
- Pre:
the res register must have enough bits to store the result
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Add_Mult_UInt_ConstUInt_InPlace(std::string_view reg_in, size_t mult, std::string_view reg_out)
Constructor (name version)
- Parameters:
reg_in – Input register name
mult – Multiplier constant
reg_out – Output register name (result accumulated here)
- Throws:
Throws – an exception when a register type is not UnsignedInteger
-
inline Add_Mult_UInt_ConstUInt_InPlace(size_t reg_in, size_t mult, size_t reg_out)
Constructor (ID version)
- Parameters:
reg_in – Input register ID
mult – Multiplier constant
reg_out – Output register ID (result accumulated here)
- Throws:
Throws – an exception when a register type is not UnsignedInteger
-
virtual void operator()(std::vector<System> &state) const
Apply the accumulate-multiply operation.
- Parameters:
state – System state vector
-
virtual void dag(std::vector<System> &state) const
Apply the dagger operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Add_UInt_ConstUInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Unsigned integer add-constant operation (Out-of-place)
Implements out-of-place add-constant: res ^= lhs + add_int
Unitary guarantee: implemented via XOR, res = res ⊕ (lhs + add_int) Applied twice: res ⊕ (lhs + add_int) ⊕ (lhs + add_int) = res
- Example
auto lhs = System::add_register("lhs", UnsignedInteger, 4); auto res = System::add_register("res", UnsignedInteger, 4); Init_Unsafe(lhs, 6); // lhs = 6 // res = 0 ⊕ (6 + 4) = 10 Add_UInt_ConstUInt("lhs", 4, "res");
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs and res must both be UnsignedInteger
Note
Overflow behavior: the addition result is truncated to the output register size before the XOR
- Pre:
the lhs and res registers must be of UnsignedInteger type
- Pre:
all registers must be active
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Add_UInt_ConstUInt(std::string_view reg_in, size_t add, std::string_view reg_out)
Constructor (name version)
- Parameters:
reg_in – Input register name
add – Addend constant
reg_out – Output register name
-
inline Add_UInt_ConstUInt(size_t reg_in, size_t add, size_t reg_out)
Constructor (ID version)
- Parameters:
reg_in – Input register ID
add – Addend constant
reg_out – Output register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the add-constant operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Add_UInt_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Unsigned integer addition operation (Out-of-place)
Implements out-of-place addition: res ^= lhs + rhs
Unitary guarantee: implemented via XOR, res = res ⊕ (lhs + rhs) Applied twice: res ⊕ (lhs + rhs) ⊕ (lhs + rhs) = res, i.e. U^2 = I
- Example
auto lhs = System::add_register("lhs", UnsignedInteger, 4); auto rhs = System::add_register("rhs", UnsignedInteger, 4); auto res = System::add_register("res", UnsignedInteger, 4); Init_Unsafe(lhs, 3); // lhs = 3 Init_Unsafe(rhs, 5); // rhs = 5 // res = 0 ⊕ (3 + 5) = 8 Add_UInt_UInt("lhs", "rhs", "res");
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must all be UnsignedInteger
Note
Overflow behavior: the addition result is truncated to the output register size before the XOR
- Pre:
the lhs, rhs, and res registers must be of UnsignedInteger type
- Pre:
all registers must be active
- Pre:
the res register is usually initialized to 0, but may hold any value (XOR semantics)
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Add_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_)
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Result register name
-
inline Add_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_)
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the addition operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Add_UInt_UInt_InPlace : public qram_simulator::BaseOperator
- #include <quantum_arithmetic.h>
In-place unsigned integer addition operation (In-place)
Implements in-place addition: rhs += lhs
This is an in-place operation; an explicit dagger implementation is required to guarantee unitarity. dagger implementation: rhs += (2^N - lhs) mod 2^N, where N is the rhs register bit width
- Example
auto lhs = System::add_register("lhs", UnsignedInteger, 4); auto rhs = System::add_register("rhs", UnsignedInteger, 4); Init_Unsafe(lhs, 7); // lhs = 7 Init_Unsafe(rhs, 3); // rhs = 3 // rhs = 3 + 7 = 10 Add_UInt_UInt_InPlace("lhs", "rhs"); // dagger: rhs = 10 + (16 - 7) % 16 = 3 (restores the original value) op.dag(state);
Note
Unitarity: bijectivity is guaranteed by modular addition
Note
Data type: lhs and rhs should both be UnsignedInteger
Note
Overflow behavior: the result wraps around modulo 2^N at the rhs register size
Note
lhs and rhs may have different sizes; lhs is read as an integer, and rhs undergoes modular addition at its own bit width.
- Pre:
lhs and rhs must be active
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Add_UInt_UInt_InPlace(std::string_view lhs_, std::string_view rhs_)
Constructor (name version)
- Parameters:
lhs_ – Left operand register name (addend)
rhs_ – Right operand register name (augend; result stored here)
- Throws:
Throws – an exception when a register type is not UnsignedInteger or sizes do not match
-
inline Add_UInt_UInt_InPlace(size_t lhs_, size_t rhs_)
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID (addend)
rhs_ – Right operand register ID (augend; result stored here)
- Throws:
Throws – an exception when a register type is not UnsignedInteger or sizes do not match
-
virtual void operator()(std::vector<System> &state) const
Apply the in-place addition operation.
- Parameters:
state – System state vector
-
virtual void dag(std::vector<System> &state) const
Apply the dagger operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct And_UInt_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Unsigned integer bitwise AND operation (Out-of-place)
Implements out-of-place bitwise AND: res ^= lhs & rhs
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must all be UnsignedInteger
Note
Width and truncation: operands are zero-extended; the result is then XORed into res after taking mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline And_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_)
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Result register name
-
inline And_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_)
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the bitwise AND operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()
-
struct Assign : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Assignment operation (Out-of-place)
Implements register copy: register_2 ^= register_1
This is the standard implementation of the “copy” operation in quantum computing. Implemented via XOR; applying it twice restores the original value.
- Example
auto src = System::add_register("src", UnsignedInteger, 4); auto dst = System::add_register("dst", UnsignedInteger, 4); Init_Unsafe(src, 7); // src = 7 Init_Unsafe(dst, 0); // dst = 0 // dst = 0 ⊕ 7 = 7 Assign("src", "dst"); // Applied again: dst = 7 ⊕ 7 = 0 (restores the original value) Assign("src", "dst");
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: any type, as long as the two registers have the same size
Note
Semantics: register_2 = register_2 ⊕ register_1 If register_2 is initially 0, the effect is register_2 = register_1
- Pre:
register_1 and register_2 must have the same size
- Pre:
all registers must be active
Public Functions
-
inline Assign(std::string_view reg1, std::string_view reg2)
Constructor (name version)
- Parameters:
reg1 – First register name
reg2 – Second register name
-
inline Assign(size_t reg1, size_t reg2)
Constructor (ID version)
- Parameters:
reg1 – First register ID
reg2 – Second register ID
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
virtual void operator()(std::vector<System> &state) const
Apply the assignment operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Carry_UInt_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Unsigned addition carry flag operation (Out-of-place flag operator)
Reports the carry-out of lhs + rhs relative to res width w: flag ^= carry_out_w(lhs + rhs)
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must be UnsignedInteger, flag must be Boolean (width 1)
Note
The out parameter only provides the width and its value is never read: res is only used to determine the target width w of the carry test, this operator does not read or write res (docs/operators.md “Width and Truncation Convention”)
Note
The predicate is evaluated on the full-precision domain: when w = 64 it is decided by 64-bit wraparound, when w < 64 it is decided by a + b >= 2^w
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Carry_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_, std::string_view flag_)
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Name of the out register providing the target width
flag_ – Register name of the carry result flag
-
inline Carry_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_, size_t flag_)
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – ID of the out register providing the target width
flag_ – Register ID of the carry result flag
-
virtual void operator()(std::vector<System> &state) const
Apply the carry flag operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
size_t lhs
Left operand register ID.
-
size_t rhs
Right operand register ID.
-
size_t res
ID of the out register providing the target width (its value is not read)
-
size_t flag_id
Carry result flag register ID.
-
std::vector<size_t> condition_variable_nonzeros
-
std::vector<size_t> condition_variable_all_ones
-
inline void clear_control_nonzeros()
-
struct Compare_UInt_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Unsigned integer comparison operation (Out-of-place)
Compares two unsigned integers, outputting the less-than and equal flags
Implementation:
compare_less_id ^= (left < right)
compare_equal_id ^= (left == right)
- Example
auto left = System::add_register("left", UnsignedInteger, 4); auto right = System::add_register("right", UnsignedInteger, 4); auto less = System::add_register("less", Boolean, 1); auto equal = System::add_register("equal", Boolean, 1); Init_Unsafe(left, 3); Init_Unsafe(right, 5); // less = (3 < 5) = 1, equal = (3 == 5) = 0 Compare_UInt_UInt("left", "right", "less", "equal");
Note
Unitarity: self-adjoint operator, implemented via XOR
Note
Data type: left_id and right_id must be UnsignedInteger; compare_less_id and compare_equal_id must be Boolean
Note
Semantics: the output flags are XORed into the result registers; if initially 0, the comparison result is stored directly
- Pre:
left_id and right_id must be of UnsignedInteger type
- Pre:
compare_less_id and compare_equal_id must be of Boolean type (size 1)
- Pre:
all registers must be active
Public Functions
-
inline Compare_UInt_UInt(std::string_view left_register, std::string_view right_register, std::string_view compare_less, std::string_view compare_equal)
Constructor (name version)
- Parameters:
left_register – Left operand register name
right_register – Right operand register name
compare_less – Register name of the less-than result
compare_equal – Register name of the equality result
-
inline Compare_UInt_UInt(size_t lreg, size_t rreg, size_t compare_less, size_t compare_equal)
Constructor (ID version)
- Parameters:
lreg – Left operand register ID
rreg – Right operand register ID
compare_less – Register ID of the less-than result
compare_equal – Register ID of the equality result
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
virtual void operator()(std::vector<System> &state) const
Apply the comparison operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
size_t left_id
Left operand register ID.
-
size_t right_id
Right operand register ID.
-
size_t compare_less_id
Less-than comparison result register ID.
-
size_t compare_equal_id
Equality comparison result register ID.
-
std::vector<size_t> condition_variable_nonzeros
-
std::vector<size_t> condition_variable_all_ones
-
struct CustomArithmetic : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Custom arithmetic operation (Out-of-place)
Allows the user to define a custom arithmetic function and apply it to the quantum state
The user can provide a function func: vector<size_t> -> vector<size_t>, The operation passes the input register values to func and then XORs the output into the output registers.
────────────────────────────────────────────────────────────────────────
The current implementation is a **”simulator privilege” primitive**: on each basis state of the
SparseState it directly calls a host C++ / Python callback func, XORing f(x) into the output register. This is equivalent to an idealized oracle U_f|x⟩|y⟩ = |x⟩|y ⊕ f(x)⟩, but with no corresponding physical quantum circuit – real hardware cannot “read out basis state values and then call an arbitrary function”. Therefore:- Design notes: the “simulator privilege” semantics of CustomArithmetic and its future evolution
CustomArithmetic is only meaningful in a sparse state simulator;
Any pass that “lowers an algorithm to a physical backend / Clifford+T / OriginIR” should not treat CustomArithmetic as a valid target primitive;
Upper-layer DSLs (e.g. qec_compiler/dsl_runtime/dsl) should not allow YAML composites to reference CustomArithmetic directly, otherwise the compiled circuit cannot be physically executed.
By analogy with the C standard library: sin/exp/log in math.h are not CPU instructions; libm implements them with a software library from a small set of ALU primitives (+, −, ×, ÷, FMA, sqrt) + range reduction + polynomial approximation + table lookup. Similarly, in the quantum world we should:
- Future evolution: build quantum-libm + intelligent lowering strategy
┌──────────────────────────────────────────────────────────────────┐ │ Tier 0 — quantum arithmetic ISA: │ │ QAdd / QSub / QMul / QDiv / QMod / QShift / QSwap / Toffoli / │ │ multi-controlled X, Clifford+T basis, and other existing primitives │ ├──────────────────────────────────────────────────────────────────┤ │ Tier 1 — reciprocal / square root / modular inverse (Newton iteration over Tier 0) │ ├──────────────────────────────────────────────────────────────────┤ │ Tier 2 — elementary functions: sin/cos/exp/log via range reduction + │ │ polynomial + QROM coefficient table lookup + Horner (all composed from Tier 0 / Tier 1) │ ├──────────────────────────────────────────────────────────────────┤ │ Tier 3 — black-box lookup tables: QROM / SELECT-SWAP (Babbush et al. 2018) │ │ Suitable for small discrete domains; expands into an O(2^n) multi-controlled X chain │ └──────────────────────────────────────────────────────────────────┘
Under this architecture, CustomArithmetic is no longer an endpoint but a trait interface:
It accepts the user-provided func along with metadata such as domain / precision / target backend;
An intelligent lowering strategy selector chooses the landing path based on this information:
Domain <= 2^k (k small, typically k <= 8) -> QROM expansion
func is a polynomial / analytic smooth function -> polynomial approximation + Horner
func is structured arithmetic such as modular exponentiation / modular multiplication -> use dedicated primitives such as Mod_Mult directly
Simulator-only target and func is hard to decompose -> keep as a host callback (i.e. current behavior)
The selector need not be simple code, but a cost model considering N (bit width), ε (error budget), T-count budget, fault tolerance, and other multi-dimensional constraints.
The controlled modular exponentiation in Shor’s algorithm should not take the CustomArithmetic route – it is essentially a controlled-Mod_Mult chain (an in-place operation), whereas CustomArithmetic’s XOR semantics only describe the out-of-place |x⟩|y⟩→|x⟩|y⊕f(x)⟩, and LUT expansion would prevent Shor from scaling to 2048 bits. The correct approach is to call Mod_Mult_UInt_ConstUInt_InPlace directly, accumulating the product over j = 0..2n-1 of a^(2^j) mod N, each factor controlled by bit j of work_reg. Shor’s lowering optimizations (windowed arithmetic, Beauregard, Häner-Roetteler- Soeken, etc.) are all built on this in-place chain rather than on LUTs.
- Special note on Shor (mod-pow)
- Example
// Custom function: output = input * 2 GenericArithmetic double_func = [](const std::vector<size_t>& inputs) { return std::vector<size_t>{inputs[0] * 2}; }; auto inp = System::add_register("inp", UnsignedInteger, 4); auto out = System::add_register("out", UnsignedInteger, 4); Init_Unsafe(inp, 7); // inp = 7 std::vector<std::string> regs = {"inp", "out"}; CustomArithmetic arith(regs, 1, 1, double_func); // out = 0 ⊕ (7 * 2) = 14 arith(state);
Note
Unitarity: self-adjoint operator (U^† = U), because it is implemented with XOR
Note
Constraint: func must be a deterministic pure function, otherwise unitarity cannot be guaranteed
Warning
Until this architecture lands, please treat CustomArithmetic as a “simulator-only oracle”; do not reference it in algorithm descriptions targeting physical hardware (DSL composites, IR codegen passes). ────────────────────────────────────────────────────────────────────────
Warning
The user is responsible for ensuring func does not cause information loss (i.e. func should be a deterministic function of its input)
- Pre:
the numbers of input and output registers must be correctly specified in the constructor
- Pre:
func must be deterministic (the same input always produces the same output)
- Pre:
all registers must be active
Public Functions
-
inline CustomArithmetic(const std::vector<size_t> &input_registers, size_t input_size, size_t output_size, GenericArithmetic func)
Constructor (ID version)
- Parameters:
input_registers – List of input register IDs
input_size – Number of input registers
output_size – Number of output registers
func – Custom arithmetic function
- Throws:
Throws – an exception when input and output sizes do not match
-
inline CustomArithmetic(const std::vector<std::string> &input_registers, size_t input_size, size_t output_size, GenericArithmetic func)
Constructor (name version)
- Parameters:
input_registers – List of input register names
input_size – Number of input registers
output_size – Number of output registers
func – Custom arithmetic function
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline virtual void operator()(std::vector<System> &state) const
Apply the custom arithmetic operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
std::vector<size_t> input_ids
List of input register IDs.
-
std::vector<size_t> output_ids
List of output register IDs.
-
GenericArithmetic func
Custom arithmetic function.
-
std::vector<size_t> condition_variable_nonzeros
-
std::vector<size_t> condition_variable_all_ones
-
struct Div_Sqrt_Arccos_UInt_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Division square-root arccosine operation (Out-of-place)
Implements: res ^= arccos(sqrt(lhs / rhs)) / π / 2
Used to compute quantum rotation angles, common in quantum machine learning algorithms.
- Mathematical formula
output = arccos(√(lhs / rhs)) / (2π)
- Example
auto lhs = System::add_register("lhs", UnsignedInteger, 4); auto rhs = System::add_register("rhs", UnsignedInteger, 4); auto res = System::add_register("res", Rational, 8); Init_Unsafe(lhs, 1); // lhs = 1 Init_Unsafe(rhs, 4); // rhs = 4 // res = arccos(sqrt(1/4)) / 2π = arccos(0.5) / 2π = 1/6 ≈ 0.167 Div_Sqrt_Arccos_UInt_UInt("lhs", "rhs", "res");
Note
Unitarity: self-adjoint operator, implemented via XOR
Note
Data type: lhs and rhs must be UnsignedInteger, res must be Rational
Note
Numeric range: the result is in [0, 0.5], encoded as a rational
- Pre:
lhs and rhs must be of UnsignedInteger type
- Pre:
res must be of Rational type
- Pre:
lhs < rhs (otherwise the sqrt argument exceeds the [0,1] range and may produce NaN)
- Pre:
all registers must be active
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Div_Sqrt_Arccos_UInt_UInt(std::string_view register_lhs, std::string_view register_rhs, std::string_view register_out)
Constructor (name version)
- Parameters:
register_lhs – Left operand register name
register_rhs – Right operand register name
register_out – Output register name
-
inline Div_Sqrt_Arccos_UInt_UInt(size_t reg_lhs, size_t reg_rhs, size_t reg_out)
Constructor (ID version)
- Parameters:
reg_lhs – Left operand register ID
reg_rhs – Right operand register ID
reg_out – Output register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the arithmetic operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Div_UInt_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Unsigned integer division operation (Out-of-place)
Implements out-of-place division: res ^= lhs / rhs (integer division, rounding down)
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must all be UnsignedInteger
Note
Total domain: when the divisor is zero the quotient is 0 and no domain exception is thrown (reversibility requires the operator to be a deterministic function on all basis vectors; docs/operators.md “Width and Truncation Convention”); overflow information is reported separately by dedicated flag operators
Note
Width and truncation: operands are zero-extended, quotient domain <= 64 bits, then XORed into res after taking mod 2^res_width
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Div_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_)
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Result register name
-
inline Div_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_)
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the division operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()
-
struct FlipBools : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Boolean flip operation.
Flips all bits in the register (bitwise NOT), implementing y = ~y
- Example
// 4-bit register, initial value 0b1010 (10) FlipBools("reg"); // Result: 0b0101 (5)
Note
Unitarity: self-adjoint operator (SelfAdjointOperator), i.e. U^† = U
Note
Data type: any integer type (UnsignedInteger/SignedInteger)
Note
Overflow behavior: only bits within the register size are affected; high bits are flipped but truncated by the mask
- Pre:
the input register must be active
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline FlipBools(std::string_view reg)
Constructor (name version)
- Parameters:
reg – Register name
-
inline FlipBools(size_t id_)
Constructor (ID version)
- Parameters:
id_ – Register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the flip operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct GetMid_UInt_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Get midpoint operation (Out-of-place)
Computes the midpoint of two unsigned integers: mid ^= (left + right) / 2
Commonly used for binary search and midpoint computation in quantum algorithms.
- Example
auto left = System::add_register("left", UnsignedInteger, 4); auto right = System::add_register("right", UnsignedInteger, 4); auto mid = System::add_register("mid", UnsignedInteger, 4); Init_Unsafe(left, 0); Init_Unsafe(right, 10); // mid = (0 + 10) / 2 = 5 GetMid_UInt_UInt("left", "right", "mid");
Note
Unitarity: self-adjoint operator, implemented via XOR
Note
Data type: left_id, right_id, and mid_id must all be UnsignedInteger
Note
Overflow behavior: the addition may overflow, but the result after division is correct (integer division, rounding down)
- Pre:
left_id, right_id, and mid_id must be of UnsignedInteger type
- Pre:
the three registers must have the same size
- Pre:
all registers must be active
Public Functions
-
inline GetMid_UInt_UInt(std::string_view left_register_, std::string_view right_register_, std::string_view mid_register_)
Constructor (name version)
- Parameters:
left_register_ – Left operand register name
right_register_ – Right operand register name
mid_register_ – Midpoint result register name
-
inline GetMid_UInt_UInt(size_t left_register_, size_t right_register_, size_t mid_register_)
Constructor (ID version)
- Parameters:
left_register_ – Left operand register ID
right_register_ – Right operand register ID
mid_register_ – Midpoint result register ID
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
virtual void operator()(std::vector<System> &state) const
Apply the midpoint computation operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct GetRotateAngle_Int_Int : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Get rotation angle operation (Out-of-place)
Computes the polar angle from lhs to rhs: res ^= atan2(rhs, lhs) / (2π)
Converts the Cartesian coordinates (lhs, rhs) to a polar angle; the result is encoded in the range [0, 1).
- Mathematical formula
If lhs == 0 and rhs >= 0: output = 0.25 (90°)
If lhs == 0 and rhs < 0: output = 0.75 (270°)
Otherwise: output = atan2(rhs, lhs) / (2π) normalized to [0,1)
- Example
auto lhs = System::add_register("lhs", SignedInteger, 4); auto rhs = System::add_register("rhs", SignedInteger, 4); auto res = System::add_register("res", Rational, 8); Init_Unsafe(lhs, 1); // lhs = 1 Init_Unsafe(rhs, 1); // rhs = 1 // res = atan2(1, 1) / 2π = 0.125 (45°) GetRotateAngle_Int_Int("lhs", "rhs", "res");
Note
Unitarity: self-adjoint operator, implemented via XOR
Note
Data type: lhs and rhs may be SignedInteger or UnsignedInteger, res must be Rational
Note
Numeric range: the result is in [0, 1) (a normalized angle)
- Pre:
res must be of Rational type
- Pre:
all registers must be active
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline GetRotateAngle_Int_Int(std::string_view reg_lhs, std::string_view reg_rhs, std::string_view reg_out)
Constructor (name version)
- Parameters:
reg_lhs – Left operand register name
reg_rhs – Right operand register name
reg_out – Output register name
-
inline GetRotateAngle_Int_Int(size_t reg_lhs, size_t reg_rhs, size_t reg_out)
Constructor (ID version)
- Parameters:
reg_lhs – Left operand register ID
reg_rhs – Right operand register ID
reg_out – Output register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the arithmetic operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct IsZero_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Unsigned integer zero-test operation (Out-of-place flag operator)
Implements out-of-place zero test: flag ^= (reg == 0)
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: reg must be UnsignedInteger, flag must be Boolean (width 1)
Note
The predicate is evaluated on the full-precision domain: operands are zero-extended and compared with 0 (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline IsZero_UInt(std::string_view reg_, std::string_view flag_)
Constructor (name version)
- Parameters:
reg_ – Input register name
flag_ – Register name of the zero-test result flag
-
inline IsZero_UInt(size_t reg_, size_t flag_)
Constructor (ID version)
- Parameters:
reg_ – Input register ID
flag_ – Register ID of the zero-test result flag
-
virtual void operator()(std::vector<System> &state) const
Apply the zero-test operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()
-
struct Less_SInt_SInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Signed integer less-than comparison operation (Out-of-place)
Implements out-of-place signed comparison: flag ^= (lhs < rhs)
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs and rhs must be SignedInteger, flag must be Boolean (width 1)
Note
The predicate is evaluated on the full-precision domain: operands are sign-extended to 64 bits and then compared (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Less_SInt_SInt(std::string_view lhs_, std::string_view rhs_, std::string_view flag_)
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
flag_ – Register name of the less-than result flag
-
inline Less_SInt_SInt(size_t lhs_, size_t rhs_, size_t flag_)
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
flag_ – Register ID of the less-than result flag
-
virtual void operator()(std::vector<System> &state) const
Apply the signed less-than comparison operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()
-
struct Less_UInt_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Less-than comparison operation (Out-of-place)
Compares two unsigned integers, outputting only the less-than flag
Implementation: compare_less_id ^= (left < right)
- Example
auto left = System::add_register("left", UnsignedInteger, 4); auto right = System::add_register("right", UnsignedInteger, 4); auto less = System::add_register("less", Boolean, 1); Init_Unsafe(left, 3); Init_Unsafe(right, 5); // less = (3 < 5) = 1 Less_UInt_UInt("left", "right", "less");
Note
Unitarity: self-adjoint operator, implemented via XOR
Note
Data type: left_id and right_id must be UnsignedInteger, compare_less_id must be Boolean
Note
Semantics: the output flags are XORed into the result registers; if initially 0, the comparison result is stored directly
- Pre:
left_id and right_id must be of UnsignedInteger type
- Pre:
compare_less_id must be of Boolean type (size 1)
- Pre:
all registers must be active
Public Functions
-
inline Less_UInt_UInt(std::string_view lreg, std::string_view rreg, std::string_view compare_less)
Constructor (name version)
- Parameters:
lreg – Left operand register name
rreg – Right operand register name
compare_less – Register name of the less-than result
-
inline Less_UInt_UInt(size_t lreg, size_t rreg, size_t compare_less)
Constructor (ID version)
- Parameters:
lreg – Left operand register ID
rreg – Right operand register ID
compare_less – Register ID of the less-than result
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
virtual void operator()(std::vector<System> &state) const
Apply the less-than comparison operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Mod_Mult_UInt_ConstUInt_InPlace : public qram_simulator::BaseOperator
- #include <quantum_arithmetic.h>
Modular multiplication.
Computes |y⟩ → |y * a^(2^x) mod N⟩
When a and N are coprime, Mod_Mult_UInt_ConstUInt_InPlace is a unitary operation.
Unitarity notes for Mod_Mult_UInt_ConstUInt_InPlace¶
Unitarity conditions for Mod_Mult_UInt_ConstUInt_InPlace:
a and N must be coprime (gcd(a, N) = 1)
When the condition holds, the inverse operation is y * a^(2^x*(N-2)) mod N (Fermat’s little theorem)
Usage example¶
auto reg = System::add_register("y", UnsignedInteger, 4); auto cond = System::add_register("ctrl", Boolean, 1); Mod_Mult_UInt_ConstUInt_InPlace(reg, 7, 2, 15).conditioned_by_all_ones(cond)(state); // Computes: y = y * 7^4 mod 15 = y * 4 mod 15
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
Mod_Mult_UInt_ConstUInt_InPlace(std::string_view reg_name, uint64_t a, uint64_t x, uint64_t N)
Constructor (name version)
- Parameters:
reg_name – Operand register name
a – Base
x – Exponent bit
N – Modulus
- Throws:
Throws – an exception when a and N are not coprime
-
Mod_Mult_UInt_ConstUInt_InPlace(size_t reg_id, uint64_t a, uint64_t x, uint64_t N)
Constructor (ID version)
- Parameters:
reg_id – Operand register ID
a – Base
x – Exponent bit
N – Modulus
- Throws:
Throws – an exception when a and N are not coprime
-
virtual void operator()(std::vector<System> &state) const
Execute the modular multiplication.
- Parameters:
state – System state vector
-
virtual void dag(std::vector<System> &state) const
Execute the inverse modular multiplication.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Mul_UInt_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Unsigned integer multiplication operation (Out-of-place)
Implements out-of-place multiplication: res ^= lhs * rhs
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must all be UnsignedInteger
Note
Width and truncation: operands are zero-extended; the low 64 bits of the full-precision 128-bit product are taken, then XORed into res after taking mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Mul_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_)
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Result register name
-
inline Mul_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_)
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the multiplication operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()
-
struct MulOverflow_UInt_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Unsigned multiplication overflow flag operation (Out-of-place flag operator)
Reports whether lhs * rhs exceeds the representable range of res width w: flag ^= (lhs * rhs not contained in w bits)
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must be UnsignedInteger, flag must be Boolean (width 1)
Note
The out parameter only provides the width and its value is never read: res is only used to determine the target width w of the overflow test, this operator does not read or write res (docs/operators.md “Width and Truncation Convention”)
Note
The predicate is evaluated on the full-precision domain: the product is decomposed into 64-bit high/low halves (equivalent to 128-bit precision), overflow is decided when the high 64 bits are nonzero or the low 64 bits exceed the w-bit range
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline MulOverflow_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_, std::string_view flag_)
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Name of the out register providing the target width
flag_ – Register name of the overflow result flag
-
inline MulOverflow_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_, size_t flag_)
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – ID of the out register providing the target width
flag_ – Register ID of the overflow result flag
-
virtual void operator()(std::vector<System> &state) const
Apply the multiplication overflow flag operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
size_t lhs
Left operand register ID.
-
size_t rhs
Right operand register ID.
-
size_t res
ID of the out register providing the target width (its value is not read)
-
size_t flag_id
Overflow result flag register ID.
-
std::vector<size_t> condition_variable_nonzeros
-
std::vector<size_t> condition_variable_all_ones
-
inline void clear_control_nonzeros()
-
struct Mult_UInt_ConstUInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Unsigned integer multiply-by-constant operation (Out-of-place)
Implements out-of-place multiplication: res ^= lhs * mult
Unitary guarantee: implemented via XOR, res = res ⊕ (lhs * mult) Applied twice: res ⊕ (lhs * mult) ⊕ (lhs * mult) = res, i.e. U^2 = I
- Example
auto lhs = System::add_register("lhs", UnsignedInteger, 4); auto res = System::add_register("res", UnsignedInteger, 4); Init_Unsafe(lhs, 3); // lhs = 3 // res = 0 ⊕ (3 * 4) = 12 Mult_UInt_ConstUInt("lhs", 4, "res");
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: both input and output must be UnsignedInteger
Note
Overflow behavior: the multiplication result is truncated to the output register size
- Pre:
the lhs and res registers must be of UnsignedInteger type
- Pre:
all registers must be active
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Mult_UInt_ConstUInt(std::string_view reg_in, size_t mult, std::string_view reg_out)
Constructor (name version)
- Parameters:
reg_in – Input register name
mult – Multiplier constant
reg_out – Output register name
-
inline Mult_UInt_ConstUInt(size_t reg_in, size_t mult, size_t reg_out)
Constructor (ID version)
- Parameters:
reg_in – Input register ID
mult – Multiplier constant
reg_out – Output register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the multiplication operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Neg_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Unsigned integer negation operation (Out-of-place)
Implements out-of-place negation: res ^= 0 - reg
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: reg and res must both be UnsignedInteger
Note
Width and truncation: operands are zero-extended; negative values are evaluated on the unsigned 64-bit wrapping domain (equivalent to 64-bit two’s complement negation), then XORed into res after mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Neg_UInt(std::string_view reg_, std::string_view res_)
Constructor (name version)
- Parameters:
reg_ – Input register name
res_ – Result register name
-
inline Neg_UInt(size_t reg_, size_t res_)
Constructor (ID version)
- Parameters:
reg_ – Input register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the negation operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()
-
struct Negative_SInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Signed integer negative-test operation (Out-of-place flag operator)
Implements out-of-place negative test: flag ^= (reg < 0)
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: reg must be SignedInteger, flag must be Boolean (width 1)
Note
The predicate is evaluated on the full-precision domain: operands are two’s complement sign-extended and compared with 0 (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Negative_SInt(std::string_view reg_, std::string_view flag_)
Constructor (name version)
- Parameters:
reg_ – Input register name
flag_ – Register name of the negative-test result flag
-
inline Negative_SInt(size_t reg_, size_t flag_)
Constructor (ID version)
- Parameters:
reg_ – Input register ID
flag_ – Register ID of the negative-test result flag
-
virtual void operator()(std::vector<System> &state) const
Apply the negative-test operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()
-
struct Or_UInt_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Unsigned integer bitwise OR operation (Out-of-place)
Implements out-of-place bitwise OR: res ^= lhs | rhs
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must all be UnsignedInteger
Note
Width and truncation: operands are zero-extended; the result is then XORed into res after taking mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Or_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_)
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Result register name
-
inline Or_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_)
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the bitwise OR operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()
-
struct Overflow_SInt_SInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Signed addition overflow flag operation (Out-of-place flag operator)
Reports signed overflow of lhs + rhs relative to res width w: flag ^= overflow_w(lhs + rhs)
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs and rhs must be SignedInteger, res must be UnsignedInteger, flag must be Boolean (width 1)
Note
The out parameter only provides the width and its value is never read: res is only used to determine the target width w of the overflow test, this operator does not read or write res (docs/operators.md “Width and Truncation Convention”)
Note
The predicate is evaluated on the full-precision domain: operands are sign-extended, truncated to w bits, and decided by same-sign addition with the result changing sign
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Overflow_SInt_SInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_, std::string_view flag_)
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Name of the out register providing the target width
flag_ – Register name of the overflow result flag
-
inline Overflow_SInt_SInt(size_t lhs_, size_t rhs_, size_t res_, size_t flag_)
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – ID of the out register providing the target width
flag_ – Register ID of the overflow result flag
-
virtual void operator()(std::vector<System> &state) const
Apply the overflow flag operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
size_t lhs
Left operand register ID.
-
size_t rhs
Right operand register ID.
-
size_t res
ID of the out register providing the target width (its value is not read)
-
size_t flag_id
Overflow result flag register ID.
-
std::vector<size_t> condition_variable_nonzeros
-
std::vector<size_t> condition_variable_all_ones
-
inline void clear_control_nonzeros()
-
struct Select_Bool_UInt_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Boolean conditional select operation (Out-of-place)
Implements out-of-place two-way select: res ^= (cond ? lhs : rhs), cond reads bit 0
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: cond must be Boolean (width 1), lhs, rhs, and res must all be UnsignedInteger
Note
Width and truncation: operands are zero-extended; the selected value is then XORed into res after taking mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Select_Bool_UInt_UInt(std::string_view cond_, std::string_view lhs_, std::string_view rhs_, std::string_view res_)
Constructor (name version)
- Parameters:
cond_ – Condition register name
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Result register name
-
inline Select_Bool_UInt_UInt(size_t cond_, size_t lhs_, size_t rhs_, size_t res_)
Constructor (ID version)
- Parameters:
cond_ – Condition register ID
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the conditional select operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()
-
struct ShiftLeft_InPlace : public qram_simulator::BaseOperator
- #include <quantum_arithmetic.h>
Rotate-left operation.
Rotates the register value left by the specified number of bits; the overflowing high bits wrap around to the low bits
Mathematical definition: y = (y << digit) | (y >> (N - digit)), where N is the register bit width
- Example
// 4-bit register, initial value 0b1010 ShiftLeft_InPlace("reg", 1); // Result: 0b0101 (rotate left by 1 bit) ShiftLeft_InPlace("reg", 2); // Result: 0b1010 (rotate left by 2 bits)
Note
Unitarity: rotation is a bijection, guaranteeing unitarity
Note
dagger operation: the dagger of a left rotation by d bits is a right rotation by d bits (or a left rotation by N-d bits)
Note
Data type: UnsignedInteger recommended, may also be used with SignedInteger
- Pre:
register_1 must be active
- Pre:
digit <= register size (digit == size is equivalent to the identity operation)
Public Functions
-
virtual void dag(std::vector<System> &state) const
Apply the dagger operation (calls ShiftRight_InPlace)
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline ShiftLeft_InPlace(std::string_view reg1, size_t d)
Constructor (name version)
- Parameters:
reg1 – Register name
d – Number of bits to shift
- Throws:
Throws – an exception when a register type is not an integer type
-
inline ShiftLeft_InPlace(size_t reg1, size_t d)
Constructor (ID version)
- Parameters:
reg1 – Register ID
d – Number of bits to shift
- Throws:
Throws – an exception when a register type is not an integer type
-
struct ShiftRight_InPlace : public qram_simulator::BaseOperator
- #include <quantum_arithmetic.h>
Rotate-right operation.
Rotates the register value right by the specified number of bits; the overflowing low bits wrap around to the high bits
Mathematical definition: y = (y >> digit) | (y << (N - digit)), where N is the register bit width
- Example
// 4-bit register, initial value 0b1010 ShiftRight_InPlace("reg", 1); // Result: 0b0101 (rotate right by 1 bit)
Note
Unitarity: rotation is a bijection, guaranteeing unitarity
Note
dagger operation: the dagger of a right rotation by d bits is a left rotation by d bits (or a right rotation by N-d bits)
Note
Data type: UnsignedInteger recommended, may also be used with SignedInteger
- Pre:
register_1 must be active
- Pre:
digit <= register size (digit == size is equivalent to the identity operation)
Public Functions
-
virtual void dag(std::vector<System> &state) const
Apply the dagger operation (calls ShiftLeft_InPlace)
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline ShiftRight_InPlace(std::string_view reg1, size_t d)
Constructor (name version)
- Parameters:
reg1 – Register name
d – Number of bits to shift
- Throws:
Throws – an exception when a register type is not an integer type
-
inline ShiftRight_InPlace(size_t reg1, size_t d)
Constructor (ID version)
- Parameters:
reg1 – Register ID
d – Number of bits to shift
- Throws:
Throws – an exception when a register type is not an integer type
-
struct Sqrt_Div_Arccos_Int_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Square-root division arccosine operation (Out-of-place)
Implements: res ^= arccos(lhs / sqrt(rhs)) / π / 2
Used to compute quantum rotation angles, common in quantum amplitude encoding.
- Mathematical formula
output = arccos(lhs / √rhs) / (2π)
- Example
auto lhs = System::add_register("lhs", SignedInteger, 4); auto rhs = System::add_register("rhs", UnsignedInteger, 4); auto res = System::add_register("res", Rational, 8); Init_Unsafe(lhs, 1); // lhs = 1 Init_Unsafe(rhs, 4); // rhs = 4 // res = arccos(1/2) / 2π = 1/6 ≈ 0.167 Sqrt_Div_Arccos_Int_UInt("lhs", "rhs", "res");
Note
Unitarity: self-adjoint operator, implemented via XOR
Note
Data type: lhs must be SignedInteger, rhs must be UnsignedInteger, res must be Rational
Note
Numeric range: the result is in [0, 1), encoded as a rational
- Pre:
lhs must be of SignedInteger type
- Pre:
rhs must be of UnsignedInteger type
- Pre:
res must be of Rational type
- Pre:
|lhs| <= sqrt(rhs) (guarantees the arccos argument is within [-1,1])
- Pre:
all registers must be active
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Sqrt_Div_Arccos_Int_UInt(std::string_view lhs, std::string_view rhs, std::string_view out)
Constructor (name version)
- Parameters:
lhs – Left operand register name
rhs – Right operand register name
out – Output register name
-
inline Sqrt_Div_Arccos_Int_UInt(size_t reg_lhs, size_t reg_rhs, size_t reg_out)
Constructor (ID version)
- Parameters:
reg_lhs – Left operand register ID
reg_rhs – Right operand register ID
reg_out – Output register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the arithmetic operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Sqrt_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Unsigned integer square root operation (Out-of-place)
Implements out-of-place square root: res ^= floor(sqrt(reg))
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: reg and res must both be UnsignedInteger
Note
Implementation detail: a pure integer bit-by-bit square root algorithm (isqrt_u64) with no floating point involved, CPU and CUDA results are bit-for-bit identical
Note
Width and truncation: operands are zero-extended, quotient domain <= 64 bits, then XORed into res after taking mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Sqrt_UInt(std::string_view reg_, std::string_view res_)
Constructor (name version)
- Parameters:
reg_ – Input register name
res_ – Result register name
-
inline Sqrt_UInt(size_t reg_, size_t res_)
Constructor (ID version)
- Parameters:
reg_ – Input register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the square root operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()
-
struct Sub_UInt_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Unsigned integer subtraction operation (Out-of-place)
Implements out-of-place subtraction: res ^= lhs - rhs
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must all be UnsignedInteger
Note
Width and truncation: operands are zero-extended; the difference is evaluated on the unsigned 64-bit wrapping domain, then XORed into res after taking mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Sub_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_)
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Result register name
-
inline Sub_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_)
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the subtraction operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()
-
struct Swap_Bool_Bool : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Two-bit swap operation.
Swaps single bits at the specified positions of two registers
Implementation: swaps the values of the specified bits of the two registers using a temporary variable This is a self-adjoint operation; applying it twice yields the identity operation
- Example
// reg1 = 0b1010, reg2 = 0b0101 Swap_Bool_Bool("reg1", 0, "reg2", 1); // Swaps bit 0 of reg1 and bit 1 of reg2
Note
Unitarity: self-adjoint operator, Swap^2 = I
Note
Data type: boolean bits of registers of any type
- Pre:
the lhs and rhs registers must be active
- Pre:
digit1 and digit2 must be within the valid bit range of their registers [0, size)
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Swap_Bool_Bool(std::string_view reg1, size_t d1, std::string_view reg2, size_t d2)
Constructor (name version)
- Parameters:
reg1 – First register name
d1 – First bit index
reg2 – Second register name
d2 – Second bit index
- Throws:
Throws – an exception when a bit index is out of the register size
-
inline Swap_Bool_Bool(size_t id1, size_t d1, size_t id2, size_t d2)
Constructor (ID version)
- Parameters:
id1 – First register ID
d1 – First bit index
id2 – Second register ID
d2 – Second bit index
- Throws:
Throws – an exception when a bit index is out of the register size
-
virtual void operator()(std::vector<System> &state) const
Apply the swap operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Swap_General_General : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
General swap operation (In-place)
Swaps the complete values of two registers
Implementation: swaps the value fields of the two registers using std::swap. This is a self-adjoint operation; applying it twice yields the identity operation.
- Example
auto reg1 = System::add_register("reg1", UnsignedInteger, 4); auto reg2 = System::add_register("reg2", UnsignedInteger, 4); Init_Unsafe(reg1, 5); // reg1 = 5 Init_Unsafe(reg2, 10); // reg2 = 10 // After the swap: reg1 = 10, reg2 = 5 Swap_General_General("reg1", "reg2");
Note
Unitarity: self-adjoint operator, Swap^2 = I
Note
Data type: any type, but the two registers must have the same size
Note
Implementation detail: register values are swapped directly, without XOR or arithmetic operations
- Pre:
id1 and id2 must have the same size
- Pre:
all registers must be active
Public Functions
-
inline Swap_General_General(std::string_view regname1, std::string_view regname2)
Constructor (name version)
- Parameters:
regname1 – First register name
regname2 – Second register name
- Throws:
Throws – an exception when register sizes do not match
-
inline Swap_General_General(size_t regname1, size_t regname2)
Constructor (ID version)
- Parameters:
regname1 – First register ID
regname2 – Second register ID
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
virtual void operator()(std::vector<System> &state) const
Apply the swap operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
struct Xor_UInt_UInt : public qram_simulator::SelfAdjointOperator
- #include <quantum_arithmetic.h>
Unsigned integer bitwise XOR operation (Out-of-place)
Implements out-of-place bitwise XOR: res ^= lhs ^ rhs
Note
Unitarity: self-adjoint operator (U^† = U), because XOR is self-inverse
Note
Data type: lhs, rhs, and res must all be UnsignedInteger
Note
Width and truncation: operands are zero-extended; the result is then XORed into res after taking mod 2^res_width (docs/operators.md “Width and Truncation Convention”)
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Xor_UInt_UInt(std::string_view lhs_, std::string_view rhs_, std::string_view res_)
Constructor (name version)
- Parameters:
lhs_ – Left operand register name
rhs_ – Right operand register name
res_ – Result register name
-
inline Xor_UInt_UInt(size_t lhs_, size_t rhs_, size_t res_)
Constructor (ID version)
- Parameters:
lhs_ – Left operand register ID
rhs_ – Right operand register ID
res_ – Result register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the bitwise XOR operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()
-
using GenericArithmetic = std::function<std::vector<size_t>(const std::vector<size_t>&)>
并行相位操作（SparQ/include/parallel_phase_operations.h）¶
Parallel phase operation definitions.
Implements parallel conditional phase flips and global phase operations, supporting zero-conditional phase flips, range-conditional phase flips and reflection operations
-
namespace qram_simulator
QRAM sparse state simulator namespace.
Contains all classes, functions, and data structures related to quantum computing simulation
Typedefs
-
using GlobalPhase_Int = GlobalPhase
-
struct GlobalPhase : public qram_simulator::BaseOperator
- #include <parallel_phase_operations.h>
Global phase operation (integer register)
Applies a global phase to the whole state
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline GlobalPhase(complex_t c_)
Constructor.
- Parameters:
c_ – Phase factor
-
virtual void operator()(std::vector<System> &state) const
Apply the global phase operation.
- Parameters:
state – System state vector
-
virtual void dag(std::vector<System> &state) const
Apply the dagger operation (conjugate phase)
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()
-
struct RangeConditionalPhaseFlip : public qram_simulator::SelfAdjointOperator
- #include <parallel_phase_operations.h>
Range-conditional phase flip.
Applies a phase flip when the register value is within the specified range
Public Functions
-
inline RangeConditionalPhaseFlip(size_t id_, size_t range_)
Constructor (ID version)
- Parameters:
id_ – Register ID
range_ – Value range
-
inline RangeConditionalPhaseFlip(std::string_view reg_, size_t range_)
Constructor (name version)
- Parameters:
reg_ – Register name
range_ – Value range
-
virtual void operator()(std::vector<System> &state) const
Apply the phase flip operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
size_t id
Register ID.
-
size_t value_range
Value range.
-
inline RangeConditionalPhaseFlip(size_t id_, size_t range_)
-
struct Reflection_Bool : public qram_simulator::SelfAdjointOperator
- #include <parallel_phase_operations.h>
Boolean reflection operation.
Implements the Grover reflection operation: (I - 2|0><0|) or (2|0><0| - I)
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline Reflection_Bool(std::string_view reg_, bool inverse_ = false)
Constructor (single register name version)
- Parameters:
reg_ – Register name
inverse_ – Whether to use the inverse form (default false)
-
inline Reflection_Bool(size_t id_, bool inverse_ = false)
Constructor (single register ID version)
- Parameters:
id_ – Register ID
inverse_ – Whether to use the inverse form (default false)
-
inline Reflection_Bool(const std::vector<std::string> ®s_, bool inverse_ = false)
Constructor (multiple register names version)
- Parameters:
regs_ – List of register names
inverse_ – Whether to use the inverse form (default false)
-
inline Reflection_Bool(const std::vector<size_t> &ids_, bool inverse_ = false)
Constructor (multiple register IDs version)
- Parameters:
ids_ – List of register IDs
inverse_ – Whether to use the inverse form (default false)
-
virtual void operator()(std::vector<System> &state) const
Apply the reflection operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()
-
struct ZeroConditionalPhaseFlip : public qram_simulator::SelfAdjointOperator
- #include <parallel_phase_operations.h>
Zero-conditional phase flip.
Applies a phase flip when the specified registers are all zero
Public Functions
-
inline void clear_control_nonzeros()
-
inline auto &conditioned_by_nonzeros(std::string_view cond)
-
inline auto &conditioned_by_nonzeros(size_t cond)
-
inline auto &conditioned_by_nonzeros(const std::vector<size_t> &conds)
-
inline void clear_control_all_ones()
-
inline auto &conditioned_by_all_ones(std::string_view cond)
-
inline auto &conditioned_by_all_ones(size_t cond)
-
inline auto &conditioned_by_all_ones(const std::vector<size_t> &conds)
-
inline void clear_control_by_bit()
-
inline auto &conditioned_by_bit(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_bit(size_t cond, size_t pos)
-
inline void clear_control_by_value()
-
inline auto &conditioned_by_value(std::string_view cond, size_t pos)
-
inline auto &conditioned_by_value(size_t cond, size_t pos)
-
template<typename Operator>
inline void copy_control_conditions_to(Operator &target) const
-
inline ZeroConditionalPhaseFlip(const std::vector<size_t> ®s_)
Constructor (ID list version)
- Parameters:
regs_ – List of register IDs
-
inline ZeroConditionalPhaseFlip(const std::vector<std::string> ®s_)
Constructor (name list version)
- Parameters:
regs_ – List of register names
-
virtual void operator()(std::vector<System> &state) const
Apply the phase flip operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline void clear_control_nonzeros()
-
using GlobalPhase_Int = GlobalPhase
状态排序（SparQ/include/sort_state.h）¶
State sorting definitions.
Implements various sorting operations on quantum states, supporting sorting by key, unconditional sorting, sorting by amplitude, and other sorting modes
-
namespace qram_simulator
QRAM sparse state simulator namespace.
Contains all classes, functions, and data structures related to quantum computing simulation
Functions
-
inline uint64_t make_mask(const std::set<size_t> &qubit_ids)
Create a bit mask.
- Parameters:
qubit_ids – Set of qubit IDs
- Returns:
Bit mask
-
bool compare_equal(const System &a, const System &b, size_t out_id)
Compare two systems for equality (excluding a specified key)
Used by CondRot_General_Bool, CondRot_General_Bool_QW, Hadamard_Int, etc.
- Parameters:
a – First system
b – Second system
out_id – Excluded key (register ID)
- Returns:
Whether they are equal
-
bool compare_equal2(const System &a, const System &b, size_t out_id1, size_t out_id2)
Compare two systems for equality (excluding two specified keys)
Used by QRAM::set_branches
- Parameters:
a – First system
b – Second system
out_id1 – First excluded key (register ID)
out_id2 – Second excluded key (register ID)
- Returns:
Whether they are equal
-
bool compare_equal_rot(const System &a, const System &b, size_t out_id, uint64_t mask)
Compare two systems for equality (excluding a specified key and masked bits)
- Parameters:
a – First system
b – Second system
out_id – Excluded key (register ID)
mask – Bit mask
- Returns:
Whether they are equal
-
bool compare_equal_hadamard(const System &a, const System &b, size_t out_id, uint64_t mask)
Compare two systems for equality (Hadamard version)
Used by Hadamard_Partial; excludes the target qubit and the masked bits when comparing
- Parameters:
a – First system
b – Second system
out_id – Excluded key (register ID)
mask – Bit mask
- Returns:
Whether they are equal
-
struct SortByAmplitude : public qram_simulator::SelfAdjointOperator
- #include <sort_state.h>
Sort by amplitude.
Sorts the system states by amplitude
Public Functions
-
inline SortByAmplitude()
Default constructor.
-
virtual void operator()(std::vector<System> &states) const
Apply the sorting operation.
- Parameters:
states – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline SortByAmplitude()
-
struct SortByKey : public qram_simulator::SelfAdjointOperator
- #include <sort_state.h>
Sort by key.
Sorts by the value of the specified register
Public Functions
-
SortByKey(std::string_view key)
Constructor (name version)
- Parameters:
key – Register name
-
SortByKey(size_t key)
Constructor (ID version)
- Parameters:
key – Register ID
-
virtual void operator()(std::vector<System> &state) const
Apply the sorting operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
size_t register_key
Sort key (register ID)
-
SortByKey(std::string_view key)
-
struct SortByKey2 : public qram_simulator::SelfAdjointOperator
- #include <sort_state.h>
Two-key sorting.
Sorts by the values of two registers
Public Functions
-
inline SortByKey2(std::string_view key1_, std::string_view key2_)
Constructor (name version)
- Parameters:
key1_ – Name of the first register
key2_ – Name of the second register
-
inline SortByKey2(size_t key1_, size_t key2_)
Constructor (ID version)
- Parameters:
key1_ – ID of the first register
key2_ – ID of the second register
-
virtual void operator()(std::vector<System> &states) const
Apply the sorting operation.
- Parameters:
states – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
size_t id1
First key (register ID)
-
size_t id2
Second key (register ID)
-
inline SortByKey2(std::string_view key1_, std::string_view key2_)
-
struct SortExceptBit : public qram_simulator::SelfAdjointOperator
- #include <sort_state.h>
Sort excluding a bit.
Excludes the specified bit of a register during sorting
Public Functions
-
inline SortExceptBit(std::string_view key_, size_t digit_)
Constructor (name version)
- Parameters:
key_ – Register name
digit_ – Bit index
-
inline SortExceptBit(size_t key_, size_t digit_)
Constructor (ID version)
- Parameters:
key_ – Register ID
digit_ – Bit index
-
virtual void operator()(std::vector<System> &states) const
Apply the sorting operation.
- Parameters:
states – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
size_t id
Register ID.
-
size_t digit
Bit index.
-
inline SortExceptBit(std::string_view key_, size_t digit_)
-
struct SortExceptKey : public qram_simulator::SelfAdjointOperator
- #include <sort_state.h>
Sort excluding a key.
Excludes the specified key during sorting, so that it is moved to the end
Public Functions
-
inline SortExceptKey(std::string_view key_)
Constructor (name version)
- Parameters:
key_ – Register name
-
inline SortExceptKey(size_t key_)
Constructor (ID version)
- Parameters:
key_ – Register ID
-
virtual void operator()(std::vector<System> &states) const
Apply the sorting operation.
- Parameters:
states – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
size_t id
Excluded key (register ID)
-
inline SortExceptKey(std::string_view key_)
-
struct SortExceptKeyHadamard : public qram_simulator::SelfAdjointOperator
- #include <sort_state.h>
Hadamard sort-except-key.
Excluded-key sorting optimized for the Hadamard operation
Public Functions
-
inline SortExceptKeyHadamard(std::string_view key_, std::set<size_t> qubit_ids_)
Constructor (name version)
- Parameters:
key_ – Register name
qubit_ids_ – Set of qubit IDs
-
inline SortExceptKeyHadamard(size_t key_, std::set<size_t> qubit_ids_)
Constructor (ID version)
- Parameters:
key_ – Register ID
qubit_ids_ – Set of qubit IDs
-
size_t remove_digits(size_t val) const
Remove the specified bit.
- Parameters:
val – Original value
- Returns:
Value with the bit removed
-
virtual void operator()(std::vector<System> &states) const
Apply the sorting operation.
- Parameters:
states – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
size_t id
Excluded key (register ID)
-
uint64_t mask
Bit mask.
-
std::set<size_t> qubit_ids
Set of qubit IDs.
-
inline SortExceptKeyHadamard(std::string_view key_, std::set<size_t> qubit_ids_)
-
struct SortUnconditional : public qram_simulator::SelfAdjointOperator
- #include <sort_state.h>
Unconditional sorting.
Performs unconditional parallel sorting of the system states
Public Functions
-
inline SortUnconditional()
Default constructor.
-
virtual void operator()(std::vector<System> &states) const
Apply the sorting operation.
- Parameters:
states – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline SortUnconditional()
-
inline uint64_t make_mask(const std::set<size_t> &qubit_ids)
暗魔法算子（SparQ/include/dark_magic.h）¶
Internal optimized operations definitions.
Contains low-level optimized operations such as normalization and unsafe initialization; these operations are usually used for internal implementations, use them with care
-
namespace qram_simulator
QRAM sparse state simulator namespace.
Contains all classes, functions, and data structures related to quantum computing simulation
-
struct Init_Unsafe : public qram_simulator::SelfAdjointOperator
- #include <dark_magic.h>
Unsafe initialization operation.
Directly sets a register to the specified value without safety checks
Warning
This operation does not check whether the value exceeds the register range; use it with care
Public Functions
-
inline Init_Unsafe(int id_, size_t value_)
Constructor (ID version)
- Parameters:
id_ – Register ID
value_ – Value to set
-
inline Init_Unsafe(std::string_view reg, size_t value_)
Constructor (name version)
- Parameters:
reg – Register name
value_ – Value to set
-
virtual void operator()(std::vector<System> &system_states) const
Apply the unsafe initialization operation.
- Parameters:
system_states – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
Public Members
-
size_t value
Value to set.
-
size_t id
Register ID.
-
inline Init_Unsafe(int id_, size_t value_)
-
struct Normalize : public qram_simulator::SelfAdjointOperator
- #include <dark_magic.h>
Normalization operation.
Normalizes a quantum state so that the total probability is 1
Public Functions
-
virtual void operator()(std::vector<System> &state) const
Apply the normalization operation.
- Parameters:
state – System state vector
-
inline virtual void dag(std::vector<System> &state) const override
Apply the dagger operation (the dagger of a self-adjoint operator equals itself)
- Parameters:
state – System state vector
-
inline virtual void dag(SparseState &state) const override
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
inline virtual void dag(std::vector<System> &state) const
Apply the conjugate transpose (dagger) operation.
- Parameters:
state – System state vector
- Throws:
Throws – a not-implemented exception by default
-
inline virtual void dag(SparseState &state) const
Apply dagger to a SparseState.
- Parameters:
state – Sparse state
-
virtual void operator()(std::vector<System> &state) const
-
struct Init_Unsafe : public qram_simulator::SelfAdjointOperator