workbench_algorithms.experimental.subroutines

Top-level import for experimental subroutines in Workbench Algorithms.

QROM

Bases: Protocol

NOTE: Not final implementation, just to get things working for now.

AmplitudePreparation

Bases: Protocol

Interface for state preparation Qubricks that only prepare real, positive amplitudes.

Antisymmetrization

Bases: Protocol

NOTE: Not final implementation, just to get things working for now.

BasisTransform

Bases: Protocol

Interface for Qubricks that compute Basis Transform.

BinaryToUnaryUncomputation

Bases: Protocol

Interface for Qubricks that compute reversal of Binary to Unary conversion.

DotProduct

Bases: Protocol

Interface for Qubricks that compute dot products of vectors.

DysonSeriesSelect

Bases: Protocol

Interface for Qubricks that apply the Dyson series select operator.

EncodingChange

Bases: Protocol

Interface for Qubricks that compute the encoding change.

FlagCollisions

Bases: Protocol

Interface for Qubricks that compute Flag Collision.

FlaggedQPEWindowFunction

Bases: Protocol

Interface for Qubricks that compute window function.

GivensRotation

Bases: Protocol, Generic[T]

Interface for Qubricks that compute Givens Rotation.

HammingWeight

Bases: Protocol

Interface for Qubricks that compute Hamming Weight.

HammingWeightPhasing

Bases: Protocol

Interface for Qubricks that apply Hamming weight phasing.

InjectOp

Bases: Protocol

Interface for Qubricks that compute Inject circuit.

MajoranaFermionOperator

Bases: Protocol

Interface for Qubricks that compute the Majorana Fermion Operation.

MultiplexedRotationDataInterface

Interface for dataclasses being passed to multiplexed rotation Qubricks.

MultiplexedRotations

Bases: Protocol

Interface for Qubricks that handle multiplexing over a series of rotations.

Multiplexor

Bases: Protocol

NOTE: Not final implementation, just to get things working for now.

Permutation

Bases: Protocol

Interface for Qubricks that apply permutation to register.

PhasePreparation

Bases: Protocol

Interface for Qubricks that apply phase corrections to prepared amplitudes.

PrepareWState

Bases: Protocol

Interface for Qubricks that Prepares a W state.

QPEWindowFunction

Bases: Protocol

Interface for Qubricks that compute QPE Window Function.

Select

Bases: Protocol

Interface for Qubricks that compute Select circuit.

Sort

Bases: Protocol

Interface for Qubricks that sort qubit register.

StatePreparation

Bases: Protocol

Interface for arbitrary state preparation Qubricks.

StatePrepDataInterface

Interface for dataclasses being passed to state preparation Qubricks.

SuperpositionRotations

Bases: Protocol

Interface for Qubricks that apply a number of rotations in superposition simultaneously.

SwapUpInterface

Bases: Protocol

Interface for Qubricks that compute the SwapUp circuit.

Trotterization

Bases: Protocol

Interface for Qubricks that execute the Suzuki-Trotter circuit.

UniformStatePreparation

Bases: Protocol

NOTE: Not final implementation, just to get things working for now.

VectorAdder

Bases: Protocol

Interface for Qubricks that compute the sum (or difference) of two vectors.

HouseholderMPSLoading

HouseholderMPSLoading(unitary_synth_qbk=None, **kwargs)

Bases: Qubrick

Qubrick for loading the MPS on a quantum computer, based on HouseholderUnitarySynthesis.

compute

compute(prep_reg, data, ctrl: Qubits | int = 0)

Compute circuit for loading an MPS.

Parameters:

Name	Type	Description	Default
prep_reg	Qubits	Register where we are to prepare the desired state.	required
data	MPSPrepData	Dataclass encoding the specification of the MPS.	required
ctrl	Qubits	Control qubit.	0

Note

• Ref: see PRXQuantum.5.040339

HouseholderUnitarySynthesis

HouseholderUnitarySynthesis(
    inverse_state_prep=None,
    merge_qroms: bool = False,
    **kwargs,
)

Bases: Qubrick

Qubrick synthesizing an isometry using the Householder-based decomposition.

Parameters:

Name	Type	Description	Default
inverse_state_prep	Qubrick	state preperation protocol to utilise.	None
merge_qroms	Bool	choice to utilise QROM merging between two consecutive column loading on same physical site	False
**kwargs	dict[str, Any]	Other arguments to pass to the init.	{}

Note

• Ref: see PRXQuantum.5.040339
• Currently the QRE is inaccurate due to compute of the daggered LKS state prep acting oddly.
• QROM merging will only be accurate for sufficient b_of_p in rotation angles.

compute

compute(
    virtual_reg, physical_reg, data, ctrl: Qubits | int = 0
)

Compute function for the Householder-based synthesis of a given isometry matrix isometry.

Parameters:

Name	Type	Description	Default
virtual_reg	Qubits	Virtual reg used in synthesis. Must have dimension at least isometry.shape[1].	required
physical_reg	Qubits	Physical reg used in synthesis.	required
data	HouseHolderUnitarySynthesisData	Dataclass containing unitary synthesis info, including: - isometry ([list, numpy]): The isometry matrix to be synthesized. - bits_of_precision (int): The bit-precision used in the state preparation subroutines. - physical_dimension (None, int): If None, the physical register dimension will be used. Must be specified if used in the context of an MPS with non-power of two physical dimension.	required
ctrl	Qubits	Control qubit.	0

HouseHolderUnitarySynthesisData dataclass

HouseHolderUnitarySynthesisData(
    isometry: [list, np.ndarray],
    bits_of_precision: int,
    physical_dim: [int, None],
)

Data for specifying a Householder unitary synthesis.

Only meant to be a container for a couple of attributes for the sake of simplifying the compute signature of the HouseHolderUnitarySynthesis Qubrick.

Parameters:

Name	Type	Description	Default
isometry	[list, numpy]	The isometry matrix to be synthesized.	required
bits_of_precision	int	the number of precision bits to use in synthesizing each column of unitary matrix (per site)	required
physical_dim	(None, int)	If None, the physical register dimension will be used. Must be specified if used in the context of an MPS with non-power of two physical dimension.	required

MPSPrepData dataclass

MPSPrepData(mps_tensors: Iterable, bits_of_precision: int)

Data for specifying a matrix product state.

Parameters:

Name	Type	Description	Default
mps_tensors	Iterable	MPS tensors from DMRG calculations	required
bits_of_precision	int	the number of precision bits to use in synthesizing each column of unitary matrix (per site)	required

Note

• Input MPS tensors need to be reshaped to be fed into a loading circuit

n_sites property

n_sites: int

Returns number of sites.

physical_dim property

physical_dim: int

Returns physical leg dimension of each site.

maximum_bond_dim property

maximum_bond_dim: int

Returns maximum bond dimension.

GrayCodeMultiplexedSingleQubitRotation

GrayCodeMultiplexedSingleQubitRotation(**kwargs)

Bases: Qubrick

Decomposition of uniformly controlled rotations to single qubit rotation + CNOTs.

Figure 2 in arXiv:0407010.

compute

compute(
    index_reg: Qubits,
    target_reg: Qubits,
    rot_data: MultiplexedRotationDataInterface,
    ctrl: Qubits | int = 0,
)

Compute the multiplexed rotation.

Parameters:

Name	Type	Description	Default
index_reg	Qubits	Index qubits.	required
target_reg	Qubits	Target qubit.	required
rot_data	MultiplexedRotationDataInterface	Encodes the data needed to implement the uniformly controlled rotations.	required
ctrl	Qubits | int	Register to control on. Defaults to 0.	0

MultiplexedSingleQubitRotationViaQROM

MultiplexedSingleQubitRotationViaQROM(
    qrom: QROM,
    rotation_qbk: SuperpositionRotations,
    controlled_on: bool | None = None,
    lambda_val: int | None = None,
    **kwargs,
)

Bases: Qubrick

Multiplexor using data-lookup oracles.

Detailed in arXiv:1812.00954 (circuit described in Appendix D).

This technique for multiplexed rotations works by first loading a truncated, integerized, b-bit approximation of rotation angles onto an ancillary register and then performing the rotations coherently in superposition controlled on this register.

Parameters:

Name	Type	Description	Default
qrom	QROM	Data-loader for loading angles to b_of_p-bits of precision.	required
rotation_qbk	SuperpositionRotations	Qubrick to implement the actual rotations (e.g. via phase gradient addition).	required
controlled_on	bool | None	whether the prep circuit is controlled on, default to None.	None
lambda_val	int | None	the SEL-SWAP tunable parameter, default to None and optimized Toffoli version is used.	None
**kwargs	dict[str, Any]	Other arguments to pass to the init.	{}

controlled_on property

controlled_on: Qubrick

Flag to determine which component to control the Qubrick on, QROM or the rotations.

compute

compute(
    index_reg: Qubits,
    target_reg: Qubits,
    rot_data: MultiplexedRotationDataInterface,
    ctrl: Qubits | int = 0,
)

Compute circuit for Data-lookup multiplexor.

Parameters:

Name	Type	Description	Default
index_reg	Qubits	Index register.	required
target_reg	Qubits	Register to apply rotations onto.	required
rot_data	MultiplexedRotationDataInterface	Dataclass that containerizes the classical input data needed for the multiplexed rotations.	required
ctrl	Qubits | int	Control register.	0

NaiveMultiplexedSingleQubitRotation

NaiveMultiplexedSingleQubitRotation(
    multiplexor: Multiplexor = None, **kwargs
)

Bases: Qubrick

Controlled rotations from arXiv:0407010.

Parameters:

Name	Type	Description	Default
multiplexor	Multiplexor	Qubrick for implementing the multiplexing over the rotations.	None
**kwargs	dict[str, Any]	Other arguments to pass to the init.	{}

multiplexor property

multiplexor

Getter for the multiplexor.

compute

compute(
    index_reg: Qubits,
    target_reg: Qubits,
    rot_data: MultiplexedRotationDataInterface,
    ctrl: Qubits | int = 0,
)

Compute the multiplexed rotation.

Parameters:

Name	Type	Description	Default
index_reg	Qubits	Index qubits.	required
target_reg	Qubits	Target qubits.	required
rot_data	MultiplexedRotationDataInterface	Dataclass that containerizes the classical input data needed for the multiplexed rotations.	required
ctrl	Qubits | int	Register to control on.	0

PauliToPauliBasisTransform

PauliToPauliBasisTransform(**kwargs)

Bases: Qubrick

Transforms quantum operations between different Pauli bases (X, Y, Z).

Used to simplify or standardize quantum computations.

y_to_z

y_to_z(qbits: Qubits, ctrl: Qubits | int = 0)

Convert y to z.

x_to_z

x_to_z(qbits: Qubits, ctrl: Qubits | int = 0)

Convert x to z.

pauli_product_to_z

pauli_product_to_z(
    x_qbits: Qubits, z_qbits: Qubits, ctrl: Qubits | int = 0
)

Convert PPO to z.

z_to_y

z_to_y(qbits: Qubits, ctrl: Qubits | int = 0)

Convert z to y.

z_to_x

z_to_x(qbits: Qubits, ctrl: Qubits | int = 0)

Convert z to x.

z_to_pauli_product

z_to_pauli_product(
    x_qbits: Qubits, z_qbits: Qubits, ctrl: Qubits | int = 0
)

Convert z to PPO.

RotationViaPhaseGradientAddition

RotationViaPhaseGradientAddition(
    adder_qbk: Adder | None = None, **kwargs
)

Bases: Qubrick

Coherently-applies WB qc.phase rotations via phase gradient addition.

This method originated from Appendix A in arxiv:2007.07391 (See Appendix D.1.2 in this paper for how this is used to form a multiplexor)

The PGA circuit is defined with respect to phase rotations; as such, implementing any other-axis rotation in a coherent superposition typically requires rotating to the Z basis, in-place adding with a phase gradient, and then rotating back to the original basis.

This Qubrick is a stand-in for that base-case of phase gate.

Parameters:

Name	Type	Description	Default
adder_qbk	Adder | None	Qubrick for implementing the addition in the phase gradient addition.	None
kwargs	dict[str, Any]	Other key word arguments to pass to the constructor.	{}

compute

compute(
    angle_reg: Qubits,
    target_reg: Qubits,
    rot_data: MultiplexedRotationDataInterface,
    ctrl: Qubits | int = 0,
)

Compute circuit for rotations via phase gradient addition.

Parameters:

Name	Type	Description	Default
angle_reg	Qubits	Register where rotation angles have been written.	required
target_reg	Qubits	Single qubit where rotations are applied.	required
rot_data	MultiplexedRotationDataInterface	discretized rotation angles data for the multiplexor	required
ctrl	Qubits | int	Control register.	0

RotationViaSingleQubitUnitaries

RotationViaSingleQubitUnitaries(**kwargs)

Bases: Qubrick

Compute circuit for rotations via controlled single-qubit rotations.

See Appendix D.1.1 in this paper for how this is used to form a multiplexor.

Note

Here we note some conventions used in the literature and its correspondence in this Qubrick:

• In arXiv:1812.00954, a multiplexed Y rotation is written as \(\text{RY}(\theta_x) = e^{i2\pi \theta_x Y}\), with \(\theta_x\) in radians.
• With an explicit factor of \(2\pi\) in the exponent, this implies the angles range from zero to one.
• Workbench does not include this factor of \(2\pi\) in its definition of Pauli rotations, so it must be accounted for.
• Additionally, the default units in Workbench are degrees, and thus, this is why the angle args below have a factor of 360 in the numerator.
• This routine makes use of an integer approximation of \(\theta_x\) by truncating its binary expansion to \(b\) bits.
• For these reasons, the integer angle approximations written to a register in this routine take values from zero to \(2^b - 1\).

compute

compute(
    angle_reg: Qubits,
    target_reg: Qubits,
    rot_data: MultiplexedRotationDataInterface,
    ctrl: Qubits | int = 0,
)

Compute circuit for rotations via controlled single qubit rotations.

Parameters:

Name	Type	Description	Default
angle_reg	Qubits	Register where rotation angles have been written.	required
target_reg	Qubits	Single qubit where rotations are applied.	required
rot_data	MultiplexedRotationDataInterface	discretized rotation angles data for the multiplexor	required
ctrl	Qubits | int	Control register.	0

AliasSampling

AliasSampling(
    qrom: QROM,
    usp: UniformStatePreparation,
    lambda_val=None,
    **kwargs,
)

Bases: Qubrick

Qubrick for implementing alias sampling.

Parameters:

Name	Type	Description	Default
qrom	QROM	Data lookup instance.	required
usp	UniformStatePreparation	Uniform state preparation instance.	required
lambda_val	int	SEL-SWAP tunable parameter for QROM, default to None where optimal lambda (based on Toffoli counts) is calculated	None
**kwargs	dict[str, Any]	Other arguments to pass to the init.	{}

compute

compute(
    psi: Qubits,
    data: StatePrepDataInterface,
    ctrl: Qubits | int = 0,
    *,
    usp_rotator: Qubits | None = None,
    coin_toss_reg: Qubits | None = None,
)

State preparation by alias sampling.

Note

Uses the circuit in Fig. 11 of arXiv:1805.03662 <https://arxiv.org/abs/1805.03662>_.

Parameters:

Name	Type	Description	Default
psi	Qubits	Register to prepare coefficients onto.	required
data	StatePrepDataInterface	a data storage interface that hold all the classical precomputation numbers	required
ctrl	Qubits | int	Control register.	0
usp_rotator	Qubits | None	Qubit to rotate as part of USP. Needs to be supplied if this Qubrick is used with a coherent uncomputation (such as in LCU), but will be allocated on the fly if not supplied.	None
coin_toss_reg	Qubits | None	Qubits register used to load the coin toss state (uniform state) in for the alias sampling protocol. Needs to be supplied if this Qubrick is used with a coherent uncomputation (such as in LCU), but will be allocated on the fly if not supplied.	None

ArbitraryStatePrep

ArbitraryStatePrep(
    amplitude_prep: AmplitudePreparation,
    phase_prep: PhasePreparation | None = None,
    **kwargs,
)

Bases: Qubrick

Qubrick for preparing states with arbitrary coefficients.

The strategy used is straightforward: first we prepare the amplitudes for the state such that the probabilities for each basis state are correct, then we prepare the phases to get the full state.

Parameters:

Name	Type	Description	Default
amplitude_prep	AmplitudePreparation	Qubrick to prepare the amplitudes for the state.	required
phase_prep	PhasePreparation | None	Qubrick to prepare the phases given the amplitudes have already been prepared.	None
kwargs	dict[str, Any]	Other key word arguments to pass to the constructor.	{}

compute

compute(
    psi: Qubits,
    data: StatePrepDataInterface,
    ctrl: Qubits | int = 0,
)

Compute the arbitrary state prep.

Note

This Qubrick makes no assumptions about how the amplitudes and phases are prepared and so all data processing is delegated to those Qubricks.

Parameters:

Name	Type	Description	Default
psi	Qubits	Register to prepare the state on.	required
data	StatePrepDataInterface	Dataclass encoding the specification of the state.	required
ctrl	Qubits | int	Register to control the state preparation.	0

FlattenedRotArray

FlattenedRotArray(mplxr: MultiplexedRotations, **kwargs)

Bases: Qubrick

Implements a state sub-preparation using a single set of multiplexed rotations.

Note

• This only works with PHASE ops, so can only be used for a phase fixup, and can't be used with the Gray code multiplexor, which relies on the structure of RZ gates to work.
• There is no global phase correction to do with this Qubrick.

Parameters:

Name	Type	Description	Default
mplxr	MultiplexedRotations	The Qubrick that will implement the individual multiplexed rotations	required
kwargs	dict[str, Any]	Other key word arguments to pass to the constructor.	{}

mplxr property

mplxr: MultiplexedRotations

Getter for the multiplexor Qubrick.

compute

compute(
    psi: Qubits,
    data: StatePrepDataInterface,
    ctrl: Qubits | int = 0,
)

Compute the multiplexor.

Parameters:

Name	Type	Description	Default
psi	Qubits	The qubits to apply the rotations onto.	required
data	StatePrepDataInterface	A dataclass encoding the rotation data	required
ctrl	Qubits | int	Qubits to control the operation on.	0

MultiplexedRotationData dataclass

MultiplexedRotationData(
    opcode: str,
    angles: Iterable[float],
    epsilon: float,
    bits_of_precision: int | None = None,
)

Data class for handling data for multiplexed rotations.

Parameters:

Name	Type	Description	Default
opcode	str	Encodes the type of rotation op to be applied, one of SupportedOps.	required
angles	Iterable[float]	The list of rotation angles to be applied.	required
epsilon	float	The accuracy that the multiplexed rotations are to be applied to.	required
bits_of_precision	int | None	For QROM-based multiplexors, the number of bits of precision to be used in the rotations.	None

ProgrammableRotArray

ProgrammableRotArray(
    op,
    mplxr: MultiplexedRotations,
    fix_global_phase: bool = False,
    **kwargs,
)

Bases: Qubrick

Implements a state sub-preparation using a cascade of uniformly controlled rotations.

Essentially, it is a data storage "terminology" coined by this microsoft paper (see appendix VII, section B, subsection 1) where we need a 2D array of angles (each row of size 1, 2, 4, 8, ...), similar to the multiplexed Givens rotation.

Parameters:

Name	Type	Description	Default
op	SupportedOps	Encodes the type of rotation op to be applied, one of SupportedOps.	required
mplxr	MultiplexedRotations	The Qubrick that will implement the individual multiplexed rotations	required
fix_global_phase	bool	Whether to fix up the global phase (for statevector validation) or prepare the state up to global phase. This correction is always applied when the Qubrick is controlled.	False
kwargs	dict[str, Any]	Other key word arguments to pass to the constructor.	{}

op property

op: SupportedOps

Getter for the op in the programmable rot array.

mplxr property

mplxr: MultiplexedRotations

Getter for the multiplexor qubrick.

fix_global_phase property

fix_global_phase: bool

Getter for the fix global phase attribute.

compute

compute(
    psi: Qubits,
    data: StatePrepDataInterface,
    ctrl: Qubits | int = 0,
)

Compute the rotation array.

ProgrammableRotArrayData dataclass

ProgrammableRotArrayData(
    opcode: str,
    coefficients: Iterable[float],
    epsilon: float,
    _bits_of_precision: int | None = None,
)

Data class for handling data for multiplexed rotations.

Parameters:

Name	Type	Description	Default
opcode	str	Encodes the type of rotation op to be applied, one of SupportedOps.	required
coefficients	Iterable[float]	The coefficients of the state to be loaded.	required
epsilon	float	The accuracy that the multiplexed rotations are to be applied to.	required
_bits_of_precision	int | None	Override the default bits of precision argument with a custom value. NOTE: this may result in loss of fidelity if the value is not chosen carefully - users are recommended to leave this unset unless they know what they are doing.	None

angles cached property

angles: list[float]

Get the angles corresponding to the particular set of rotations to be applied.

bits_of_precision cached property

bits_of_precision: int

Get the number of bits of precision for QROM-based multiplexors.

ceillog

ceillog(s)

Ceiling log.

Parameters:

Name	Type	Description	Default
s	float	value to which to take ceil log	required

find_physical_locations

find_physical_locations(mps)

Find basis state indices corresponding to the physical registers.

Parameters:

Name	Type	Description	Default
mps	list	List of MPS tensors	required

get_random_mps

get_random_mps(
    d: int,
    n: int,
    maxbond: int,
    is_complex: bool,
    random_number_generator: np.random.Generator
    | None = None,
)

Get random MPS.

Parameters:

Name	Type	Description	Default
d	int	Physical dimension	required
n	int	Number of sites	required
maxbond	int	Max bond dimension	required
is_complex	bool	If True, returns MPS tensors with complex values	required
random_number_generator	Generator | None	Generator for the random numbers used in the mps. If not passed, a new generator will be instantiated using the default numpy seed.	None

get_random_tensor

get_random_tensor(
    shape: tuple,
    is_complex: bool,
    random_number_generator: np.random.Generator
    | None = None,
)

Get random MPS tensor.

Parameters:

Name	Type	Description	Default
shape	tuple	Shape of tensor	required
is_complex	bool	If True, elements of tensors are complex	required
random_number_generator	Generator | None	Generator for the random numbers used in the mps. If not passed, a new generator will be instantiated using the default numpy seed.	None

make_left_canonical

make_left_canonical(mps)

Make MPS tensors into left canonical form.

Parameters:

Name	Type	Description	Default
mps	array	Input MPS tensors	required

reconstruct_state

reconstruct_state(Ms, d, n_sites)

Convert MPS tensors into state vector.

reshape_last_tensor

reshape_last_tensor(mps)

Fuse the physical-bond indices of every MPS tensor into 2-D matrices and pad the final site.

The routine converts a left-canonical matrix-product state mps = [A₀, A₁, …, A_{n−1}] where each tensor has shape (χ_left, d, χ_right) into a list of two-dimensional arrays [M₀, M₁, …, M_{n−1}] suitable for subsequent right-to-left contractions or for a loader that expects this layout:

• M₀ – column vector of shape (d·χ₁, 1) obtained by squeezing A₀ and fusing its physical (size d) and right-bond indices.
• Mᵢ – for each interior site 1 ≤ i < n−1, a matrix of shape (d·χ_{i+1}, χᵢ) equal to Aᵢ.reshape(χᵢ, d·χ_{i+1}).T.
• M_{n−1} – the last tensor, first reshaped/transposed as above ((d′, χ_last)) and then expanded to (d′·χ_last, χ_last) by inserting χ_last − 1 rows of zeros between successive physical rows. This zero-padding ensures that each physical basis block starts at an address that is an integer multiple of the virtual bond dimension, which is required by downstream loading routines.

Parameters:

Name	Type	Description	Default
mps	list[ndarray]	List of n left-canonical MPS tensors with shapes [(1, d, χ₁), (χ₁, d, χ₂), …, (χ_{n-1}, d, 1)].	required

Returns:

Type	Description
list[ndarray]	List [M₀, …, M_{n−1}] where every element is a 2-D NumPy array as described above.

Notes

The transformation leaves the (virtual) bond dimensions unchanged and does not alter the represented many-body quantum state; it merely repackages the tensors to match the memory layout expected by other utilities in this module, e.g. :pyfunc:reconstruct_state.

split

split(M, d, bond_dim)

Split a matrix M via SVD and keep only the bond_dim largest entries.

Parameters:

Name	Type	Description	Default
M	array	Input array	required
d	int	Physical dimension	required
bond_dim	int	Bond dimension	required

splitleft

splitleft(M, d, bond_dim)

Split a matrix M via SVD and keep only the bond_dim largest entries.

Parameters:

Name	Type	Description	Default
M	array	Input array	required
d	int	Physical dimension	required
bond_dim	int	Bond dimension	required

is_positive_real

is_positive_real(coeffs: Iterable[float | complex]) -> bool

Checks whether the coeffs are all positive real.