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:

1. 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

2. 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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t reg

Input register ID.

size_t res

Result register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t add_int

Addend (constant)

size_t reg_in

Input register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t mult_int

Multiplier (constant)

size_t lhs

Left operand register ID.

size_t res

Result register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t add_int

Addend (constant)

size_t lhs

Left operand register ID.

size_t res

Result register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t lhs

Left operand register ID.

size_t rhs

Right operand register ID.

size_t res

Result register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t lhs

Left operand register ID.

size_t rhs

Right operand register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t lhs

Left operand register ID.

size_t rhs

Right operand register ID.

size_t res

Result register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t register_1

First register ID.

size_t register_2

Second register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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

1. CustomArithmetic is only meaningful in a sparse state simulator;

2. Any pass that “lowers an algorithm to a physical backend / Clifford+T / OriginIR” should not treat CustomArithmetic as a valid target primitive;

3. 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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t register_lhs

Left operand register ID.

size_t register_rhs

Right operand register ID.

size_t register_out

Output register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t lhs

Left operand register ID.

size_t rhs

Right operand register ID.

size_t res

Result register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

size_t id

Register ID.

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t left_id

Left operand register ID.

size_t right_id

Right operand register ID.

size_t mid_id

Midpoint result register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t register_lhs

Left operand register ID.

size_t register_rhs

Right operand register ID.

size_t register_out

Output register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t reg

Input register ID.

size_t flag_id

Zero-test result flag register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t lhs

Left operand register ID.

size_t rhs

Right operand register ID.

size_t flag_id

Less-than result flag register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

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 result register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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:

1. a and N must be coprime (gcd(a, N) = 1)

2. 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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t reg

Operand register ID.

uint64_t a

Base.

uint64_t x

Exponent bit (computes a^(2^x))

uint64_t N

Modulus.

uint64_t opnum

Precomputed operand opnum = a^(2^x) mod N.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t lhs

Left operand register ID.

size_t rhs

Right operand register ID.

size_t res

Result register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t mult_int

Multiplier (constant)

size_t lhs

Left operand register ID.

size_t res

Result register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t reg

Input register ID.

size_t res

Result register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t reg

Input register ID.

size_t flag_id

Negative-test result flag register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t lhs

Left operand register ID.

size_t rhs

Right operand register ID.

size_t res

Result register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t cond

Condition register ID.

size_t lhs

Left operand register ID.

size_t rhs

Right operand register ID.

size_t res

Result register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

virtual void operator()(std::vector<System> &state) const

Apply the left-rotate operation.

Parameters:

state – System state vector

Public Members

size_t register_1

Register ID.

size_t digit

Number of bits to shift.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

virtual void operator()(std::vector<System> &state) const

Apply the right-rotate operation.

Parameters:

state – System state vector

Public Members

size_t register_1

Register ID.

size_t digit

Number of bits to shift.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t register_lhs

Left operand register ID.

size_t register_rhs

Right operand register ID.

size_t register_out

Output register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t reg

Input register ID.

size_t res

Result register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t lhs

Left operand register ID.

size_t rhs

Right operand register ID.

size_t res

Result register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t lhs

Left operand register ID.

size_t rhs

Right operand register ID.

size_t digit1

Left operand bit index.

size_t digit2

Right operand bit index.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t id1

First register ID.

size_t id2

Second register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

size_t lhs

Left operand register ID.

size_t rhs

Right operand register ID.

size_t res

Result register ID.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(std::string_view cond)

inline auto &conditioned_by_nonzeros(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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

Public Members

complex_t c

Phase factor.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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.

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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> &regs_, 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

std::vector<size_t> regs

List of register IDs.

bool inverse

Whether to use the inverse form (true: I-2|0><0|, false: 2|0><0|-I)

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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(const std::vector<std::string_view> &conds)

inline auto &conditioned_by_nonzeros(const std::vector<std::string> &conds)

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(const std::vector<std::string_view> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_bit(const std::vector<std::pair<size_t, size_t>> &conds)

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(const std::vector<std::pair<std::string, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<std::string_view, size_t>> &conds)

inline auto &conditioned_by_value(const std::vector<std::pair<size_t, size_t>> &conds)

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> &regs_)

Constructor (ID list version)

Parameters:

regs_ – List of register IDs

inline ZeroConditionalPhaseFlip(const std::vector<std::string> &regs_)

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

Public Members

std::vector<size_t> ids

List of register IDs.

std::vector<size_t> condition_variable_nonzeros

std::vector<size_t> condition_variable_all_ones

std::vector<std::pair<size_t, size_t>> condition_variable_by_bit

std::vector<std::pair<size_t, size_t>> condition_variable_by_value

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

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)

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)

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.

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)

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.

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

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

Public Members

size_t value

Value to set.

size_t id

Register ID.

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