Source code for pennylane.math.utils

# Copyright 2018-2021 Xanadu Quantum Technologies Inc.

# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at

#     http://www.apache.org/licenses/LICENSE-2.0

# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Utility functions"""

# pylint: disable=wrong-import-order


import numbers

import autoray as ar
import jax
import numpy as _np
import scipy as sp
from autograd.numpy.numpy_boxes import ArrayBox
from autoray import numpy as np

from pennylane import math


[docs] def allequal(tensor1, tensor2, **kwargs): """Returns True if two tensors are element-wise equal along a given axis. This function is equivalent to calling ``np.all(tensor1 == tensor2, **kwargs)``, but allows for ``tensor1`` and ``tensor2`` to differ in type. Args: tensor1 (tensor_like): tensor to compare tensor2 (tensor_like): tensor to compare **kwargs: Accepts any keyword argument that is accepted by ``np.all``, such as ``axis``, ``out``, and ``keepdims``. See the `NumPy documentation <https://numpy.org/doc/stable/reference/generated/numpy.all.html>`__ for more details. Returns: ndarray, bool: If ``axis=None``, a logical AND reduction is applied to all elements and a boolean will be returned, indicating if all elements evaluate to ``True``. Otherwise, a boolean NumPy array will be returned. **Example** >>> a = torch.tensor([1, 2]) >>> b = np.array([1, 2]) >>> allequal(a, b) True """ t1 = ar.to_numpy(tensor1) t2 = ar.to_numpy(tensor2) return np.all(t1 == t2, **kwargs)
def _allclose_sparse(a, b, rtol=1e-05, atol=1e-08): """Compare two sparse matrices for approximate equality. Args: a, b: scipy sparse matrices to compare rtol (float): relative tolerance atol (float): absolute tolerance Returns: bool: True if matrices are approximately equal """ if (a != b).nnz == 0: return True diff = abs(a - b) # Handle cases where the matrix might be empty max_diff = diff.data.max() if diff.nnz > 0 else 0 max_b = abs(b).data.max() if b.nnz > 0 else 0 return max_diff <= atol + rtol * max_b def _mixed_shape_match(a, b): """Check if the shapes of two matrices of mixed types are compatible for comparison. Args: a, b: matrices to compare Returns: bool: True if the shapes are compatible """ a_shapes = a.shape b_shapes = b.shape # Take the product, if inequal then false if np.prod(a_shapes) != np.prod(b_shapes): return False # Make the sets of shapes, and ignore '1' a_shape_set = set(a_shapes) - {1} b_shape_set = set(b_shapes) - {1} if len(a_shape_set) == len(b_shape_set) == 1: return True # For intrinsic one-dimensional arrays return a_shapes == b_shapes def _allclose_mixed(a, b, rtol=1e-05, atol=1e-08, b_is_sparse=True): """Helper function for comparing dense and sparse matrices with correct tolerance reference. Args: a: first matrix (dense or sparse) b: second matrix (sparse or dense) rtol: relative tolerance atol: absolute tolerance b_is_sparse: True if b is sparse matrix, False if a is sparse matrix Returns: bool: True if matrices are approximately equal """ sparse = b if b_is_sparse else a dense = a if b_is_sparse else b if sparse.nnz == 0: return np.allclose(dense, 0, rtol=rtol, atol=atol) if not _mixed_shape_match(dense, sparse): return False SIZE_THRESHOLD = 10000 if np.prod(dense.shape) < SIZE_THRESHOLD: # Use dense comparison but maintain b as reference if b_is_sparse: return np.allclose(a, sparse.toarray(), rtol=rtol, atol=atol) return np.allclose(sparse.toarray(), b, rtol=rtol, atol=atol) dense_coords = dense.nonzero() sparse_coords = sparse.nonzero() coord_diff = set(zip(*dense_coords, strict=True)) ^ set(zip(*sparse_coords, strict=True)) if coord_diff: return False # Maintain asymmetric comparison with correct reference if b_is_sparse: a_data = dense[dense_coords] b_data = sparse.data else: a_data = sparse.data b_data = dense[sparse_coords] return np.allclose(a_data, b_data, rtol=rtol, atol=atol) def _allclose_sparse_scalar(sparse_mat, scalar, rtol=1e-05, atol=1e-08): """Compare a sparse matrix to a scalar value. This function checks if a sparse matrix is approximately equal to a scalar value by considering three cases: 1. Empty/zero sparse matrix compared to any scalar -> scalar must be close to zero 2. Sparse matrix with non-zero values compared to a scalar -> all non-zero values must match 3. Following case 2, if scalar is zero, any sparsity pattern is allowed 4. If the scalar is non-zero, all elements must be non-zero, e.g. size match nnz Args: sparse_mat: A scipy sparse matrix scalar: A scalar value to compare against rtol: Relative tolerance atol: Absolute tolerance Returns: bool: True if the sparse matrix is approximately equal to the scalar """ # Case 1: Empty sparse matrix - only close to zero scalar if sparse_mat.nnz == 0: return np.isclose(scalar, 0, rtol=rtol, atol=atol) # Case 2: Sparse matrix with all non-zero values matching scalar # Check if all non-zeros in the sparse matrix match the scalar if not np.allclose(sparse_mat.data, scalar, rtol=rtol, atol=atol): return False # Note that from this step all the data already close to scalar # Case 3: Special handling for scalar = 0 or fully populated sparse matrix # If scalar is approximately zero, allow any sparsity pattern if np.isclose(scalar, 0, rtol=rtol, atol=atol): return True # If scalar is non-zero, all elements must be non-zero # Use size property for efficiency with very large matrices return sparse_mat.nnz == np.prod(sparse_mat.shape)
[docs] def allclose(a, b, rtol=1e-05, atol=1e-08, **kwargs): """Wrapper around np.allclose, allowing tensors ``a`` and ``b`` to differ in type""" try: # Some frameworks may provide their own allclose implementation. # Try and use it if available. if sp.sparse.issparse(a) and sp.sparse.issparse(b): return _allclose_sparse(a, b, rtol=rtol, atol=atol) # Add handling for sparse matrix compared with scalar if sp.sparse.issparse(a) and np.isscalar(b): return _allclose_sparse_scalar(a, b, rtol=rtol, atol=atol) if sp.sparse.issparse(b) and np.isscalar(a): return _allclose_sparse_scalar(b, a, rtol=rtol, atol=atol) if sp.sparse.issparse(a): return _allclose_mixed(a, b, rtol=rtol, atol=atol, b_is_sparse=False) if sp.sparse.issparse(b): return _allclose_mixed(a, b, rtol=rtol, atol=atol, b_is_sparse=True) res = np.allclose(a, b, rtol=rtol, atol=atol, **kwargs) except (TypeError, AttributeError, ImportError, RuntimeError): # Otherwise, convert the input to NumPy arrays. # # TODO: replace this with a bespoke, framework agnostic # low-level implementation to avoid the NumPy conversion: # # np.abs(a - b) <= atol + rtol * np.abs(b) # t1 = ar.to_numpy(a) t2 = ar.to_numpy(b) res = np.allclose(t1, t2, rtol=rtol, atol=atol, **kwargs) return res
allclose.__doc__ = _np.allclose.__doc__
[docs] def cast(tensor, dtype): """Casts the given tensor to a new type. Args: tensor (tensor_like): tensor to cast dtype (str, np.dtype): Any supported NumPy dtype representation; this can be a string (``"float64"``), a ``np.dtype`` object (``np.dtype("float64")``), or a dtype class (``np.float64``). If ``tensor`` is not a NumPy array, the **equivalent** dtype in the dispatched framework is used. Returns: tensor_like: a tensor with the same shape and values as ``tensor`` and the same dtype as ``dtype`` **Example** We can use NumPy dtype specifiers: >>> x = torch.tensor([1, 2]) >>> cast(x, np.float64) tensor([1., 2.], dtype=torch.float64) We can also use strings: >>> x = torch.tensor([1, 2]) >>> cast(x, "complex128") tensor([1.+0.j, 2.+0.j], dtype=torch.complex128) """ if isinstance(tensor, (list, tuple, int, float, complex)): tensor = np.asarray(tensor) if not isinstance(dtype, str): try: dtype = np.dtype(dtype).name except (AttributeError, TypeError, ImportError): dtype = getattr(dtype, "name", dtype) if math.get_interface(dtype) == "torch": tensor = np.asarray(tensor, like="torch") return ar.astype(tensor, ar.to_backend_dtype(dtype, like=ar.infer_backend(tensor)))
[docs] def cast_like(tensor1, tensor2): """Casts a tensor to the same dtype as another. Args: tensor1 (tensor_like): tensor to cast tensor2 (tensor_like): tensor with corresponding dtype to cast to Returns: tensor_like: a tensor with the same shape and values as ``tensor1`` and the same dtype as ``tensor2`` **Example** >>> x = torch.tensor([1, 2]) >>> y = torch.tensor([3., 4.]) >>> cast_like(x, y) tensor([1., 2.]) """ if isinstance(tensor2, tuple) and len(tensor2) > 0: tensor2 = tensor2[0] # Check for abstract tensors FIRST before trying to convert to numpy # This is important for JAX 0.7.0+ which has additional tracer types if is_tracer(tensor2): dtype = tensor2.dtype elif isinstance(tensor2, ArrayBox): dtype = ar.to_numpy(tensor2._value).dtype.type # pylint: disable=protected-access elif hasattr(tensor2, "dtype"): dtype = tensor2.dtype else: dtype = ar.to_numpy(tensor2).dtype.type return cast(tensor1, dtype)
[docs] def convert_like(tensor1, tensor2): """Convert a tensor to the same type as another. Args: tensor1 (tensor_like): tensor to convert tensor2 (tensor_like): tensor with corresponding type to convert to Returns: tensor_like: a tensor with the same shape, values, and dtype as ``tensor1`` and the same type as ``tensor2``. **Example** >>> x = np.array([1, 2]) >>> y = torch.tensor([3, 4]) >>> convert_like(x, y) tensor([1, 2]) """ interface = math.get_interface(tensor2) if interface == "torch": dev = tensor2.device return np.asarray(tensor1, device=dev, like=interface) if interface == "scipy": return sp.sparse.csr_matrix(tensor1) return np.asarray(tensor1, like=interface)
[docs] def is_tracer(tensor, like=None): """Return whether the tensor is a JAX tracer without a concrete value. Such tracers commonly occur when tracing functions decorated with ``@jax.jit``. This function does not identify PennyLane shape/type descriptors such as ``qp.typing.Float[3]`` or ``qp.typing.Wire[3]``. Tracers with a concrete value also return ``False``. .. note:: Currently Autograd tensors and Torch tensors will always return ``False``. This is because: - Autograd does not provide JIT compilation, and - ``@torch.jit.script`` is not currently compatible with QNodes. Args: tensor (tensor_like): input tensor like (str): The name of the interface. Will be determined automatically if not provided. Returns: bool: whether the tensor is a tracer without a concrete value **Example** Consider the following JAX function: .. code-block:: python import jax from jax import numpy as jnp def function(x): print("Value:", x) print("Tracer:", qp.math.is_tracer(x)) return jnp.sum(x ** 2) When we execute it, we see that the tensor is not abstract; it has known value: >>> x = jnp.array([0.5, 0.1]) >>> function(x) Value: [0.5, 0.1] Tracer: False Array(0.26, dtype=float32) However, if we use the ``@jax.jit`` decorator, the tensor will now be abstract: >>> x = jnp.array([0.5, 0.1]) >>> jax.jit(function)(x) Value: Traced<ShapedArray(float32[2])>with<DynamicJaxprTrace(level=0/1)> Tracer: True Array(0.26, dtype=float32) Note that JAX uses an abstract *shaped* array, so although we won't be able to include conditionals within our function that depend on the value of the tensor, we *can* include conditionals that depend on the shape of the tensor. """ interface = like or math.get_interface(tensor) if interface == "jax": # Use jax.core.Tracer as base class to catch all tracer types including new ones in JAX 0.7.0+ # (e.g., LinearizeTracer, JVPTracer, BatchTracer, JaxprTracer, DynamicJaxprTracer, etc.) if isinstance(tensor, jax.core.Tracer): # Tracer objects will be used when computing gradients or applying transforms. # If the value of the tracer is known, jax.core.is_concrete will return True. # Otherwise, it will be abstract. return not jax.core.is_concrete(tensor) return False # Autograd does not have a JIT # QNodes do not currently support TorchScript: # NotSupportedError: Compiled functions can't take variable number of arguments or # use keyword-only arguments with defaults. return False
# Remove this compatibility alias once supported Catalyst versions use is_tracer. is_abstract = is_tracer
[docs] def requires_grad(tensor, interface=None): """Returns True if the tensor is considered trainable. .. warning:: The implementation depends on the contained tensor type, and may be context dependent. For example, Torch tensors and PennyLane tensors track trainability as a property of the tensor itself. Args: tensor (tensor_like): input tensor interface (str): The name of the interface. Will be determined automatically if not provided. Returns: bool: whether the tensor is trainable or not. **Example** Calling this function on a PennyLane NumPy array: >>> x = np.array([1., 5.], requires_grad=True) >>> requires_grad(x) True >>> x.requires_grad = False >>> requires_grad(x) False PyTorch has similar behaviour. """ interface = interface or math.get_interface(tensor) if interface == "autograd": if isinstance(tensor, ArrayBox): return True return getattr(tensor, "requires_grad", False) if interface == "torch": return getattr(tensor, "requires_grad", False) if interface in {"numpy", "scipy"}: return False if interface == "jax": return isinstance(tensor, jax.core.Tracer) raise ValueError(f"Argument {tensor} is an unknown object")
[docs] def in_backprop(tensor, interface=None): """Returns True if the tensor is considered to be in a backpropagation environment, it works for Autograd and Jax. It is not only checking the differentiability of the tensor like :func:`~.requires_grad`, but rather checking if the gradient is actually calculated. Args: tensor (tensor_like): input tensor interface (str): The name of the interface. Will be determined automatically if not provided. Returns: bool: whether the tensor is in a backpropagation environment or not. **Example** >>> from pennylane import numpy as np >>> x = np.array(0.6, requires_grad=True) >>> in_backprop(x) False >>> def cost(x): ... print(in_backprop(x)) ... return x ** 2 >>> qp.grad(cost)(x) True tensor(1.2, requires_grad=True) .. seealso:: :func:`~.requires_grad` """ interface = interface or math.get_interface(tensor) if interface == "autograd": return isinstance(tensor, ArrayBox) if interface == "jax": return isinstance(tensor, jax.core.Tracer) if interface in {"numpy", "scipy"}: return False raise ValueError(f"Cannot determine if {tensor} is in backpropagation.")
[docs] def ceil_log2(n: numbers.Real) -> int: """Compute the ceiling of the base-2 logarithm of a number, with integer as output data type. Args: n (int or float): Number to compute the rounded-up base-2 logarithm of. Traced inputs must have an integer data type. Returns: int: Rounded-up base-2 logarithm of ``n``. .. warning:: Under just-in-time (JIT) compilation with JAX, this function will not raise an error for the input ``0``: >>> import jax >>> jax.jit(qp.math.ceil_log2)(0) Array(-2147483648, dtype=int32) **Example** On powers of two, ``ceil_log2`` simply acts like ``np.log2`` whose result was converted to an ``int``: >>> qp.math.ceil_log2(8) 3 On other numbers, the rounding of the logarithm becomes visible: >>> qp.math.log2(14) 3.807354922057604 >>> qp.math.ceil_log2(14) 4 Note that we always round up: >>> qp.math.round(qp.math.log2(9)) 3.0 >>> qp.math.ceil_log2(9) 4 The result is exact even for inputs with more significant bits than a float can hold: >>> qp.math.ceil_log2(2**53 + 1) 54 For simple ``int`` inputs, this function computes the same as ``(n - 1).bit_length()``, which does not work for inputs like ``np.int64``. """ if is_tracer(n): # The ceiling exceeds the floor by one unless n is a power of two, which is the # case if and only if n & (n - 1) vanishes return floor_log2(n) + ((n & (n - 1)) != 0) # np.log2 loses precision for inputs with more than 53 significant bits, so that its rounded # result may be off by one. Comparing to the neighbouring powers of two corrects this. exponent = int(np.ceil(np.log2(n))) if (1 << exponent) < n: return exponent + 1 return exponent
[docs] def floor_log2(n: numbers.Real) -> int: """Compute the floor of the base-2 logarithm of a number, with integer as output data type. Args: n (int or float): Number to compute the rounded-down base-2 logarithm of. Traced inputs must have an integer data type. Returns: int: Rounded-down base-2 logarithm of ``n``. .. warning:: Under just-in-time (JIT) compilation with JAX, this function will not raise an error for the input ``0``: >>> import jax >>> jax.jit(qp.math.floor_log2)(0) Array(2147483647, dtype=int32) **Example** On powers of two, ``floor_log2`` simply acts like ``np.log2`` whose result was converted to an ``int``: >>> qp.math.floor_log2(8) 3 On other numbers, the rounding of the logarithm becomes visible: >>> qp.math.log2(14) 3.807354922057604 >>> qp.math.floor_log2(14) 3 Note that we always round down: >>> qp.math.round(qp.math.log2(15)) 4.0 >>> qp.math.floor_log2(15) 3 The result is exact even for inputs with more significant bits than a float can hold: >>> qp.math.floor_log2(2**53 - 1) 52 For simple ``int`` inputs, this function computes the same as ``n.bit_length() - 1``, which does not work for inputs like ``np.int64``. """ # np.log2 loses precision for inputs with more than 53 significant bits, so that its rounded # result may be off by one. Comparing to the neighbouring powers of two corrects this. if is_tracer(n): exponent = np.floor(np.log2(n)).astype(int) # Shifting compares n to 2 ** exponent without forming the power itself, which could # exceed the integer data type shifted = n >> exponent return exponent - (shifted == 0) + (shifted >= 2) exponent = int(np.floor(np.log2(n))) if (1 << (exponent + 1)) <= n: return exponent + 1 if (1 << exponent) > n: return exponent - 1 return exponent