experimental

experimental

Subpackage for experimental WBA functions and Qubricks.

This directory is designed to allow for free-form experimentation and prototyping while keeping core development constrained to the WBA repo. The idea is that new interfaces, refactors or otherwise experimental Qubricks will be implemented here, to be imported as from psiqdk.algorithms.experimental import ... so that they can be used by other developers without them having to align disparate branches (that may have become stale).

NOTES FOR USERS: - The code contained within this directory should be considered unstable and subject to breaking changes. It should be used with appropriate caution. - Code implemented here may have less documentation than code implemented in the main package, and may also have more uncaught bugs. - Experimental Qubricks live as flat underscore-prefixed modules in this package and are re-exported from from psiqdk.algorithms.experimental import x.

NOTES FOR DEVELOPERS: - Experimental code will have a relaxed, but not totally eliminated, set of requirements to be merged. Specifically: - Code is still expected to be tested, but requirements won't be as robust as for the main branch (i.e. if the main functionality works on expected inputs, this should be sufficient) - Documentation requirements will be relaxed - docstrings and usage notebooks are still recommended to make usage clearer, but robust documentation will not be enforced. - Breaking changes can be made to experimental interfaces without requiring a major version bump, but devs should be conscious of the effects on users of doing so - if you're implementing a number of alternative APIs to choose from, consider using versioning as MyAPIV1, MyAPIV2 to minimise churn - Code merged into experimental should be considered as transient and short-lived. It should either be merged into the main repo once the API is stabilized or deleted if the feature is not needed. - MRs are still subject to review, but we should err a little more on the side of rapid development rather than robust checks.

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.	{}

qrom instance-attribute

qrom: Incomplete = qrom

usp instance-attribute

usp: Incomplete = usp

lambda_val instance-attribute

lambda_val: Incomplete = lambda_val

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 "Encoding Electronic Spectra in Quantum Circuits with Linear T Complexity" (arXiv:1805.03662 ⧉).

Parameters:

Name	Type	Description	Default
psi	Qubits	Register to prepare coefficients onto.	required
data	StatePrepDataInterface	A data storage interface that holds 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 keyword arguments to pass to the constructor.	{}

amplitude_prep instance-attribute

amplitude_prep: Incomplete = amplitude_prep

phase_prep instance-attribute

phase_prep: Incomplete = phase_prep

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

GrayCodeMultiplexedSingleQubitRotation

GrayCodeMultiplexedSingleQubitRotation(**kwargs)

Bases: Qubrick

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

Figure 2 in "Transformation of quantum states using uniformly controlled rotations" (arXiv:quant-ph/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

HouseholderMPSLoading

HouseholderMPSLoading(unitary_synth_qbk=None, **kwargs)

Bases: Qubrick

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

unitary_synth_qbk instance-attribute

unitary_synth_qbk: Incomplete = 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 qubits.	0

Note

Ref: see "Initial state preparation for quantum chemistry on quantum computers" (arXiv:2310.18410 ⧉).

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 "Initial state preparation for quantum chemistry on quantum computers" (arXiv:2310.18410 ⧉).
• 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.

merge_qroms instance-attribute

merge_qroms: Incomplete = merge_qroms

inverse_state_prep instance-attribute

inverse_state_prep: Incomplete = ArbitraryStatePrep(mux_rot, mux_rot_phase, dagger=True)

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.	required
ctrl	Qubits	Control qubits.	0

QROM

Bases: Protocol

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

compute

compute(index_reg: Qubits, bits_of_precision: int, data: Iterable[int], lambda_val: int | None = None, ctrl: Qubits | int = 0)

Compute the Qubrick.

Parameters:

Name	Type	Description	Default
index_reg	Qubits	Qubits encoding the indices to load the data from.	required
bits_of_precision	int	Encodes the accuracy of the data being loaded.	required
data	Iterable[int]	Contains the data to be loaded.	required
lambda_val	int | None	Space/time tradeoff parameter.	None
ctrl	Qubits | int	Qubits to control the operation.	0

AmplitudePreparation

Bases: Protocol

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

compute

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

Compute the Qubrick.

Parameters:

Name	Type	Description	Default
psi	Qubits	Qubits to prepare the state on.	required
data	StatePrepDataInterface	Classical parameters needed to specify the state.	required
ctrl	Qubits | int	Qubits to control the operation.	0

Antisymmetrization

Bases: Protocol

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

compute

compute(system_reg: Qubits, ctrl: Qubits | int = 0)

Compute the Qubrick.

Parameters:

Name	Type	Description	Default
system_reg	Qubits	Register to prepare antisymmetrized state on.	required
ctrl	Qubits | int	Control register for the routine. Defaults to 0.	0

BasisTransform

Bases: Protocol

Interface for Qubricks that compute Basis Transform.

compute

compute(target_reg: Qubits, catalyst_reg: Qubits, ctrl: Qubits | int = 0, final_qubits: Qubits | int = 0)

Computes Basis Transform.

Parameters:

Name	Type	Description	Default
target_reg	Qubits	The state to implement the rotations upon	required
catalyst_reg	Qubits	The catalyst state to use which is specific to the base angle being implemented	required
ctrl	Qubits | int	Classical or Quantum control conditions	0
final_qubits	Qubits | int	If passed in, these are the three qubits on which we just perform Z, S, and T directly instead of adding on to the catalyst state.	0

Notes

• The implemented circuit applies rotations of base_angle(2*i) for the i'th qubit of the target_reg where i runs from 0 to len(target_reg) - 1.

BinaryToUnaryUncomputation

Bases: Protocol

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

compute

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

Compute reversal of Binary to Unary conversion.

Parameters:

Name	Type	Description	Default
index_reg	Qubits	Input number state.	required
target_reg	Qubits	Register we apply the swap network to.	required
reg_size	int	Number of bits in each output register.	required
ctrl	Qubits | int	Qreg to control on. Defaults to None.	0

DotProduct

Bases: Protocol

Interface for Qubricks that compute dot products of vectors.

compute

compute(q_vec: list[Qubits] | Qubits)

Compute dot products of vectors.

Parameters:

Name	Type	Description	Default
q_vec	list[Qubits] | Qubits	List of Qubits each storing a component of the vector or one big Qubits object with each component (ex. x | y | z).	required

DysonSeriesSelect

Bases: Protocol

Interface for Qubricks that apply the Dyson series select operator.

compute

compute(register: CompositeRegister, data: DysonSeriesData, ctrl: Qubits | int = 0)

Apply the Dyson series select operator.

Parameters:

Name	Type	Description	Default
register	CompositeRegister	register (binary) for Dyson series indexing.	required
data	DysonSeriesData	Dataclass for the DysonSeries operator parameters.	required
ctrl	Qubits | int	A register to control this operation on. Default to None.	0

EncodingChange

Bases: Protocol

Interface for Qubricks that compute the encoding change.

compute

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

Compute the encoding change.

Takes a target_reg register and produces a new register (copy_reg) with 1's corresponding to the bit lengths of the values encoded in the register (loaded in superposition).

Parameters:

Name	Type	Description	Default
target_reg	Qubits	Register encoding the data to be multiplexed over.	required
ctrl	Qubits | int	Optional register to control on. Defaults to None.	0

FlagCollisions

Bases: Protocol

Interface for Qubricks that compute Flag Collision.

compute

compute(discret_reg: Qubits, trunc_reg: Qubits, ctrl: Qubits | int = 0)

Compute Flag Collision.

Parameters:

Name	Type	Description	Default
discret_reg	Qubits	registers to be compared (registers where time collisions may occure).	required
trunc_reg	Qubits	register indicating the value to compare up to.	required
ctrl	Qubits | int	a register to control this operation on. Default to None.	0

Note on convention

The resulting register, flag, stores 1 if at least one collision occured, 0 otherwise.

FlaggedQPEWindowFunction

Bases: Protocol

Interface for Qubricks that compute window function.

compute

compute(target_reg: Qubits, flag_reg: Qubits, ctrl: Qubits | int = 0, **kwargs)

Computes window function.

Parameters:

Name	Type	Description	Default
target_reg	Qubits	register on which the sine window state is prepared	required
flag_reg	Qubits	flag qubit when 0, the sine window state is prepared	required
ctrl	Qubits | int	control qubit	0
**kwargs	dict[str, Any]	other keyword arguments	{}

Note

• Needs a round of amplitude amplification.

GivensRotation

Bases: Protocol, Generic[T]

Interface for Qubricks that compute Givens Rotation.

compute

compute(rotation_encoding: T, target_reg: Qubits, ctrl: Qubits | int = 0) -> None

Computes Givens Rotation.

Parameters:

Name	Type	Description	Default
rotation_encoding	T	data type that encodes the rotation angle defining the PPR. This can be encoded in either a classical or a quantum datatype depending on the implementation, hence the protocol is generic in this argument.	required
target_reg	Qubits	the quantum register that we wish to rotate via the Givens rotation.	required
ctrl	Qubits | int	Qreg to control on. Defaults to None.	0

HammingWeight

Bases: Protocol

Interface for Qubricks that compute Hamming Weight.

compute

compute(target_register: Qubits, ctrl: Qubits | int = 0)

Compute the Hamming Weight.

Parameters:

Name	Type	Description	Default
target_register	Qubits	The target qubit register to compute the hamming weight of.	required
ctrl	Qubits | int	Quantum control conditions defaults to 0.	0

Note

• Allocates a quantum register storing the hamming weight

HammingWeightPhasing

Bases: Protocol

Interface for Qubricks that apply Hamming weight phasing.

compute

compute(target_register: Qubits, ctrl: Qubits | int = 0)

Implement a stack of rotations using Hamming weight phasing.

Parameters:

Name	Type	Description	Default
target_register	Qubits	The register on which to apply the rotations	required
ctrl	Qubits | int	The quantum control conditions.	0

InjectOp

Bases: Protocol

Interface for Qubricks that compute Inject circuit.

compute

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

Compute Inject circuit.

Parameters:

Name	Type	Description	Default
index_reg	Qubits	Input number state.	required
target_reg	Qubits	Register to apply operation to.	required
reg_size	int	Number of bits in each output register.	required
ctrl	Qubits | int	Qreg to control on. Defaults to 0.	0

MajoranaFermionOperator

Bases: Protocol

Interface for Qubricks that compute the Majorana Fermion Operator.

compute

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

Compute the Majorana Fermion Operator.

Parameters:

Name	Type	Description	Default
index_reg	Qubits	The qubit register that represents the indices to multiplex over.	required
target_reg	Qubits	The qubit register that the Majorana Fermion Operator gets applied onto.	required
ctrl	Qubits | int	Additional classical or quantum control conditions. Defaults to 0 which performs the operation as if a control qubit were in the |1> state.	0

MultiplexedRotationDataInterface

Interface for dataclasses being passed to multiplexed rotation Qubricks.

opcode instance-attribute

opcode: str

angles instance-attribute

angles: Iterable[float]

epsilon instance-attribute

epsilon: float

bits_of_precision class-attribute instance-attribute

bits_of_precision: int | None = None

MultiplexedRotations

Bases: Protocol

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

compute

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

Compute the Qubrick.

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

Multiplexor

Bases: Protocol

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

compute

compute(index_reg: Qubits, multiplex_function: Callable, used_indices: list[int] | None = None, ctrl: Qubits | int = 0)

Compute the Qubrick.

Parameters:

Name	Type	Description	Default
index_reg	Qubits	Encodes the indices we're multiplexing over.	required
multiplex_function	Callable	Defines the operation that performs the multiplexing.	required
used_indices	list[int] | None	Encodes whether we skip any indices.	None
ctrl	Qubits | int	Qubits to control the operation on.	0

Permutation

Bases: Protocol

Interface for Qubricks that apply permutation to register.

compute

compute(target_reg: Qubits, reg_size: int, register_permutation_function: Callable, ctrl: Qubits | int = 0)

Apply permutation to register.

Parameters:

Name	Type	Description	Default
target_reg	Qubits	Register we apply the permutation to. This register can conceptually be interpreted as a single large register, or as several registers of equal size. To facilitate this dual use, we currently allow passing a list of Qubits objects (though this is likely to be refactored).	required
reg_size	int	Number of bits in each target sub-register of target_reg.	required
register_permutation_function	Callable	Which quantum operation to use to effect the permutation of the target register.	required
ctrl	Qubits | int	Qreg to control on. Defaults to None.	0

Note

target_reg is given as a single register or as a list of multiple registers.

PhasePreparation

Bases: Protocol

Interface for Qubricks that apply phase corrections to prepared amplitudes.

compute

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

Compute the Qubrick.

Parameters:

Name	Type	Description	Default
psi	Qubits	Qubits to prepare the state on.	required
data	StatePrepDataInterface	Classical parameters needed to specify the state.	required
ctrl	Qubits | int	Qubits to control the operation.	0

PrepareWState

Bases: Protocol

Interface for Qubricks that Prepares a W state.

compute

compute(target: Qubits, ctrl: Qubits | int = 0)

Prepares a W state.

Parameters:

Name	Type	Description	Default
target	Qubits	Target qubits.	required
ctrl	Qubits | int	Control register. Default to None.	0

QPEWindowFunction

Bases: Protocol

Interface for Qubricks that compute QPE Window Function.

compute

compute(phase_reg: Qubits, ctrl: Qubits | int = 0, **kwargs)

Compute QPE Window Function.

Parameters:

Name	Type	Description	Default
phase_reg	Qubits	Phase qubit register	required
ctrl	Qubits | int	Control register	0
**kwargs	dict[str, Any]	Optional keyword arguments. Included to stay consistent with the arguments of window emulators.	{}

Select

Bases: Protocol

Interface for Qubricks that compute Select circuit.

compute

compute(index_reg: Qubits, target_reg: Qubits, data: PauliSum | list[int], ctrl: Qubits | int = 0)

Compute Select circuit.

Parameters:

Name	Type	Description	Default
index_reg	Qubits	Qubit register determining which op in data to apply.	required
target_reg	Qubits	System qubits.	required
data	PauliSum | list[int]	Hamiltonian terms expressed as a PauliSum to load in \(\text{SELECT}\) or a list of bitvalues to load.	required
ctrl	Qubits | int	Control for \(\text{SELECT}\). Defaults to 0.	0

Sort

Bases: Protocol

Interface for Qubricks that sort qubit register.

compute

compute(regs_list: list[Qubits], direction: int, ctrl: Qubits | int = 0)

Sort qubit registers.

Parameters:

Name	Type	Description	Default
regs_list	list[Qubits]	List of qubit registers to sort.	required
direction	int	Direction of the sort (0-ascending vs 1-descending).	required
ctrl	Qubits | int	Control qubit for the routine. Defaults to None.	0

Note

This assumes same size register for all registers in regs_list.

StatePreparation

Bases: Protocol

Interface for arbitrary state preparation Qubricks.

compute

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

Compute the Qubrick.

Parameters:

Name	Type	Description	Default
psi	Qubits	Qubits to prepare the state on.	required
data	StatePrepDataInterface	Classical parameters needed to specify the state.	required
ctrl	Qubits | int	Qubits to control the operation.	0

StatePrepDataInterface

Interface for dataclasses being passed to state preparation Qubricks.

coefficients instance-attribute

coefficients: Iterable[float | complex]

epsilon instance-attribute

epsilon: float

SuperpositionRotations

Bases: Protocol

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

compute

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

Compute the Qubrick.

Parameters:

Name	Type	Description	Default
angle_reg	Qubits	Qubits encoding the angles for the rotations.	required
target_reg	Qubits	Qubits to apply the multiplexed rotations on.	required
rot_data	MultiplexedRotationDataInterface	Classical parameters needed to specify the superposition rotations.	required
ctrl	Qubits | int	Qubits to control the operation.	0

SwapUpInterface

Bases: Protocol

Interface for Qubricks that compute the SwapUp circuit.

compute

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

Compute SwapUp circuit.

Parameters:

Name	Type	Description	Default
index_reg	Qubits	Input number state.	required
target_reg	Qubits	Register we apply the swap network to.	required
reg_size	int	Number of bits in each output register.	required
ctrl	Qubits | int	Qreg to control on. Defaults to None.	0

Trotterization

Bases: Protocol

Interface for Qubricks that execute the Suzuki-Trotter circuit.

compute

compute(system: Qubits, steps: int, evo_time: int, ctrl: Qubits | int = 0, trotter_order: int | None = None)

Execute the Suzuki-Trotter circuit.

Performs first and second order Trotterization directly. For higher orders, uses recursive calls to generate the appropriate product of operators.

Parameters:

Name	Type	Description	Default
system	Qubits	Qubits the Hamiltonian is acting on.	required
steps	int	The number of Trotter steps.	required
evo_time	int	The total evolution time.	required
ctrl	Qubits | int	Qubit register to control evolution on. Defaults to 0.	0
trotter_order	int | None	The order of Trotterization. If not set, uses the Qubrick attribute self.trotter_order set at instantiation.	None

UniformStatePreparation

Bases: Protocol

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

compute

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

Compute the Qubrick.

Parameters:

Name	Type	Description	Default
d	int	Dimension of the USP.	required
psi	Qubits	Register to prepare the uniform state onto.	required
ctrl	Qubits | int	Qubits to control the operation on.	0

VectorAdder

Bases: Protocol

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

compute

compute(q_vec1: list[Qubits], q_vec2: list[Qubits])

Compute circuit for computing the sum (or difference) of two vectors.

Parameters:

Name	Type	Description	Default
q_vec1	list[Qubits]	List of registers encoding vector components for one vector.	required
q_vec2	list[Qubits]	List of registers encoding vector components for the other vector.	required

Note

Two things: (i) The lengths of both vectors must be equal. (ii) Currently, WB cannot handle adding registers of different sizes correctly.

Currently, this method casts the results of addition to QInt objects in order to handle negative signs. This will be generalized.

HouseHolderUnitarySynthesisData dataclass

HouseHolderUnitarySynthesisData(isometry: list | 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

isometry instance-attribute

isometry: list | ndarray

bits_of_precision instance-attribute

bits_of_precision: int

physical_dim instance-attribute

physical_dim: int | None

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.

mps_tensors instance-attribute

mps_tensors: Iterable

bits_of_precision instance-attribute

bits_of_precision: int

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.

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 "Trading T gates for dirty qubits in state preparation and unitary synthesis" (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.	{}

qrom instance-attribute

qrom: Incomplete = qrom

rotation_qbk instance-attribute

rotation_qbk: Incomplete = rotation_qbk

lambda_val instance-attribute

lambda_val: Incomplete = lambda_val

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 "Transformation of quantum states using uniformly controlled rotations" (arXiv:quant-ph/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

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 keyword 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

opcode instance-attribute

opcode: str

angles instance-attribute

angles: Iterable[float]

epsilon instance-attribute

epsilon: float

bits_of_precision class-attribute instance-attribute

bits_of_precision: int | None = 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.

Based on the implementation published in "Quantum computing enhanced computational catalysis" (arXiv:2007.14460 ⧉) (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 keyword 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

opcode instance-attribute

opcode: str

coefficients instance-attribute

coefficients: Iterable[float]

epsilon instance-attribute

epsilon: float

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.

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.

compute

compute(qbits: Qubits, opcode: SupportedOps, ctrl: Qubits | int = 0)

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 "Compilation of Fault-Tolerant Quantum Heuristics for Combinatorial Optimization" (arXiv:2007.07391 ⧉). (See Appendix D.1.2 in "Trading T gates for dirty qubits in state preparation and unitary synthesis" (arXiv:1812.00954 ⧉) 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 keyword arguments to pass to the constructor.	{}

adder_qbk instance-attribute

adder_qbk: Incomplete = adder_qbk if adder_qbk is not None else PhaseGradientAdder()

basis_change_qbk instance-attribute

basis_change_qbk: Incomplete = PauliToPauliBasisTransform()

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 "Trading T gates for dirty qubits in state preparation and unitary synthesis" (arXiv:1812.00954 ⧉) 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 "Trading T gates for dirty qubits in state preparation and unitary synthesis" (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

is_positive_real

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

Checks whether the coefficients are all positive real.

ceillog

ceillog(s)

Ceiling log.

Parameters:

Name	Type	Description	Default
s	float	Value to take ceil log of.	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: 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: 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_0, A_1, ..., A_{n-1}]\), where each tensor has shape \((χ_{left}, d, χ_{right})\), into a list of two-dimensional arrays \([M_0, M_1, ..., M_{n-1}]\) suitable for subsequent right-to-left contractions or for a loader that expects this layout:

• \(M_0\) - column vector of shape \((d \cdot χ_1, 1)\) obtained by squeezing \(A_0\) and fusing its physical (size \(d\)) and right-bond indices.
• \(M_i\) - for each interior site \(1 \le i < n-1\), a matrix of shape \((d \cdot χ_{i+1}, χ_i)\) equal to \(A_i.reshape(χ_i, d \cdot χ_{i+1}).T\).
• \(M_{n-1}\) - the last tensor, first reshaped/transposed as above, \((d', χ_{last})\), and then expanded to \((d' \cdot χ_{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, χ_1), (χ_1, d, χ_2), ..., (χ_{n-1}, d, 1)]\).	required

Returns:

Type	Description
list[ndarray]	List \([M_0, ..., 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. 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