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¶
Operator |
Operation |
Unitarity class |
|---|---|---|
|
Standard QRAM load |
SelfAdjoint |
|
Optimized QRAM load |
SelfAdjoint |
Quantum Parallel Data Access¶
QRAM implements quantum parallel memory access:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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)
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)
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)
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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)
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)
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)
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.
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.
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.
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.
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:
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 Database Search¶
# Database contents
database = [42, 17, 99, 5, ...]
# Create the QRAM (memory is passed in at construction)
qram = ps.QRAMCircuit_qutrit(addr_bits, data_bits, database)
# Address register in superposition
ps.Hadamard_Int_Full("addr")(state)
# Load all data items in parallel
ps.QRAMLoad(qram, "addr", "data")(state)
# Now you can search for a specific value...
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