workbench_algorithms.experimental.subroutines.mps_prep.mps_utils

Utility functions for MPS loading.

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.

ceillog

ceillog(s)

Ceiling log.

Parameters:

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

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

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

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.

reconstruct_state

reconstruct_state(Ms, d, n_sites)

Convert MPS tensors into state vector.

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

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