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

Rotation and state preparation operators overview

Operator

Operation

Unitarity class

Rot_GeneralUnitary

Apply an arbitrary-dimensional unitary matrix

BaseOperator

Rot_GeneralStatePrep

Prepare a target quantum state from |0⟩

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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