QRAM Operators

QRAM (Quantum Random Access Memory) operators implement quantum parallel data access. The C++-only qubit-circuit variant is documented under QRAM operations (C++), and uniform address superpositions are typically prepared with Hadamard_Int_Full.

Overview

QRAM operators overview

Operator

Operation

Unitarity class

QRAMLoad

Standard QRAM load

SelfAdjoint

QRAMLoadFast

Optimized QRAM load

SelfAdjoint

Quantum Parallel Data Access

QRAM implements quantum parallel memory access:

\[\sum_x \alpha_x |x\rangle |0\rangle \xrightarrow{QRAM} \sum_x \alpha_x |x\rangle |f(x)\rangle\]

This allows quantum algorithms to access multiple data items simultaneously.

—

QRAMLoad

class pysparq.QRAMLoad

Load classical data into quantum superposition via QRAM.

Performs the QRAM load operation, creating a superposition where each basis state is entangled with its corresponding data value.

Parameters:
  • qram – QRAMCircuit_qutrit instance containing the memory.

  • addr_reg – Name/ID of the address register.

  • data_reg – Name/ID of the data register.

Example

qram = QRAMCircuit_qutrit(addr_size=3, data_size=4, memory=data) QRAMLoad(qram, “address”, “data”)(state)

Note

Use QRAMLoadFast for optimized execution when address distribution is uniform.

clear_control_all_ones(self: pysparq._core.QRAMLoad) → None

Clear all control conditions of the specified type.

clear_control_by_bit(self: pysparq._core.QRAMLoad) → None

Clear all control conditions of the specified type.

clear_control_by_value(self: pysparq._core.QRAMLoad) → None

Clear all control conditions of the specified type.

clear_control_nonzeros(self: pysparq._core.QRAMLoad) → None

Clear all control conditions of the specified type.

property condition_variable_all_ones
property condition_variable_by_bit
property condition_variable_by_value
property condition_variable_nonzeros
conditioned_by_all_ones(*args, **kwargs)

Overloaded function.

  1. conditioned_by_all_ones(self: pysparq._core.QRAMLoad, cond: str) -> pysparq._core.QRAMLoad

Condition this operation on registers where all bits are 1.

Calling this method replaces prior all-ones conditions. Pass the list overload to require several registers simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int) to condition on.

  • conds – List of register names or IDs for multi-condition.

Returns:

Self, for method chaining.

  1. conditioned_by_all_ones(self: pysparq._core.QRAMLoad, conds: collections.abc.Sequence[str]) -> pysparq._core.QRAMLoad

Condition this operation on registers where all bits are 1.

Calling this method replaces prior all-ones conditions. Pass the list overload to require several registers simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int) to condition on.

  • conds – List of register names or IDs for multi-condition.

Returns:

Self, for method chaining.

  1. conditioned_by_all_ones(self: pysparq._core.QRAMLoad, cond: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.QRAMLoad

Condition this operation on registers where all bits are 1.

Calling this method replaces prior all-ones conditions. Pass the list overload to require several registers simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int) to condition on.

  • conds – List of register names or IDs for multi-condition.

Returns:

Self, for method chaining.

  1. conditioned_by_all_ones(self: pysparq._core.QRAMLoad, conds: collections.abc.Sequence[typing.SupportsInt | typing.SupportsIndex]) -> pysparq._core.QRAMLoad

Condition this operation on registers where all bits are 1.

Calling this method replaces prior all-ones conditions. Pass the list overload to require several registers simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int) to condition on.

  • conds – List of register names or IDs for multi-condition.

Returns:

Self, for method chaining.

conditioned_by_bit(*args, **kwargs)

Overloaded function.

  1. conditioned_by_bit(self: pysparq._core.QRAMLoad, cond: str, pos: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.QRAMLoad

Condition this operation on a specific bit position.

Calling this method replaces prior bit conditions. Pass the list-of-pairs overload to require several bits simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int).

  • pos – Bit position to check (0-indexed).

  • conds – List of (register, position) pairs.

Returns:

Self, for method chaining.

  1. conditioned_by_bit(self: pysparq._core.QRAMLoad, conds: collections.abc.Sequence[tuple[str, typing.SupportsInt | typing.SupportsIndex]]) -> pysparq._core.QRAMLoad

Condition this operation on a specific bit position.

Calling this method replaces prior bit conditions. Pass the list-of-pairs overload to require several bits simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int).

  • pos – Bit position to check (0-indexed).

  • conds – List of (register, position) pairs.

Returns:

Self, for method chaining.

  1. conditioned_by_bit(self: pysparq._core.QRAMLoad, cond: typing.SupportsInt | typing.SupportsIndex, pos: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.QRAMLoad

Condition this operation on a specific bit position.

Calling this method replaces prior bit conditions. Pass the list-of-pairs overload to require several bits simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int).

  • pos – Bit position to check (0-indexed).

  • conds – List of (register, position) pairs.

Returns:

Self, for method chaining.

  1. conditioned_by_bit(self: pysparq._core.QRAMLoad, conds: collections.abc.Sequence[tuple[typing.SupportsInt | typing.SupportsIndex, typing.SupportsInt | typing.SupportsIndex]]) -> pysparq._core.QRAMLoad

Condition this operation on a specific bit position.

Calling this method replaces prior bit conditions. Pass the list-of-pairs overload to require several bits simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int).

  • pos – Bit position to check (0-indexed).

  • conds – List of (register, position) pairs.

Returns:

Self, for method chaining.

conditioned_by_nonzeros(*args, **kwargs)

Overloaded function.

  1. conditioned_by_nonzeros(self: pysparq._core.QRAMLoad, cond: str) -> pysparq._core.QRAMLoad

Condition this operation on registers with nonzero values.

Calling this method replaces prior nonzero-register conditions. Pass the list overload to require several registers simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int) to condition on.

  • conds – List of register names or IDs for multi-condition.

Returns:

Self, for method chaining.

Example

op.conditioned_by_nonzeros(‘control_reg’)(state)

  1. conditioned_by_nonzeros(self: pysparq._core.QRAMLoad, conds: collections.abc.Sequence[str]) -> pysparq._core.QRAMLoad

Condition this operation on registers with nonzero values.

Calling this method replaces prior nonzero-register conditions. Pass the list overload to require several registers simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int) to condition on.

  • conds – List of register names or IDs for multi-condition.

Returns:

Self, for method chaining.

Example

op.conditioned_by_nonzeros(‘control_reg’)(state)

  1. conditioned_by_nonzeros(self: pysparq._core.QRAMLoad, cond: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.QRAMLoad

Condition this operation on registers with nonzero values.

Calling this method replaces prior nonzero-register conditions. Pass the list overload to require several registers simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int) to condition on.

  • conds – List of register names or IDs for multi-condition.

Returns:

Self, for method chaining.

Example

op.conditioned_by_nonzeros(‘control_reg’)(state)

  1. conditioned_by_nonzeros(self: pysparq._core.QRAMLoad, conds: collections.abc.Sequence[typing.SupportsInt | typing.SupportsIndex]) -> pysparq._core.QRAMLoad

Condition this operation on registers with nonzero values.

Calling this method replaces prior nonzero-register conditions. Pass the list overload to require several registers simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int) to condition on.

  • conds – List of register names or IDs for multi-condition.

Returns:

Self, for method chaining.

Example

op.conditioned_by_nonzeros(‘control_reg’)(state)

conditioned_by_value(*args, **kwargs)

Overloaded function.

  1. conditioned_by_value(self: pysparq._core.QRAMLoad, cond: str, pos: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.QRAMLoad

Condition this operation on registers holding a specific value.

Calling this method replaces prior value conditions. Pass the list-of-pairs overload to require several values simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int).

  • pos – Value to match.

  • conds – List of (register, value) pairs.

Returns:

Self, for method chaining.

  1. conditioned_by_value(self: pysparq._core.QRAMLoad, conds: collections.abc.Sequence[tuple[str, typing.SupportsInt | typing.SupportsIndex]]) -> pysparq._core.QRAMLoad

Condition this operation on registers holding a specific value.

Calling this method replaces prior value conditions. Pass the list-of-pairs overload to require several values simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int).

  • pos – Value to match.

  • conds – List of (register, value) pairs.

Returns:

Self, for method chaining.

  1. conditioned_by_value(self: pysparq._core.QRAMLoad, cond: typing.SupportsInt | typing.SupportsIndex, pos: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.QRAMLoad

Condition this operation on registers holding a specific value.

Calling this method replaces prior value conditions. Pass the list-of-pairs overload to require several values simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int).

  • pos – Value to match.

  • conds – List of (register, value) pairs.

Returns:

Self, for method chaining.

  1. conditioned_by_value(self: pysparq._core.QRAMLoad, conds: collections.abc.Sequence[tuple[typing.SupportsInt | typing.SupportsIndex, typing.SupportsInt | typing.SupportsIndex]]) -> pysparq._core.QRAMLoad

Condition this operation on registers holding a specific value.

Calling this method replaces prior value conditions. Pass the list-of-pairs overload to require several values simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int).

  • pos – Value to match.

  • conds – List of (register, value) pairs.

Returns:

Self, for method chaining.

property qram_circuit
version = ''

Operation: Loads data from the QRAM circuit into a quantum register

Type constraints: - Address register: UnsignedInteger - Data register: UnsignedInteger or General

Bit constraints: - The address size must match the QRAM configuration - The data size must match the QRAM data width

import pysparq as ps

ps.System.clear()

# Create a QRAM circuit (qutrit version)
addr_size = 4  # 4-bit address → 16 memory cells
data_size = 8  # 8-bit data

# Set the memory contents (memory must be passed in at construction)
memory = [i * 10 for i in range(16)]  # 0, 10, 20, ..., 150
qram = ps.QRAMCircuit_qutrit(addr_size, data_size, memory)

# Create registers
ps.System.add_register("addr", ps.UnsignedInteger, addr_size)
ps.System.add_register("data", ps.UnsignedInteger, data_size)

state = ps.SparseState()

# Uniform superposition on the address register
ps.Hadamard_Int_Full("addr")(state)

# QRAM load: access all addresses in parallel
ps.QRAMLoad(qram, "addr", "data")(state)

ps.pprint(state)
# The output contains 16 states:
# |addr=0,data=0⟩, |addr=1,data=10⟩, ...

# QRAMLoad is self-adjoint; applying it again undoes the load
ps.QRAMLoad(qram, "addr", "data")(state)
# The data register is zeroed

QRAMLoadFast

class pysparq.QRAMLoadFast
clear_control_all_ones(self: pysparq._core.QRAMLoadFast) → None

Clear all control conditions of the specified type.

clear_control_by_bit(self: pysparq._core.QRAMLoadFast) → None

Clear all control conditions of the specified type.

clear_control_by_value(self: pysparq._core.QRAMLoadFast) → None

Clear all control conditions of the specified type.

clear_control_nonzeros(self: pysparq._core.QRAMLoadFast) → None

Clear all control conditions of the specified type.

property condition_variable_all_ones
property condition_variable_by_bit
property condition_variable_by_value
property condition_variable_nonzeros
conditioned_by_all_ones(*args, **kwargs)

Overloaded function.

  1. conditioned_by_all_ones(self: pysparq._core.QRAMLoadFast, cond: str) -> pysparq._core.QRAMLoadFast

Condition this operation on registers where all bits are 1.

Calling this method replaces prior all-ones conditions. Pass the list overload to require several registers simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int) to condition on.

  • conds – List of register names or IDs for multi-condition.

Returns:

Self, for method chaining.

  1. conditioned_by_all_ones(self: pysparq._core.QRAMLoadFast, conds: collections.abc.Sequence[str]) -> pysparq._core.QRAMLoadFast

Condition this operation on registers where all bits are 1.

Calling this method replaces prior all-ones conditions. Pass the list overload to require several registers simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int) to condition on.

  • conds – List of register names or IDs for multi-condition.

Returns:

Self, for method chaining.

  1. conditioned_by_all_ones(self: pysparq._core.QRAMLoadFast, cond: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.QRAMLoadFast

Condition this operation on registers where all bits are 1.

Calling this method replaces prior all-ones conditions. Pass the list overload to require several registers simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int) to condition on.

  • conds – List of register names or IDs for multi-condition.

Returns:

Self, for method chaining.

  1. conditioned_by_all_ones(self: pysparq._core.QRAMLoadFast, conds: collections.abc.Sequence[typing.SupportsInt | typing.SupportsIndex]) -> pysparq._core.QRAMLoadFast

Condition this operation on registers where all bits are 1.

Calling this method replaces prior all-ones conditions. Pass the list overload to require several registers simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int) to condition on.

  • conds – List of register names or IDs for multi-condition.

Returns:

Self, for method chaining.

conditioned_by_bit(*args, **kwargs)

Overloaded function.

  1. conditioned_by_bit(self: pysparq._core.QRAMLoadFast, cond: str, pos: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.QRAMLoadFast

Condition this operation on a specific bit position.

Calling this method replaces prior bit conditions. Pass the list-of-pairs overload to require several bits simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int).

  • pos – Bit position to check (0-indexed).

  • conds – List of (register, position) pairs.

Returns:

Self, for method chaining.

  1. conditioned_by_bit(self: pysparq._core.QRAMLoadFast, conds: collections.abc.Sequence[tuple[str, typing.SupportsInt | typing.SupportsIndex]]) -> pysparq._core.QRAMLoadFast

Condition this operation on a specific bit position.

Calling this method replaces prior bit conditions. Pass the list-of-pairs overload to require several bits simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int).

  • pos – Bit position to check (0-indexed).

  • conds – List of (register, position) pairs.

Returns:

Self, for method chaining.

  1. conditioned_by_bit(self: pysparq._core.QRAMLoadFast, cond: typing.SupportsInt | typing.SupportsIndex, pos: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.QRAMLoadFast

Condition this operation on a specific bit position.

Calling this method replaces prior bit conditions. Pass the list-of-pairs overload to require several bits simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int).

  • pos – Bit position to check (0-indexed).

  • conds – List of (register, position) pairs.

Returns:

Self, for method chaining.

  1. conditioned_by_bit(self: pysparq._core.QRAMLoadFast, conds: collections.abc.Sequence[tuple[typing.SupportsInt | typing.SupportsIndex, typing.SupportsInt | typing.SupportsIndex]]) -> pysparq._core.QRAMLoadFast

Condition this operation on a specific bit position.

Calling this method replaces prior bit conditions. Pass the list-of-pairs overload to require several bits simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int).

  • pos – Bit position to check (0-indexed).

  • conds – List of (register, position) pairs.

Returns:

Self, for method chaining.

conditioned_by_nonzeros(*args, **kwargs)

Overloaded function.

  1. conditioned_by_nonzeros(self: pysparq._core.QRAMLoadFast, cond: str) -> pysparq._core.QRAMLoadFast

Condition this operation on registers with nonzero values.

Calling this method replaces prior nonzero-register conditions. Pass the list overload to require several registers simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int) to condition on.

  • conds – List of register names or IDs for multi-condition.

Returns:

Self, for method chaining.

Example

op.conditioned_by_nonzeros(‘control_reg’)(state)

  1. conditioned_by_nonzeros(self: pysparq._core.QRAMLoadFast, conds: collections.abc.Sequence[str]) -> pysparq._core.QRAMLoadFast

Condition this operation on registers with nonzero values.

Calling this method replaces prior nonzero-register conditions. Pass the list overload to require several registers simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int) to condition on.

  • conds – List of register names or IDs for multi-condition.

Returns:

Self, for method chaining.

Example

op.conditioned_by_nonzeros(‘control_reg’)(state)

  1. conditioned_by_nonzeros(self: pysparq._core.QRAMLoadFast, cond: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.QRAMLoadFast

Condition this operation on registers with nonzero values.

Calling this method replaces prior nonzero-register conditions. Pass the list overload to require several registers simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int) to condition on.

  • conds – List of register names or IDs for multi-condition.

Returns:

Self, for method chaining.

Example

op.conditioned_by_nonzeros(‘control_reg’)(state)

  1. conditioned_by_nonzeros(self: pysparq._core.QRAMLoadFast, conds: collections.abc.Sequence[typing.SupportsInt | typing.SupportsIndex]) -> pysparq._core.QRAMLoadFast

Condition this operation on registers with nonzero values.

Calling this method replaces prior nonzero-register conditions. Pass the list overload to require several registers simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int) to condition on.

  • conds – List of register names or IDs for multi-condition.

Returns:

Self, for method chaining.

Example

op.conditioned_by_nonzeros(‘control_reg’)(state)

conditioned_by_value(*args, **kwargs)

Overloaded function.

  1. conditioned_by_value(self: pysparq._core.QRAMLoadFast, cond: str, pos: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.QRAMLoadFast

Condition this operation on registers holding a specific value.

Calling this method replaces prior value conditions. Pass the list-of-pairs overload to require several values simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int).

  • pos – Value to match.

  • conds – List of (register, value) pairs.

Returns:

Self, for method chaining.

  1. conditioned_by_value(self: pysparq._core.QRAMLoadFast, conds: collections.abc.Sequence[tuple[str, typing.SupportsInt | typing.SupportsIndex]]) -> pysparq._core.QRAMLoadFast

Condition this operation on registers holding a specific value.

Calling this method replaces prior value conditions. Pass the list-of-pairs overload to require several values simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int).

  • pos – Value to match.

  • conds – List of (register, value) pairs.

Returns:

Self, for method chaining.

  1. conditioned_by_value(self: pysparq._core.QRAMLoadFast, cond: typing.SupportsInt | typing.SupportsIndex, pos: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.QRAMLoadFast

Condition this operation on registers holding a specific value.

Calling this method replaces prior value conditions. Pass the list-of-pairs overload to require several values simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int).

  • pos – Value to match.

  • conds – List of (register, value) pairs.

Returns:

Self, for method chaining.

  1. conditioned_by_value(self: pysparq._core.QRAMLoadFast, conds: collections.abc.Sequence[tuple[typing.SupportsInt | typing.SupportsIndex, typing.SupportsInt | typing.SupportsIndex]]) -> pysparq._core.QRAMLoadFast

Condition this operation on registers holding a specific value.

Calling this method replaces prior value conditions. Pass the list-of-pairs overload to require several values simultaneously; conditions of different kinds are combined with logical AND.

Parameters:
  • cond – Register name (str) or ID (int).

  • pos – Value to match.

  • conds – List of (register, value) pairs.

Returns:

Self, for method chaining.

Operation: Optimized QRAM load

Characteristics: Optimized for specific memory patterns, with higher performance.

# Fast load (same interface)
ps.QRAMLoadFast(qram, "addr", "data")(state)

—

QRAMCircuit_qutrit

PySparQ provides the QRAMCircuit_qutrit class for configuring a QRAM:

class pysparq.QRAMCircuit_qutrit
property address_size
property data_size

Note

QRAMCircuit_qubit (the qubit-version QRAM in the C++ API) is not available in PySparQ. PySparQ provides only the qutrit version.

Creating and Configuring a QRAM Circuit

import pysparq as ps

# Create a QRAM circuit
addr_bits = 4   # number of address bits
data_bits = 8   # number of data bits

# Set the memory contents (memory must be passed in at construction)
memory_list = [0, 10, 20, 30, 40, 50, 60, 70,
               80, 90, 100, 110, 120, 130, 140, 150]
qram = ps.QRAMCircuit_qutrit(addr_bits, data_bits, memory_list)

# Note: the set_memory() method is not available in PySparQ
# memory must be passed in when constructing QRAMCircuit_qutrit

# Query information
print(f"Address size: {qram.addr_size}")
print(f"Data size: {qram.data_size}")

Conditional Loading

QRAM loading supports conditional execution:

op = ps.QRAMLoad(qram, "addr", "data")

# Load only when control is nonzero
op.conditioned_by_nonzeros("control")(state)

# Load only when bit 0 of flag is 1
op.conditioned_by_bit("flag", 0)(state)

Use Cases

Quantum Machine Learning

# Load training data (memory is passed in at construction)
qram = ps.QRAMCircuit_qutrit(addr_bits, data_bits, training_data)
ps.Hadamard_Int_Full("sample_id")(state)
ps.QRAMLoad(qram, "sample_id", "sample_data")(state)

# All training samples can now be processed in parallel