Rotation and State Preparation¶
Rotation and state preparation operators provide arbitrary-dimensional unitary rotations and the ability to prepare a target quantum state from |0⟩. QRAM-based state preparation built on them is part of the algorithm library.
Overview¶
Operator |
Operation |
Unitarity class |
|---|---|---|
|
Apply an arbitrary-dimensional unitary matrix |
BaseOperator |
|
Prepare a target quantum state from |
BaseOperator |
—
Rot_GeneralUnitary (general unitary rotation)¶
- class pysparq.Rot_GeneralUnitary¶
- clear_control_all_ones(self: pysparq._core.Rot_GeneralUnitary) None¶
Clear all control conditions of the specified type.
- clear_control_by_bit(self: pysparq._core.Rot_GeneralUnitary) None¶
Clear all control conditions of the specified type.
- clear_control_by_value(self: pysparq._core.Rot_GeneralUnitary) None¶
Clear all control conditions of the specified type.
- clear_control_nonzeros(self: pysparq._core.Rot_GeneralUnitary) 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.Rot_GeneralUnitary, cond: str) -> pysparq._core.Rot_GeneralUnitary
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.Rot_GeneralUnitary, conds: collections.abc.Sequence[str]) -> pysparq._core.Rot_GeneralUnitary
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.Rot_GeneralUnitary, cond: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.Rot_GeneralUnitary
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.Rot_GeneralUnitary, conds: collections.abc.Sequence[typing.SupportsInt | typing.SupportsIndex]) -> pysparq._core.Rot_GeneralUnitary
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.Rot_GeneralUnitary, cond: str, pos: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.Rot_GeneralUnitary
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.Rot_GeneralUnitary, conds: collections.abc.Sequence[tuple[str, typing.SupportsInt | typing.SupportsIndex]]) -> pysparq._core.Rot_GeneralUnitary
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.Rot_GeneralUnitary, cond: typing.SupportsInt | typing.SupportsIndex, pos: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.Rot_GeneralUnitary
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.Rot_GeneralUnitary, conds: collections.abc.Sequence[tuple[typing.SupportsInt | typing.SupportsIndex, typing.SupportsInt | typing.SupportsIndex]]) -> pysparq._core.Rot_GeneralUnitary
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.Rot_GeneralUnitary, cond: str) -> pysparq._core.Rot_GeneralUnitary
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.Rot_GeneralUnitary, conds: collections.abc.Sequence[str]) -> pysparq._core.Rot_GeneralUnitary
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.Rot_GeneralUnitary, cond: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.Rot_GeneralUnitary
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.Rot_GeneralUnitary, conds: collections.abc.Sequence[typing.SupportsInt | typing.SupportsIndex]) -> pysparq._core.Rot_GeneralUnitary
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.Rot_GeneralUnitary, cond: str, pos: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.Rot_GeneralUnitary
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.Rot_GeneralUnitary, conds: collections.abc.Sequence[tuple[str, typing.SupportsInt | typing.SupportsIndex]]) -> pysparq._core.Rot_GeneralUnitary
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.Rot_GeneralUnitary, cond: typing.SupportsInt | typing.SupportsIndex, pos: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.Rot_GeneralUnitary
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.Rot_GeneralUnitary, conds: collections.abc.Sequence[tuple[typing.SupportsInt | typing.SupportsIndex, typing.SupportsInt | typing.SupportsIndex]]) -> pysparq._core.Rot_GeneralUnitary
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: Applies an arbitrary \(2^n \times 2^n\) unitary matrix to a register.
Parameters:
reg— target register (name or ID)matrix— unitary matrix (DenseMatrix_complexor a NumPy array)
Dagger: Applies the conjugate transpose of the matrix.
Purpose: When the standard gate library cannot directly express the desired transformation, you can specify it directly in matrix form.
Note
The matrix dimension must match the Hilbert-space dimension \(2^n\) of the register, where \(n\) is the number of bits in the register.
import numpy as np
import pysparq as ps
ps.System.clear()
ps.System.add_register("q", ps.UnsignedInteger, 2)
state = ps.SparseState()
# Define a 4x4 unitary matrix
matrix = np.eye(4, dtype=complex)
matrix[0, 0] = 0
matrix[0, 3] = 1
matrix[3, 3] = 0
matrix[3, 0] = 1
op = ps.Rot_GeneralUnitary("q", matrix)
op(state)
# Undo
op.dag(state)
—
Rot_GeneralStatePrep (quantum state preparation)¶
- class pysparq.Rot_GeneralStatePrep¶
- clear_control_all_ones(self: pysparq._core.Rot_GeneralStatePrep) None¶
Clear all control conditions of the specified type.
- clear_control_by_bit(self: pysparq._core.Rot_GeneralStatePrep) None¶
Clear all control conditions of the specified type.
- clear_control_by_value(self: pysparq._core.Rot_GeneralStatePrep) None¶
Clear all control conditions of the specified type.
- clear_control_nonzeros(self: pysparq._core.Rot_GeneralStatePrep) 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.Rot_GeneralStatePrep, cond: str) -> pysparq._core.Rot_GeneralStatePrep
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.Rot_GeneralStatePrep, conds: collections.abc.Sequence[str]) -> pysparq._core.Rot_GeneralStatePrep
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.Rot_GeneralStatePrep, cond: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.Rot_GeneralStatePrep
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.Rot_GeneralStatePrep, conds: collections.abc.Sequence[typing.SupportsInt | typing.SupportsIndex]) -> pysparq._core.Rot_GeneralStatePrep
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.Rot_GeneralStatePrep, cond: str, pos: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.Rot_GeneralStatePrep
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.Rot_GeneralStatePrep, conds: collections.abc.Sequence[tuple[str, typing.SupportsInt | typing.SupportsIndex]]) -> pysparq._core.Rot_GeneralStatePrep
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.Rot_GeneralStatePrep, cond: typing.SupportsInt | typing.SupportsIndex, pos: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.Rot_GeneralStatePrep
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.Rot_GeneralStatePrep, conds: collections.abc.Sequence[tuple[typing.SupportsInt | typing.SupportsIndex, typing.SupportsInt | typing.SupportsIndex]]) -> pysparq._core.Rot_GeneralStatePrep
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.Rot_GeneralStatePrep, cond: str) -> pysparq._core.Rot_GeneralStatePrep
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.Rot_GeneralStatePrep, conds: collections.abc.Sequence[str]) -> pysparq._core.Rot_GeneralStatePrep
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.Rot_GeneralStatePrep, cond: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.Rot_GeneralStatePrep
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.Rot_GeneralStatePrep, conds: collections.abc.Sequence[typing.SupportsInt | typing.SupportsIndex]) -> pysparq._core.Rot_GeneralStatePrep
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.Rot_GeneralStatePrep, cond: str, pos: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.Rot_GeneralStatePrep
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.Rot_GeneralStatePrep, conds: collections.abc.Sequence[tuple[str, typing.SupportsInt | typing.SupportsIndex]]) -> pysparq._core.Rot_GeneralStatePrep
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.Rot_GeneralStatePrep, cond: typing.SupportsInt | typing.SupportsIndex, pos: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.Rot_GeneralStatePrep
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.Rot_GeneralStatePrep, conds: collections.abc.Sequence[tuple[typing.SupportsInt | typing.SupportsIndex, typing.SupportsInt | typing.SupportsIndex]]) -> pysparq._core.Rot_GeneralStatePrep
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: Prepares a register from the |0⟩ state into a target quantum state.
Parameters:
reg— target register (name or ID)state_vector— the target state vector (list of complex numbers or a NumPy array)
Dagger: Maps the target state back to |0⟩.
Mathematical representation: Given a target state \(|\psi\rangle = \sum_i \alpha_i |i\rangle\), construct a unitary \(U\) such that \(U|0\rangle = |\psi\rangle\).
Warning
This operator requires the register to currently be in the |0⟩ state. If the register already holds a nonzero value, the behavior is undefined.
import numpy as np
import pysparq as ps
ps.System.clear()
ps.System.add_register("q", ps.UnsignedInteger, 2)
state = ps.SparseState()
# Prepare a simplified Bell state: a uniform superposition
target = np.array([0.5, 0.5, 0.5, 0.5], dtype=complex)
op = ps.Rot_GeneralStatePrep("q", target)
op(state)
ps.pprint(state)
# |q=0⟩ : (0.5+0j)
# |q=1⟩ : (0.5+0j)
# |q=2⟩ : (0.5+0j)
# |q=3⟩ : (0.5+0j)
Helper Functions¶
stateprep_unitary_build_schmidt¶
- pysparq.stateprep_unitary_build_schmidt(state_vector: collections.abc.Sequence[SupportsComplex | SupportsFloat | SupportsIndex]) pysparq._core.DenseMatrix_complex¶
Build unitary for state preparation
Operation: Constructs the unitary matrix needed for state preparation using a Schmidt decomposition.
Purpose: Use it when you need to manually build or inspect the internal matrix of Rot_GeneralStatePrep.