Source code for pennylane.labs.trotter_error.abstract
# Copyright 2026 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.
"""The abstract Fragment class that defines the API for Trotter error computations"""
from __future__ import annotations
from abc import ABC, abstractmethod
from collections.abc import Sequence
class _AdditiveIdentity:
"""Only used to initialize accumulators for summing Fragments"""
def __add__(self, other):
return other
def __radd__(self, other):
return other
[docs]
class Fragment(ABC):
r"""Abstract class used to define a fragment object for product formula error estimation.
For Trotter error, a Hamiltonian is expressed a sum of fragments :math:`H = \sum H_i`.
A :class:`~.Fragment` is an object that has a well-defined notion of a commutator. To ensure
the existence of commutators, the implementation requires the following arithmetic dunder
methods:
* :meth:`~.__add__`: implements addition
* :meth:`~.__mul__`: implements multiplication
* :meth:`~.__matmul__`: implements matrix multiplication
In addition to the arithmetic operators, a ``norm`` method should be defined. The norm is
required to compute error estimates of Trotter error operators.
"""
@abstractmethod
def __add__(self, other: Fragment) -> Fragment:
raise NotImplementedError
def __sub__(self, other: Fragment) -> Fragment:
return self + (-1) * other
@abstractmethod
def __mul__(self, scalar: float) -> Fragment:
raise NotImplementedError
@abstractmethod
def __matmul__(self, other: Fragment) -> Fragment:
raise NotImplementedError
[docs]
def commutator(self, other: Fragment) -> Fragment:
"""Evaluates the commutator :math:`[A, B] = AB - BA` of two fragments"""
return self @ other - other @ self
[docs]
@abstractmethod
def apply(self, state: TrotterState) -> TrotterState:
r"""For a fragment :math:`H` and state :math:`|\psi\rangle` return the state :math:`H|\psi\rangle`
The type of ``state`` is determined by the implementation of :math:`H` as a ``Fragment`` object.
Implementation of this function is mandatory for :func:`~.pennylane.labs.trotter_error.perturbation_error`.
Args:
state (TrotterState): an object representing a quantum state
Returns:
TrotterState: the result of applying the ``Fragment`` to ``state``
"""
raise NotImplementedError
[docs]
def expectation(self, left: TrotterState, right: TrotterState) -> float:
"""Return the expectation value of a state. The type of ``state`` is determined by each
class inheriting from ``Fragment``.
Args:
left (TrotterState): the state to be multiplied on the left of the ``Fragment``
right (TrotterState): the state to be multiplied on the right of the ``Fragment``
Returns:
float: the expectation value obtained by applying ``Fragment`` to the given states
"""
return left.dot(self.apply(right))
[docs]
def initialize_parallel_job(self, backend: str):
"""Set up required for parallel compatibility. This method is called in
:func:`~.pennylane.labs.trotter_error.perturbation_error` before the parallel computations
are called. Any required setup for parallel jobs goes into this function."""
[docs]
def start_parallel_job(self, state: TrotterState):
"""Start perturbation error computation in parallel. This method is the first operation called
in each parallel job dispatched by :func:`~.pennylane.labs.trotter_error.perturbation_error`.
Anything necessary to start the parallel job (such as reading from disk memory) goes into this
function."""
def commutator(a: Fragment, b: Fragment) -> Fragment:
"""Return the commutator of two :class:`~.Fragment` objects
Args:
a (Fragment): the :class:`~.Fragment` on the left side of the commutator
b (Fragment): the :class:`~.Fragment` on the right side of the commutator
Returns:
Fragment: the commutator ``[a, b]``
"""
return a @ b - b @ a
def nested_commutator(fragments: Sequence[Fragment]) -> Fragment:
"""Return the nested commutator of a sequence of :class:`~.Fragment` objects
Args:
fragments (Sequence[Fragment]): a sequence of fragments
Returns:
Fragment: the nested commutator of the fragments
"""
if len(fragments) == 0:
return []
if len(fragments) == 1:
if isinstance(fragments[0], Sequence):
return nested_commutator(fragments[0])
return fragments[0]
head, *tail = fragments
if isinstance(head, Sequence):
return commutator(nested_commutator(head), nested_commutator(tail))
return commutator(head, nested_commutator(tail))
[docs]
class TrotterState(ABC):
"""Abstract class used to define a state object for perturbation error estimation.
A class inheriting from ``TrotterState`` must implement the following dunder methods.
* ``__add__``: implements addition
* ``__mul__``: implements multiplication
Additionally, it requires the following methods.
* ``zero_state``: returns a representation of the zero state
* ``dot``: implements the dot product of two states
"""
@abstractmethod
def __add__(self, other: TrotterState) -> TrotterState:
raise NotImplementedError
def __sub__(self, other: TrotterState) -> TrotterState:
return self + (-1) * other
@abstractmethod
def __mul__(self, scalar: float) -> TrotterState:
raise NotImplementedError
[docs]
@abstractmethod
def dot(self, other: TrotterState) -> float:
"""Compute the dot product of two states.
Args:
other (TrotterState): the state to take the dot product with
Returns:
float: the dot product of self and other
"""
raise NotImplementedError
[docs]
def initialize_parallel_job(self, backend: str):
"""Set up required for parallel compatibility. This method is called in
:func:`~.pennylane.labs.trotter_error.perturbation_error` before the parallel computations
are called. Any required setup for parallel jobs goes into this function."""
[docs]
def start_parallel_job(self, backend: str):
"""Start perturbation error computation in parallel. This method is the first operation called
in each parallel job dispatched by :func:`~.pennylane.labs.trotter_error.perturbation_error`.
Anything necessary to start the parallel job (such as reading from disk memory) goes into this
function."""
_modules/pennylane/labs/trotter_error/abstract