Decompositions#

vec_to_mps#

tensorkrowch.decompositions.vec_to_mps(vec, n_batches=0, rank=None, cum_percentage=None, cutoff=None, renormalize=False)[source]#

Splits a vector into a sequence of MPS tensors via consecutive SVD decompositions. The resultant tensors can be used to instantiate a MPS with boundary = "obc".

The number of resultant tensors and their respective physical dimensions depend on the shape of the input vector. That is, if one expects to recover a MPS with physical dimensions

\[d_1 \times \cdots \times d_n\]

the input vector will have to be provided with that shape. This can be done with reshape.

If the input vector has batch dimensions, having as shape

\[b_1 \times \cdots \times b_m \times d_1 \times \cdots \times d_n\]

the number of batch dimensions \(m\) can be specified in n_batches. In this case, the resultant tensors will all have the extra batch dimensions. These tensors can be used to instantiate a MPSData with boundary = "obc".

To specify the bond dimension of each cut done via SVD, one can use the arguments rank, cum_percentage and cutoff. If more than one is specified, the resulting rank will be the one that satisfies all conditions.

Parameters:

  • vec (torch.Tensor) – Input vector to decompose.

  • n_batches (int) – Number of batch dimensions of the input vector. Each resultant tensor will have also the corresponding batch dimensions. It should be between 0 and the rank of vec.

  • rank (int, optional) – Number of singular values to keep.

  • cum_percentage (float, optional) –

    Proportion that should be satisfied between the sum of all singular values kept and the total sum of all singular values.

    \[\frac{\sum_{i \in \{kept\}}{s_i}}{\sum_{i \in \{all\}}{s_i}} \ge cum\_percentage\]

  • cutoff (float, optional) – Quantity that lower bounds singular values in order to be kept.

  • renormalize (bool) – Indicates whether nodes should be renormalized after SVD/QR decompositions. If not, it may happen that the norm explodes as it is being accumulated from all nodes. Renormalization aims to avoid this undesired behavior by extracting the norm of each node on a logarithmic scale after SVD/QR decompositions are computed. Finally, the normalization factor is evenly distributed among all nodes of the MPS.

Return type:

List[torch.Tensor]

mat_to_mpo#

tensorkrowch.decompositions.mat_to_mpo(mat, rank=None, cum_percentage=None, cutoff=None, renormalize=False)[source]#

Splits a matrix into a sequence of MPO tensors via consecutive SVD decompositions. The resultant tensors can be used to instantiate a MPO with boundary = "obc".

The number of resultant tensors and their respective input/output dimensions depend on the shape of the input matrix. That is, if one expects to recover a MPO with input/output dimensions

\[in_1 \times out_1 \times \cdots \times in_n \times out_n\]

the input matrix will have to be provided with that shape. Thus it must have an even number of dimensions. To accomplish this, it may happen that some input/output dimensions are 1. This can be done with reshape.

To specify the bond dimension of each cut done via SVD, one can use the arguments rank, cum_percentage and cutoff. If more than one is specified, the resulting rank will be the one that satisfies all conditions.

Parameters:

  • mat (torch.Tensor) – Input matrix to decompose. It must have an even number of dimensions.

  • rank (int, optional) – Number of singular values to keep.

  • cum_percentage (float, optional) –

    Proportion that should be satisfied between the sum of all singular values kept and the total sum of all singular values.

    \[\frac{\sum_{i \in \{kept\}}{s_i}}{\sum_{i \in \{all\}}{s_i}} \ge cum\_percentage\]

  • cutoff (float, optional) – Quantity that lower bounds singular values in order to be kept.

  • renormalize (bool) – Indicates whether nodes should be renormalized after SVD/QR decompositions. If not, it may happen that the norm explodes as it is being accumulated from all nodes. Renormalization aims to avoid this undesired behavior by extracting the norm of each node on a logarithmic scale after SVD/QR decompositions are computed. Finally, the normalization factor is evenly distributed among all nodes of the MPS.

Return type:

List[torch.Tensor]

tt_rss#

tensorkrowch.decompositions.tt_rss(function, embedding, sketch_samples, labels=None, domain=None, domain_multiplier=1, out_position=None, rank=None, cum_percentage=None, batch_size=64, device=None, verbose=True, return_info=False)[source]#

Tensor Train via Recursive Sketching from Samples.

Decomposes a scalar or vector-valued function of \(N\) input variables in a Matrix Product State of \(N\) cores, each corresponding to one input variable, in the same order as they are provided to the function. To turn each input variable into a vector that can be contracted with the corresponding MPS core, an embedding function is required. The dimension of the embedding will be used as the input dimension of the MPS.

If the function is vector-valued, it will be seen as a \(N + 1\) scalar function, returning a MPS with \(N + 1\) cores. The output variable will use the embedding basis(), which maps integers (corresponding to indices of the output vector) to basis vectors: \(i \mapsto \langle i \rvert\). It can be specified the position in which the output core will be. By default, it will be in the middle of the MPS.

To specify the bond dimension of each MPS core, one can use the arguments rank and cum_percentage. If more than one is specified, the resulting rank will be the one that satisfies all conditions.

Parameters:

  • function (Callable) – Function that is going to be decomposed. It needs to have a single input argument, the data, which is a tensor of shape batch_size x n_features or batch_size x n_features x in_dim. It must return a tensor of shape batch_size x out_dim. If the function is scalar, out_dim = 1.

  • embedding (Callable) – Embedding function that maps the data tensor to a higher dimensional space. It needs to have a single argument. It is a function that transforms the given data tensor of shape batch_size x n_features or batch_size x n_features x in_dim and returns an embedded tensor of shape batch_size x n_features x embed_dim.

  • sketch_samples (torch.Tensor) – Samples that will be used as sketches to decompose the function. It has to be a tensor of shape batch_size x n_features or batch_size x n_features x in_dim.

  • labels (torch.Tensor, optional) – Tensor of output labels of the function with shape batch_size. If function is vector-valued, labels will be used to select an element from each output vector. If labels are not given, these will be obtained according to the distribution represented by the output vectors (assuming these represent square roots of probabilities for each class).

  • domain (torch.Tensor or list[torch.Tensor], optional) – Domain of the input variables. It should be given as a finite set of possible values that can take each variable. If all variables live in the same domain, it should be given as a tensor with shape n_values or n_values x in_dim, where the possible n_values should be at least as large as the desired input dimension of the MPS cores, which is the embed_dim of the embedding. The more values are given, the more accurate will be the tensorization but more costly will be to do it. If domain is given as a list, it should have the same number of elements as input variables, so that each variable can live in a different domain. If domain is not given, it will be obtained from the values each variable takes in the sketch_samples.

  • domain_multiplier (int) – Upper bound for how many values are used for the input variable domain if domain is not provided. If domain is not provided, the domain of the input variables will be inferred from the unique values each variable takes in the sketch_samples. In this case, only domain_multiplier * embed_dim values will be taken randomly.

  • out_position (int, optional) – If the function is vector-valued, position of the output core in the resulting MPS.

  • rank (int, optional) – Upper bound for the bond dimension of all cores.

  • cum_percentage (float, optional) – When getting the proper bond dimension of each core via truncated SVD, this is the proportion that should be satisfied between the sum of all singular values kept and the total sum of all singular values. Therefore, it specifies the rank of each core independently, allowing for varying bond dimensions.

  • batch_size (int) – Batch size used to process sketch_samples with DataLoaders during the decomposition.

  • device (torch.device, optional) – Device to which sketch_samples will be sent to compute sketches. It should coincide with the device the function is in, in the case the function is a call to a nn.Module or uses tensors that are in a specific device. This also applies to the embedding function.

  • verbose (bool) – Default is True.

  • return_info (bool) – Boolean indicating if an additional dictionary with total time and validation error should be returned.

Returns:

  • list[torch.Tensor] – List of tensor cores of the MPS.

  • dictionary – If return_info is True.