qml.math

Overview

This package contains unified functions for framework-agnostic tensor and array manipulation. Given the input tensor-like object, the call is dispatched to the corresponding array manipulation framework, allowing for end-to-end differentiation to be preserved.

Warning

These functions are experimental, and only a subset of common functionality is supported. Furthermore, the names and behaviour of these functions may differ from similar functions in common frameworks; please refer to the function docstrings for more details.

The following frameworks are currently supported:

  • NumPy

  • Autograd

  • TensorFlow

  • PyTorch

  • JAX

Functions

add(*args[, like])

Add arguments element-wise.

allclose(a, b[, rtol, atol])

Returns True if two arrays are element-wise equal within a tolerance.

allequal(tensor1, tensor2, **kwargs)

Returns True if two tensors are element-wise equal along a given axis.

array(*args[, like])

Creates an array or tensor object of the target framework.

block_diag(values[, like])

Combine a sequence of 2D tensors to form a block diagonal tensor.

cast(tensor, dtype)

Casts the given tensor to a new type.

cast_like(tensor1, tensor2)

Casts a tensor to the same dtype as another.

concatenate(values[, axis, like])

Concatenate a sequence of tensors along the specified axis.

convert_like(tensor1, tensor2)

Convert a tensor to the same type as another.

convert_to_su2(U[, return_global_phase])

Convert a 2x2 unitary matrix to \(SU(2)\).

convert_to_su4(U[, return_global_phase])

Convert a 4x4 matrix to \(SU(4)\).

cov_matrix(prob, obs[, wires, diag_approx])

Calculate the covariance matrix of a list of commuting observables, given the joint probability distribution of the system in the shared eigenbasis.

detach(tensor[, like])

Detach a tensor from its trace and return just its numerical values.

diag(values[, k, like])

Construct a diagonal tensor from a list of scalars.

dm_from_state_vector(state[, check_state, ...])

Convenience function to compute a (full) density matrix from a state vector.

dot(tensor1, tensor2[, like])

Returns the matrix or dot product of two tensors.

einsum(indices, *operands[, like, optimize])

Evaluates the Einstein summation convention on the operands.

expand_matrix(mat, wires[, wire_order, ...])

Re-express a matrix acting on a subspace defined by a set of wire labels according to a global wire order.

expand_vector(vector, original_wires, ...)

Expand a vector to more wires.

expectation_value(operator_matrix, state_vector)

Compute the expectation value of an operator with respect to a pure state.

expm(tensor[, like])

Compute the matrix exponential of an array \(e^{X}\).

eye(*args[, like])

Creates an identity array or tensor object of the target framework.

fidelity(state0, state1[, check_state, c_dtype])

Compute the fidelity for two states (given as density matrices) acting on quantum systems with the same size.

fidelity_statevector(state0, state1[, ...])

Compute the fidelity for two states (given as state vectors) acting on quantum systems with the same size.

frobenius_inner_product(A, B[, normalize, like])

Frobenius inner product between two matrices.

gammainc(m, t[, like])

Return the lower incomplete Gamma function.

get_dtype_name(x)

An interface independent way of getting the name of the datatype.

get_interface(*values)

Determines the correct framework to dispatch to given a tensor-like object or a sequence of tensor-like objects.

get_batch_size(tensor, expected_shape, ...)

Determine whether a tensor has an additional batch dimension for broadcasting, compared to an expected_shape.

get_canonical_interface_name(user_input)

Helper function to get the canonical interface name.

get_deep_interface(value)

Given a deep data structure with interface-specific scalars at the bottom, return their interface name.

get_trainable_indices(values[, like])

Returns a set containing the trainable indices of a sequence of values.

grad(f[, argnums])

Compute the gradient in a jax-like manner for any interface.

in_backprop(tensor[, interface])

Returns True if the tensor is considered to be in a backpropagation environment, it works for Autograd, TensorFlow and Jax.

is_abstract(tensor[, like])

Returns True if the tensor is considered abstract.

is_independent(func, interface, args[, ...])

Test whether a function is independent of its input arguments, both numerically and analytically.

iscomplex(tensor[, like])

Return True if the tensor has a non-zero complex component.

jacobian(f[, argnums])

Compute the Jacobian in a jax-like manner for any interface.

kron(*args[, like])

The kronecker/tensor product of args.

matmul(tensor1, tensor2[, like])

Returns the matrix product of two tensors.

marginal_prob(prob, axis)

Compute the marginal probability given a joint probability distribution expressed as a tensor.

max_entropy(state, indices[, base, ...])

Compute the maximum entropy of a density matrix on a given subsystem.

min_entropy(state, indices[, base, ...])

Compute the minimum entropy from a density matrix.

multi_dispatch([argnum, tensor_list])

Decorator to dispatch arguments handled by the interface.

mutual_info(state, indices0, indices1[, ...])

Compute the mutual information between two subsystems given a state:

norm(tensor[, like])

Compute the norm of a tensor in each interface.

ones_like(tensor[, dtype])

Returns a tensor of all ones with the same shape and dtype as the input tensor.

partial_trace(matrix, indices[, c_dtype])

Compute the reduced density matrix by tracing out the provided indices.

purity(state, indices[, check_state, c_dtype])

Computes the purity of a density matrix.

reduce_dm(density_matrix, indices[, ...])

Compute the density matrix from a state represented with a density matrix.

reduce_matrices(mats_and_wires_gen, reduce_func)

Apply the given reduce_func cumulatively to the items of the mats_and_wires_gen generator, from left to right, reducing the sequence to a tuple containing a single matrix and the wires it acts on.

reduce_statevector(state, indices[, ...])

Compute the density matrix from a state vector.

binary_finite_reduced_row_echelon(binary_matrix)

Returns the reduced row echelon form (RREF) of a matrix in a binary finite field \(\mathbb{Z}_2\).

relative_entropy(state0, state1[, base, ...])

Compute the quantum relative entropy of one state with respect to another.

requires_grad(tensor[, interface])

Returns True if the tensor is considered trainable.

scatter(indices, array, new_dims[, like])

Scatters an array into a tensor of shape new_dims according to indices.

scatter_element_add(tensor, index, value[, ...])

In-place addition of a multidimensional value over various indices of a tensor.

set_index(array, idx, val[, like])

Set the value at a specified index in an array.

sqrt_matrix(density_matrix)

Compute the square root matrix of a density matrix where \(\rho = \sqrt{\rho} \times \sqrt{\rho}\)

stack(values[, axis, like])

Stack a sequence of tensors along the specified axis.

svd(tensor[, like])

Compute the singular value decomposition of a tensor in each interface.

tensordot(tensor1, tensor2[, axes, like])

Returns the tensor product of two tensors.

trace_distance(state0, state1[, ...])

Compute the trace distance between two quantum states.

unwrap(values[, max_depth])

Unwrap a sequence of objects to NumPy arrays.

vn_entropy(state, indices[, base, ...])

Compute the Von Neumann entropy from a density matrix on a given subsystem.

vn_entanglement_entropy(state, indices0, ...)

Compute the Von Neumann entanglement entropy between two subsystems in a given state.

where(condition[, x, y])

Returns elements chosen from x or y depending on a boolean tensor condition, or the indices of entries satisfying the condition.

Classes

Interface(value)

Canonical set of interfaces supported.

Utility functions for decompositions

Utility functions for decompositions are available from qml.math.decomposition.

Functions

decomp_int_to_powers_of_two(k, n)

Decompose an integer \(k<=2^{n-1}\) into additions and subtractions of the smallest-possible number of powers of two.

givens_decomposition(unitary)

Decompose a unitary into a sequence of Givens rotation gates with phase shifts and a diagonal phase matrix.

su2su2_to_tensor_products(U)

Given a matrix \(U = A \otimes B\) in SU(2) x SU(2), extract A and B

xyx_rotation_angles(U[, return_global_phase])

Compute the rotation angles \(\lambda\), \(\theta\), and \(\phi\) and the phase \(\alpha\) of a 2x2 unitary matrix as a product of X and Y rotations in the form \(e^{i\alpha} RX(\phi) RY(\theta) RX(\lambda)\).

xzx_rotation_angles(U[, return_global_phase])

Compute the rotation angles \(\lambda\), \(\theta\), and \(\phi\) and the phase \(\alpha\) of a 2x2 unitary matrix as a product of X and Z rotations in the form \(e^{i\alpha} RX(\phi) RZ(\theta) RX(\lambda)\).

zxz_rotation_angles(U[, return_global_phase])

Compute the rotation angles \(\lambda\), \(\theta\), and \(\phi\) and the phase \(\alpha\) of a 2x2 unitary matrix as a product of Z and X rotations in the form \(e^{i\alpha} RZ(\phi) RX(\theta) RZ(\lambda)\).

zyz_rotation_angles(U[, return_global_phase])

Compute the rotation angles \(\phi\), \(\theta\), and \(\omega\) and the phase \(\alpha\) of a 2x2 unitary matrix as a product of Z and Y rotations in the form \(e^{i\alpha} RZ(\omega) RY(\theta) RZ(\phi)\)