Python emulator

Python backend

We report here the python backend, with all the available functions, coming from the package qtealeaves

class qtealeaves.emulator.mps_simulator.MPS(num_sites, convergence_parameters, local_dim=2, initialize='vacuum', requires_singvals=False, tensor_backend=None, sectors=None, **kwargs)[source]

Matrix product states class

Parameters

num_sites: int: Number of sites
convergence_parameters: TNConvergenceParameters: Class for handling convergence parameters. In particular, in the MPS simulator we are interested in: - the maximum bond dimension \(\chi\); - the cut ratio \(\epsilon\) after which the singular

values are neglected, i.e. if \(\lamda_1\) is the bigger singular values then after an SVD we neglect all the singular values such that \(\frac{\lambda_i}{\lambda_1}\leq\epsilon\)
local_dim: int or list of ints, optional: Local dimension of the degrees of freedom. Default to 2. If a list is given, then it must have length num_sites.
initialize: str, optional: The method for the initialization. Default to “vacuum” Available: - “vacuum”, for the |000…0> state (no symmetric tensors yet) - “random”, for a random state at given bond dimension
requires_singvalsboolean, optional: Allows to enforce SVD to have singular values on each link available which might be useful for measurements, e.g., bond entropy (the alternative is traversing the whole TN again to get the bond entropy on each link with an SVD).
tensor_backendNone or instance of TensorBackend: Default for None is QteaTensor with np.complex128 on CPU.
sectorsdict | None, optional: Can restrict symmetry sector and/or bond dimension in initialization. If empty, no restriction. The global symmetry sector is parsed from the the key global; intermediate sectors can be restricted via integer keys specifying the number of sites to the left of the corresponding link. Example: Restrict irreps after the second site at python-index=1, the key equals to 2 for two sites being on the left of the link. Default to None resulting in empty dictionary.

add_site(idx, state=None)[source]

Add a site in a product state in the link idx (idx=0 is before the first site, idx=N+1 is after the last). The state of the new index is |0> or the one provided.

Parameters

idxint: index of the link where you want to add the site
state: _AbstractQteaTensor | np.ndarray | None: Vector state that you want to add

Details

To insert a new site in the MPS we first insert an identity on a link, then add a dimension-1 link to the identity and lastly contract the new link with the initial state, usually a |0>

apply_local_kraus_channel(kraus_ops)[source]

Apply local Kraus channels to tensor network. Does not work for MPS!

Parameters

kraus_opsdict of QTeaTensor: Dictionary, keys are site indices and elements the corresponding 3-leg kraus tensors

Returns

singvals_cut: float: Sum of singular values discarded due to truncation.

apply_mpo(mpo)[source]

Apply an MPO to the MPS on the sites sites. The MPO should have the following convention for the links: 0 is left link. 1 is physical link pointing downwards. 2 is phisical link pointing upwards. 3 is right link.

The sites are encoded inside the DenseMPO class.

Parameters

mpoDenseMPO: MPO to be applied

Returns

np.ndarray: Singular values cutted when the gate link is contracted

apply_nonlocal_two_site_operator(op, control, target, swap=False)[source]

Apply a non-local two-site operator, by taking first the SVD of the operator, contracting the almost-single-site operator to the respective sites and then propagating the operator to the correct site

Warning

The operations in this method are NOT ALWAYS well defined. If the left-operator tensor is not unitary, then we are applying a non-unitary operation to the state, and thus we will see a vanishing norm. Notice that, if the error can happen a warning message will be issued

Parameters

opnp.ndarray: Operator to be applied
controlint: control qubit index
targetint: target qubit index
swapbool, optional: If True, transpose the tensor legs such that the control and target are swapped. Default to False

Returns

np.ndarray: Singular values cutted when the gate link is contracted

apply_one_site_operator(op, pos)[source]

Applies a one operator op to the site pos of the MPS.

Parameters

op: QteaTensor of shape (local_dim, local_dim): Matrix representation of the quantum gate
pos: int: Position of the qubit where to apply op.

apply_projective_operator(site, selected_output=None, remove=False)[source]

Apply a projective operator to the site site, and give the measurement as output. You can also decide to select a given output for the measurement, if the probability is non-zero. Finally, you have the possibility of removing the site after the measurement.

Warning

Applying projective measurements/removing sites is ALWAYS dangerous. The information of the projective measurement should be in principle carried over the entire mps, by iteratively applying SVDs across all sites. However, this procedure is highly suboptimal, since it is not always necessary and will be processed by the following two-sites operators. Thus, the procedure IS NOT applied here. Take care that entanglement measures through TNObsBondEntropy may give incorrect results right after a projective operator application. Furthermore, if working with parallel approaches, projective operators should be treated with even more caution, since they CANNOT be applied in parallel.

Parameters

site: int: Index of the site you want to measure
selected_output: int, optional: If provided, the selected state is measured. Throw an error if the probability of the state is 0
remove: bool, optional: If True, the measured index is traced away after the measurement. Default to False.

Returns

meas_state: int: Measured state
state_probfloat: Probability of measuring the output state

apply_two_site_operator(op, pos, swap=False, svd=True, parallel=False)[source]

Applies a two-site operator op to the site pos, pos+1 of the MPS.

Parameters

op: QteaTensor (local_dim, local_dim, local_dim, local_dim): Matrix representation of the quantum gate
pos: int or list of ints: Position of the qubit where to apply op. If a list is passed, the two sites should be adjacent. The first index is assumed to be the control, and the second the target. The swap argument is overwritten if a list is passed.
swap: bool: If True swaps the operator. This means that instead of the first contraction in the following we get the second. It is written is a list of pos is passed.
svd: bool: If True, apply the usual contraction plus an SVD, otherwise use the QR approach explained in https://arxiv.org/pdf/2212.09782.pdf.
parallel: bool: If True, perform an approximation of the two-qubit gates faking the isometry center

Returns

singular_values_cutted: ndarray: Array of singular values cutted, normalized to the biggest singular value

Examples

swap=False  swap=True
  -P-M-       -P-M-
  2| |2       2| |2
  3| |4       4| |3
   GGG         GGG
  1| |2       2| |1

build_effective_operators(measurement_mode=False)[source]

Build the complete effective operator on each of the links. It assumes self.eff_op is set. Also builds effective projectors, self.eff_proj.

Parameters

measurement_modebool, optional: If True, enable measurement mode of effective operators

contract(other, boundaries=None)[source]

Contract the MPS with another MPS other <other|self>. By default it is a full contraction, but also a partial contraction is possible

Parameters

otherMPS: other MPS to contract with
boundariestuple of two ints, optional: Contract to MPSs from boundaries[0] to boundaries[1]. In this case the output will be a tensor of shape (chi_self, chi_other, 1) or (1, chi_self, chi_other). Default to None, which is full contraction

Returns

contractioncomplex | _AbstractQteaTensor: Result of the contraction

property current_max_bond_dim: Maximum bond dimension of the mps

property default_iso_pos: Returns default isometry center position, e.g., for initialization of effective operators.

default_sweep_order(skip_exact_rgtensors=False)[source]

Default sweep order to be used in the ground state search/time evolution. Default for MPS is left-to-right.

Arguments

skip_exact_rgtensorsbool, optional: Allows to exclude tensors from the sweep which are at full bond dimension and represent just a unitary transformation. Usually set via the convergence parameters and then passed here. Default to False.

Returns

List[int]: The generator that you can sweep through

deprecated_get_eff_op_on_pos(pos)[source]

Obtain the list of effective operators adjacent to the position pos and the index where they should be contracted

Parameters

poslist: list of [layer, tensor in layer]

Returns

list of IndexedOperators: List of effective operators
list of ints: Indexes where the operators should be contracted

dot(other)[source]

Calculate the dot-product or overlap between two MPSs, i.e., <self | other>.

Parameters

otherMPS: Measure the overlap with this other MPS.

Returns

Scalar representing the overlap.

property first_non_orthogonal_left: First non orthogonal tensor starting from the left

property first_non_orthogonal_right: First non orthogonal tensor starting from the right

flipped()[source]

Flip an MPS completely left-right.

Returns

psiMPS: Wave function with the reverse order of sites with respect to self.

classmethod from_density_matrix(rho, n_sites, dim, conv_params, tensor_backend=None, prob=False)[source]: Converts density matrix to MPS (not implemented yet).

classmethod from_lptn(lptn, conv_params=None, **kwargs)[source]

Converts LPTN to MPS.

Parameters

lptn: LPTN: object to convert to MPS.
conv_params: TNConvergenceParameters, optional: Input for handling convergence parameters. If None, the algorithm will try to extract conv_params from lptn.convergence_parameters. Default is None.
kwargsadditional keyword arguments: They are accepted, but not passed to calls in this function.

Return

mps: MPS: Decomposition of lptn.

classmethod from_mps(mps, conv_params=None, **kwargs)[source]

Converts MPS to MPS.

Parameters

mps: MPS: object to convert to MPS.
conv_params: TNConvergenceParameters, optional: Input for handling convergence parameters Default is None.
kwargsadditional keyword arguments: They are accepted, but not passed to calls in this function.

Return

new_mps: MPS: Decomposition of mps, here a copy.

classmethod from_statevector(statevector, local_dim=2, conv_params=None, tensor_backend=None)[source]

Initialize the MPS tensors by decomposing a statevector into MPS form. All the degrees of freedom must have the same local dimension

Parameters

statevectorndarray of shape( local_dim^num_sites, ): Statevector describing the interested state for initializing the MPS
local_dimint, optional: Local dimension of the degrees of freedom. Default to 2.
conv_paramsTNConvergenceParameters, optional: Convergence parameters for the new MPS. If None, the maximum bond bond dimension possible is assumed, and a cut_ratio=1e-9. Default to None.
tensor_backendNone or instance of TensorBackend: Default for None is QteaTensor with np.complex128 on CPU.

Returns

objMPS: MPS simulator class

Examples

>>> -U1 - U2 - U3 - ... - UN-
>>>  |    |    |          |
# For d=2, N=7 and chi=5, the tensor network is as follows:
>>> -U1 -2- U2 -4- U3 -5- U4 -5- U5 -4- U6 -2- U7-
>>>  |      |      |      |      |      |      |
# where -x- denotes the bounds' dimension (all the "bottom-facing" indices
# are of dimension d=2). Thus, the shapes
# of the returned tensors are as follows:
>>>      U1         U2         U3         U4         U5         U6         U7
>>> [(1, 2, 2), (2, 2, 4), (4, 2, 5), (5, 2, 5), (5, 2, 4), (4, 2, 2), (2, 2, 1)]

classmethod from_tensor_list(tensor_list, conv_params=None, tensor_backend=None, target_device=None)[source]

Initialize the MPS tensors using a list of correctly shaped tensors

Parameters

tensor_listlist of ndarrays or cupy arrays or _AbstractQteaTensors: List of tensor for initializing the MPS
conv_paramsTNConvergenceParameters, optional: Convergence parameters for the new MPS. If None, the maximum bond bond dimension possible is assumed, and a cut_ratio=1e-9. Default to None.
tensor_backendNone or instance of TensorBackend: Default for None is QteaTensor with np.complex128 on CPU.
target_device: None | str, optional: If None, take memory device of tensor backend. If string is any, do not convert. Otherwise, use string as device string.

Returns

objMPS: The MPS class

classmethod from_ttn(ttn, conv_params=None, **kwargs)[source]

Converts TTN to MPS.

Parameters

ttn: TTN: object to convert to MPS.
conv_params: TNConvergenceParameters, optional: Input for handling convergence parameters. If None, the algorithm will try to extract conv_params from ttn.convergence_parameters. Default is None.
kwargsadditional keyword arguments: They are accepted, but not passed to calls in this function.

Return

mps: MPS: Decomposition of ttn.

classmethod from_tto(tto, conv_params=None, **kwargs)[source]

Converts TTO to MPS.

Parameters

tto: TTO: Object to convert to MPS.
conv_params: TNConvergenceParameters, optional: Input for handling convergence parameters Default is None.
kwargsadditional keyword arguments: They are accepted, but not passed to calls in this function.

Return

mps: MPS: Decomposition of tto.

get_bipartition_link(pos_src, pos_dst)[source]

Returns two sets of sites forming the bipartition of the system for a loopless tensor network. The link is specified via two positions in the tensor network.

Arguments

pos_srctuple of two ints: Specifies the first tensor and source of the link.
pos_dsttuple of two ints: Specifies the second tensor and destination of the link.

Returns

sites_srclist of ints: Hilbert space indices when looking from the link towards source tensor and following the links therein.
sites_dstlist of ints: Hilbert space indices when looking from the link towards destination tensor and following the links therein.

get_pos_links(pos)[source]

List of tensor position where links are leading to.

Parameters

posint: Index of the tensor in the MPS

Returns

Tuple[int]: Index of the tensor connected through links to pos. None if they are open links.

get_pos_partner_link_expansion(pos)[source]

Get the position of the partner tensor to use in the link expansion subroutine. It is the tensor towards the center, that is supposed to be more entangled w.r.t. the tensor towards the edge

Parameters

posint: Position w.r.t. which you want to compute the partner

Returns

int: Position of the partner
int: Link of pos pointing towards the partner
int: Link of the partner pointing towards pos

get_rho_i(idx)[source]

Get the reduced density matrix of the site at index idx

Parameters

idxint: Index of the site

Returns

_AbstractQteaTensor: Reduced density matrix of the site

get_substate(first_site, last_site, truncate=False)[source]

Returns the smaller MPS built of tensors from first_site to last_site. Running psi.get_substate(2, 4) results in a two-site subsystem, i.e., consistent with python list indexing [2:4].

Parameters

first_siteint: First site defining a range of tensors which will compose the new MPS. Python indexing assumed, i.e. counting starts from 0.
last_siteint: Last site of a range of tensors which will compose the new MPS. Python indexing assumed, i.e. counting starts from 0.
truncateBool: If False, the MPS tensors are returned as is - possibly with non-dummy links on edge tensors, i.e. a mixed state in MPS form. If True, the edges of MPS will be truncated to dummy links. Default to False.

Return

submps : MPS

get_tensor_of_site(idx)[source]

Generic function to retrieve the tensor for a specific site. Compatible across different tensor network geometries. This function does not shift the gauge center before returning the tensor.

Parameters

idxint: Return tensor containing the link of the local Hilbert space of the idx-th site.

property iso_center: Output the gauge center if it is well defined, otherwise None

iso_towards(new_iso, keep_singvals=False, trunc=False, conv_params=None, move_to_memory_device=True, normalize=False)[source]

Apply the gauge transformation to shift the isometry center to a specific site new_iso. The method might be different for other TN structure, but for the MPS it is the same.

Parameters

new_isoint: Position in the TN of the tensor which should be isometrized.
keep_singvalsbool, optional: If True, keep the singular values even if shifting the iso with a QR decomposition. Default to False.
truncBoolean, optional: If True, the shifting is done via truncated SVD. If False, the shifting is done via QR. Default to False.
conv_paramsTNConvergenceParameters, optional: Convergence parameters to use for the SVD. If None, convergence parameters are taken from the TTN. Default to None.
move_to_memory_devicebool, optional: If True, when a mixed device is used, move the tensors that are not the isometry center back to the memory device. Default to True.
normalizebool, optional: Flag if intermediate steps should normalize. Default to False

Details

The tensors used in the computation will always be moved on the computational device. For example, the isometry movement keeps the isometry center end the effective operators around the center (if present) always on the computational device. If move_to_memory_device is False, then all the tensors (effective operators) on the path from the old iso to the new iso will be kept in the computational device. This is very useful when you iterate some protocol between two tensors, or in general when two tensors are involved.

isometrize_all()[source]: Isometrize towards the default isometry position with no previous isometry center, e.g., works as well on random states.

Returns

None

kron(other, inplace=False, install_iso=False)[source]

Concatenate two MPS, taking the kronecker/outer product of the two states. The bond dimension assumed is the maximum between the two bond dimensions. The function does not renormalize the MPS.

Parameters

otherMPS: MPS to concatenate
inplacebool, optional: If True apply the kronecker product in place. Instead, if inplace=False give as output the product. Default to False.
install_isobool, optional: If true, the isometry center will be installed in the resulting tensor network. The isometry centers of self and other might be shifted in order to do so. For False, the isometry center in the new MPS is not set. Default to False.

Returns

MPS: Concatenation of the first MPS with the second in order

Details

The tensors in the new MPS are not copied, inplace modifications in either self or other to their tensors will be reflected in both MPS, self or other and the new MPS. Inplace-updates include operations like multiplying in-place an MPS and therefore one of its tensors. Since copies on this scale might be expensive for two MPS, they have to be done explicitly.

left_canonize(idx, trunc=False, keep_singvals=False, conv_params=None, move_to_memory_device=True, normalize=False)[source]

Isometrize from left to right, applying a gauge transformation to all bonds between 0 and idx. All sites between the first (leftmost one) and idx are set to (semi)-unitary tensors.

Parameters

idx: int: index of the tensor up to which the canonization occurs
trunc: bool, optional: If True, use the SVD instead of the QR for the canonization. It might be useful to reduce the bond dimension. Default to False.
keep_singvalsbool, optional: If True, keep the singular values even if shifting the iso with a QR decomposition. Default to False.
conv_paramsTNConvergenceParameters, optional: Convergence parameters to use for the SVD in the procedure. If None, convergence parameters are taken from the MPS. Default to None.
move_to_memory_devicebool, optional: If True, when a mixed device is used, move the tensors that are not the isometry center back to the memory device. Default to True.
normalizebool, optional: Flag if singular values should be normalized. Default to False

meas_bond_entropy()[source]

Measure the entanglement entropy along all the sites of the MPS using the Von Neumann entropy \(S_V\) defined as:

\[S_V = - \sum_i^{\chi} s^2 \ln( s^2)\]

with \(s\) the singular values

Return

measuresdict: Keys are the range of the bipartition from 0 to which the entanglement (value) is relative

meas_even_probabilities(threshold, qiskit_convention=False)[source]

Compute the probabilities of measuring a given state if it is greater than a threshold. The function goes down “evenly” on the probability tree. This means that there is the possibility that no state is returned, if their probability is lower then threshold. Furthermore, notice that the maximum number of states returned is :math:`(

rac{1}{threshold})`.

For a different way of computing the probability tree see the function meas_greedy_probabilities() or meas_unbiased_probabilities().

thresholdfloat
Discard all the probabilities lower then the threshold

qiskit_conventionbool, optional
If the sites during the measure are represented such that |201> has site 0 with value one (True, mimicks bits ordering) or with value 2 (False usually used in theoretical computations). Default to False.

probabilitiesdict
Dictionary where the keys are the states while the values their probabilities. The keys are separated by a comma if local_dim > 9.

meas_greedy_probabilities(max_prob, max_iter=None, qiskit_convention=False)[source]

Compute the probabilities of measuring a given state until the total probability measured is greater than the threshold max_prob. The function goes down “greedily” on the probability tree. This means that there is the possibility that a path that was most promising at the tree root will become very computationally demanding and not so informative once reached the leaves. Furthermore, notice that there is no maximum number of states returned, and so the function might be exponentially slow.

For a different way of computing the probability tree see the function meas_even_probabilities() or meas_unbiased_probabilities()

Parameters

max_probfloat: Compute states until you reach this probability
qiskit_conventionbool, optional: If the sites during the measure are represented such that |201> has site 0 with value one (True, mimicks bits ordering) or with value 2 (False usually used in theoretical computations). Default to False.

Return

probabilitiesdict: Dictionary where the keys are the states while the values their probabilities. The keys are separated by a comma if local_dim > 9.

meas_tensor_product(ops, idxs)[source]

Measure the tensor products of n operators ops acting on the indexes idxs. The operators should be MPOs, i.e. rank-4 tensors of shape (left, up, down, right). To retrieve the tensor product operators, left=right=1.

Parameters

opslist of ndarrays: List of numpy arrays which are one-site operators
idxslist of int: Indexes where the operators are applied

Returns

measurefloat: Result of the measurement

meas_weighted_sum(op_strings, idxs_strings, coefs)[source]

Measure the weighted sum of tensor product operators. See meas_tensor_product()

Parameters

op_stringslist of lists of ndarray: list of tensor product operators
idxs_stringslist of list of int: list of indexes of tensor product operators
coefslist of complex: list of the coefficients of the sum

Return

measurecomplex: Result of the measurement

ml_decision_function_two_tensors(two_tensors, environment)[source]

Calculate the decision function from a input tensor named “twotensors” that consists in the contraction of 2 neighbor nodes of the MPS at a certain position:

—( )— —(pos)——(pos_p)— —( )—

| | |

TWO TENSORS |

| ENVIRONMENT

| | |

—( )——-( )— - - - - - - -

Parameters

two_tensorspy:class:_AbstractQteaTensor: Tensor used to get the decision function. It stands for the contraction of two neighbor nodes.
environment_AbstractQteaTensor: Environment for the ‘two tensors contraction’.

Returns

decision_function_AbstractQteaTensor: Contraction of two_tensors and environment.

ml_default_sweep_order(num_tensor_rule)[source]

Default sweep order for a machine learning optimization, where we replace the ground state sweep order.

Arguments

num_tensor_rule: int: Specify if it is a one-tensor or two-tensor update.

Returns

sweep_orderList: List of tensor positions compatible with the corresponding ansatz. For two-site rules, each pair is optimized once which skips one center position in respect to the ground state search for the two-tensor update.

ml_environment_two_tensors(pos, pos_p: None)[source]

Calculate the tensor environment for the two tensors at position pos and pos_p:

—( )— —(pos)——(pos_p)— —( )—

| | |

|

|

| | |

—( )——-( )— - - - - - - -
ENVIRONMENT

Parameters

posint: Index of the 1st tensor in the “two tensor” notation
pos_pint | None: Index of partner tensor. If None, partner tensor will be queried.

Returns

environment_AbstractQteaTensor: Environment for the tensor nodes at position pos and pos_p.

ml_get_gradient_single_tensor(pos)[source]

Get the gradient w.r.t. to the tensor at pos similar to the two-tensor version.

Parameters

posint: Index of the tensor to work with.

Returns

grad_AbstractQteaTensor: Gradient tensor
lossfloat: The loss function.

ml_get_gradient_two_tensors(pos, pos_p=None)[source]

Get the gradient w.r.t. the tensors at position pos, pos_p of the MPS following the procedure explained in https://arxiv.org/pdf/1605.05775.pdf for the data_sample given

Parameters

posint: Index of the tensor to optimize
pos_pint | None: Index of partner tensor. If None, partner tensor will be queried.

Returns

grad_AbstractQteaTensor: Gradient tensor
lossfloat: The loss function.

ml_gradient_of_cost_function_two_tensors(two_tensors, environment)[source]

Get the gradient w.r.t. a given tensor named “twotensors” knowing its environment, following the procedure explained in https://arxiv.org/pdf/1605.05775.pdf for the data_sample given.

—( )— —(pos)——(pos_p)— —( )—

| | |

TWO TENSORS |

| ENVIRONMENT

| | |

—( )——-( )— - - - - - - -

Parameters

two_tensorspy:class:_AbstractQteaTensor: Tensor used to get the decision function. It stands for the contraction of two neighbor nodes.
environment_AbstractQteaTensor: Environment for the ‘two tensors contraction’.

Returns

tgrad_AbstractQteaTensor: update/variation/gradient w.r.t. “twotensors”.
lossfloat: The loss function.

classmethod ml_initial_guess(convergence_parameters, tensor_backend, initialize, ml_data_mpo, dataset, has_trivial_label_link=True, has_env_label_link=False)[source]

Generate an initial guess for a tensor network machine learning approach.

Arguments

convergence_parametersTNConvergenceParameters: Class for handling convergence parameters. In particular, the parameter ini_bond_dimension is of interest when aiming to tune the bond dimension of the initial guess.
tensor_backendTensorBackend: Selecting the tensor backend to run the simulations with.
initializestr: The string superposition-data will trigger the superposition of the data set. All other strings will be forwarded to the init method of the underlying ansatz.
ml_data_mpoMLDataMPO: MPO of the labeled data set to be learned including the labels.
datasetList[MPS]: Data set represented as list of MPS states. Same order as in ml_data_mpo. Only accessed in case of superposition-data.
has_trivial_linkbool, optional: With a trivial link (True), the ML-MPS learns solely based on the overlap of the sample with the ansatz rounded to the closest integer. Instead, the typical ML approach with argmax over a vector is used with has_trivial_link=False. Default to True
has_env_label_linkbool, optional: Move label link into the environment, which means here having a non-trivial link towards the environment in the ansatz. Default to False.

Returns

ansatz_AbstractTN: Standard initialization of TN ansatz or Weighted superposition of the data set, wehere the weight is the label-value plus an offset of 0.1.

ml_reorder_pos_pair(pos, pos_partner, link_pos, link_partner)[source]

MPS order is with left tensor first.

Arguments

posint | tuple[int]: Position of the first tensor in the network.
pos_partnerint | tuple[int]: Position of the partner tensor in the network.
link_posint: Link in tensor connecting to partner tensor.
link_partnerint: Link in partner tensor connecting to tensor.

Returns

pos, pos_partner, link_pos, link_partner: Re-ordering of tensor and partner tensor if beneficial.

ml_two_tensor_step(pos, num_grad_steps=1)[source]

Do a gradient descent step via backpropagation with two tensors and the label link in the environment.

Parameters

posint | tuple(int): Position of the tensor to be optimized in the network.
num_grad_stepsint: Number of steps as loop in the gradient descent.

Returns

lossfloat (as native data type of the backend on the CPU): Value of the loss function.

ml_update_conjugate_gradient_two_tensors(pos, pos_p=None)[source]

Get the optimized “two_tensors” at position pos, pos_p through Conjugate gradient descent strategy following a procedure based upon https://arxiv.org/pdf/1605.05775.pdf for the data_sample given.

the name of the variables in the following is chosen upon Conj. Grad. Algor. in https://en.wikipedia.org/wiki/Conjugate_gradient_method

Parameters

posint: Index of the tensor to optimize
pos_pint | None: Index of partner tensor. If None, partner tensor will be queried.

Returns

opt_two_tensors_AbstractQteaTensor: Optimized tensor through gradient descent algorithm
lossfloat: The loss function.

modify_local_dim(value, idxs=None)[source]

Modify the local dimension of sites idxs to the value value. By default modify the local dimension of all the sites. If value is a vector then it must have the same length of idxs. Notice that there may be loss of information, it is up to the user to be sure no error is done in this procedure.

Parameters

valueint or array-like: New value of the local dimension. If an int, it is assumed it will be the same for all sites idxs, otherwise its length must be the same of idxs.
idxsint or array-like, optional: Indexes of the sites to modify. If None, all the sites are modified. Default to None.

classmethod mpi_bcast(state, comm, tensor_backend, root=0)[source]

Broadcast a whole tensor network.

Arguments

stateMPS (for MPI-rank root, otherwise None is acceptable): State to be broadcasted via MPI.
commMPI communicator: Send state to this group of MPI processes.
tensor_backendTensorBackend: Needed to identity data types and tensor classes on receiving MPI threads (plus checks on sending MPI thread).
rootint, optional: MPI-rank of sending thread with the state. Default to 0.

static mpi_sample_n_unique_states(state, num_unique, comm, tensor_backend, cache_size=None, cache_clearing_strategy=None, filter_func=None, mpi_final_op=None, root=0, **kwargs)[source]: Try sampling a target number of unique states from TN ansatz.

mps_multiply_mps(other)[source]

Elementwise multiplication of the MPS with another MPS, resulting multiplying the coefficients of the statevector representation. If self represents the state a|000>+b|111> and other represent c|000>+d|111> then self.mps_multiply_mps(other)=ac|000>+bd|111>. It is very computationally demanding and the new bond dimension is the product of the two original bond dimensions.

Parameters

otherMPS: MPS to multiply

Returns

MPS: Summation of the first MPS with the second

norm()[source]

Returns the norm of the MPS as sqrt(<self|self>)

Return

norm: float: norm of the MPS

normalize()[source]: Normalize the MPS state, by dividing by \(\sqrt{<\psi|\psi>}\).

property physical_idxs: Physical indices property

plot(fig, axis, link_quantity=None, plot_tensors=False, noticks=True, colormap='jet', cmap_label=None)[source]

Plot the MPS in a matplotlib figure on a specific axis. The plot is an MPS, with links and tensors. The physical links are not represented. The color of the links is encoding the link_quantity value. For example, if the link quantity is the entanglement, the color of the link will encode the entanglement of that link. You can pass some quantity that will be represented as a colorcode on the link.

TODO: add color code for quantities for the tensors too.

Parameters

figmatplotlib Figure: The figure where to plot
axismatplotlib axis: The axis where to plot
link_quantitynp.ndarray, optional: Colorcode of the link through np.ndarray of double, by default None. If None, black is used
plot_tensorsbool, optional: If True, plot tensors as white dots with black edge, by default False
noticksbool, optional: If True, remove the ticks from the axis, by default True
colormapstr, optional: Colormap to use, by default “jet”
cmap_label: str, optional: Label of the colormap, by default None.

Returns

None: Acts in place on the figure/axis

classmethod product_state_from_local_states(mat, padding=None, convergence_parameters=None, tensor_backend=None)[source]

Construct a product (separable) state in MPS form, given the local states of each of the sites.

Parameters

matList[np.array of rank 1] or np.array of rank 2: Matrix with ii-th row being a (normalized) local state of the ii-th site. Number of rows is therefore equal to the number of sites, and number of columns corresponds to the local dimension. Pass a list if different sites have different local dimensions so that they require arrays of different size.
paddingnp.array of length 2 or None, optional: Used to enable the growth of bond dimension in TDVP algorithms for MPS (necessary as well for two tensor updates). If not None, all the MPS tensors are padded such that the bond dimension is equal to padding[0]. The value padding[1] tells with which value are we padding the tensors. Note that padding[1] should be very small, as it plays the role of numerical noise. If False, the bond dimensions are equal to 1. Default to None.
convergence_parametersTNConvergenceParameters, optional: Convergence parameters for the new MPS.
tensor_backendNone or instance of TensorBackend: Default for None is QteaTensor with np.complex128 on CPU.

Return

MPS: Corresponding product state MPS.

static projector_attr() → str | None[source]

Name as string of the projector class to be used with the ansatz.

Returns:: Name usable as getattr(qtealeaves.mpos, return_value) to get the actual effective projector suitable for this class. If no effective projector class is avaiable, None is returned.

classmethod read(filename, tensor_backend, cmplx=True, order='F')[source]

Read an MPS via pickle or in the old formatted way shared with the Quantum TEA fortran modules.

Parameters

filename: str: PATH to the file
tensor_backendTensorBackend: Setup which tensor class to create.
cmplx: bool, optional: If True the MPS is complex, real otherwise. Default to True
order: str, optional: If ‘F’ the tensor is transformed from column-major to row-major, if ‘C’ it is left as read.

Returns

obj: py:class:MPS: MPS class read from file

Details

The formatted format looks like in the following:

Reads in column-major order but the output is in row-major. This is the only method that overrides the number of sites, since you may not know before reading.

reset(idxs=None)[source]

Reset the states of the sites idxs to the |0> state

Parameters

idxsint or list of ints, optional: indexes of the sites to reinitialize to 0. If default value is left all the sites are restarted.

right_canonize(idx, trunc=False, keep_singvals=False, conv_params=None, move_to_memory_device=True, normalize=False)[source]

Isometrize from right to left, applying a gauge transformation to all bonds between :py:method:`MPS.num_sites` and idx. All sites between the last (rightmost one) and idx are set to (semi)-unitary tensors.

Parameters

idx: int: index of the tensor up to which the canonization occurs
trunc: bool, optional: If True, use the SVD instead of the QR for the canonization. It might be useful to reduce the bond dimension. Default to False.
keep_singvalsbool, optional: If True, keep the singular values even if shifting the iso with a QR decomposition. Default to False.
conv_paramsTNConvergenceParameters, optional: Convergence parameters to use for the SVD in the procedure. If None, convergence parameters are taken from the TTN. Default to None.
move_to_memory_devicebool, optional: If True, when a mixed device is used, move the tensors that are not the isometry center back to the memory device. Default to True.
normalizebool, optional: Flag if intermediate steps should normalize. Default to False

sanity_check()[source]

A set of sanity checks helping for debugging which can be activated via the global variable RUN_SANITY_CHECK in this file.

Raises

QTeaLeavesError for any failing check.

Details

Runs checks on

Bond dimension between neighboring tensors.
Non-trivial local dimension

scale(factor)[source]

Scale the MPS state by a scalar constant using the gauge center.

Parameters

factorscalar: Factor is multiplied to the MPS at the gauge center.

scale_inverse(factor)[source]

Scale the MPS state by a scalar constant using the gauge center.

Parameters

factorscalar: Factor is multiplied to the MPS at the gauge center.

set_singvals_on_link(pos_a, pos_b, s_vals)[source]: Update or set singvals on link via two positions.

property singvals: List of singular values in the bonds

site_canonize(idx, keep_singvals=False, normalize=False)[source]

Apply the gauge transformation to shift the isometry center to a specific site idx.

Parameters

idx: int: index of the tensor up to which the canonization occurs from the left and right side.
keep_singvalsbool, optional: If True, keep the singular values even if shifting the iso with a QR decomposition. Default to False.
normalizebool, optional: Flag if intermediate steps should normalize. Default to False

classmethod sum_approximate(sum_states, sum_amplitudes=None, convergence_parameters=None, initial_state=None, max_iterations=10, dif_goal=None, normalize_result=True)[source]

Computes the optimal MPS representation of the sum a_i psi_i for a set of MPS psi_i and ampltudes a_i. Uses the MPSProjectors to optimize the sum.

Arguments sum_states : list[MPS]

List of MPSs to sum.

sum_amplitudeslist[float] | np.ndarray[float] | None: List of amplitudes for each summand. If None, all are set to 1.
convergence_parametersTNConvergenceParameters: The convergence parameters for the resulting state. If None, a default convergence parameters object is created.
initial_stateMPS | None: The initial state for the optimization. If None will start with a random state.
max_iterationsint: The maximal number of iterations to optimize the sum.
dif_goalfloat: The convergence is gauged by computing |<psi|psi_i> - a_i|. We stop if this is smaller than dif_goal for all i. Default to machine precision.
normalize_resultbool: Whether to normalize the result.

Returns MPS : A MPS approximation of the sum.

swap_qubits(sites, conv_params=None, trunc=True)[source]

This function applies a swap gate to sites in an MPS, i.e. swaps these two qubits

Parameters

sitesTuple[int]: The qubits on site sites[0] and sites[1] are swapped
conv_paramsTNConvergenceParameters, optional: Convergence parameters to use for the SVD in the procedure. If None, convergence parameters are taken from the TTN. Default to None.

Return

np.ndarray: Singualr values cut in the process of shifting the isometry center. None if moved through the QR.

property tensors: List of MPS tensors

to_dense(true_copy=False)[source]

Return MPS without symmetric tensors.

Parameters

true_copybool, optional: The function can be forced to return an actual copy with true_copy=True, while otherwise self can be returned if the MPS is already without symmetries. Default to False

Returns

dense_mpsMPS: MPS representation without symmetric tensors.

to_statevector(qiskit_order=False, max_qubit_equivalent=20)[source]

Given a list of N tensors MPS [U1, U2, …, UN] , representing a Matrix Product State, perform the contraction in the Examples, leading to a single tensor of order N, representing a dense state.

The index ordering convention is from left-to-right. For instance, the “left” index of U2 is the first, the “bottom” one is the second, and the “right” one is the third.

Parameters

qiskit_order: bool, optional: weather to use qiskit ordering or the theoretical one. For example the state |011> has 0 in the first position for the theoretical ordering, while for qiskit ordering it is on the last position.
max_qubit_equivalent: int, optional: Maximum number of qubit sites the MPS can have and still be transformed into a statevector. If the number of sites is greater, it will throw an exception. Default to 20.

Returns

psindarray of shape (d ^ N, ): N-order tensor representing the dense state.

Examples

>>> U1 - U2 - ... - UN
>>>  |    |          |

to_tensor_list()[source]

Return the tensor list representation of the MPS. Required for compatibility with TTN emulator

Return

list: List of tensors of the MPS

to_ttn(trunc=False, convergence_parameters=None)[source]: Return a tree tensor network (TTN) representation as binary tree.

Details

The TTN is returned as a listed list where the tree layer with the local Hilbert space is the first list entry and the uppermost layer in the TTN is the last list entry. The first list will have num_sites / 2 entries. The uppermost list has two entries.

The order of the legs is always left-child, right-child, parent with the exception of the left top tensor. The left top tensor has an additional link, i.e., the symmetry selector; the order is left-child, right-child, parent, symmetry-selector.

Also see :py:func:ttn_simulator:`from_tensor_list`.

write(filename, cmplx=True)[source]

Write an MPS in python format into a FORTRAN format, i.e. transforms row-major into column-major

Parameters

filename: str: PATH to the file
cmplx: bool, optional: If True the MPS is complex, real otherwise. Default to True

Returns

None