emu-base 1.2.1__py3-none-any.whl

emu_base/base_classes/operator.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Iterable
+
+from emu_base.base_classes.state import State
+
+
+QuditOp = dict[str, complex]  # single qubit operator
+TensorOp = list[tuple[QuditOp, list[int]]]  # QuditOp applied to list of qubits
+FullOp = list[tuple[complex, TensorOp]]  # weighted sum of TensorOp
+
+
+class Operator(ABC):
+    @abstractmethod
+    def __mul__(self, other: State) -> State:
+        """
+        Apply the operator to a state
+
+        Args:
+            other: the state to apply this operator to
+
+        Returns:
+            the resulting state
+        """
+        pass
+
+    @abstractmethod
+    def __add__(self, other: Operator) -> Operator:
+        """
+        Computes the sum of two operators.
+
+        Args:
+            other: the other operator
+
+        Returns:
+           the summed operator
+        """
+        pass
+
+    @abstractmethod
+    def expect(self, state: State) -> float | complex:
+        """
+        Compute the expectation value of self on the given state.
+
+        Args:
+            state: the state with which to compute
+
+        Returns:
+            the expectation
+        """
+
+    @staticmethod
+    @abstractmethod
+    def from_operator_string(
+        basis: Iterable[str],
+        nqubits: int,
+        operations: FullOp,
+        operators: dict[str, QuditOp] = {},
+        /,
+        **kwargs: Any,
+    ) -> Operator:
+        """
+        Create an operator in the backend-specific format from the
+        pulser abstract representation
+        <https://www.notion.so/pasqal/Abstract-State-and-Operator-Definition>
+        By default it supports strings 'ij', where i and j in basis,
+        to denote |i><j|, but additional symbols can be defined in operators
+        For a list of existing bases, see
+        <https://pulser.readthedocs.io/en/stable/conventions.html>
+
+        Args:
+            basis: the eigenstates in the basis to use
+            nqubits: how many qubits there are in the state
+            operations: which bitstrings make up the state with what weight
+            operators: additional symbols to be used in operations
+
+        Returns:
+            the operator in whatever format the backend provides.
+
+        Examples:
+            >>> basis = {"r", "g"} #rydberg basis
+            >>> nqubits = 3 #or whatever
+            >>> x = {"rg": 1.0, "gr": 1.0}
+            >>> z = {"gg": 1.0, "rr": -1.0}
+            >>> operators = {"X": x, "Z": z} #define X and Z as conveniences
+            >>>
+            >>> operations = [ # 4 X1X + 3 1Z1
+            >>>     (
+            >>>         1.0,
+            >>>         [
+            >>>             ({"X": 2.0}, [0, 2]),
+            >>>             ({"Z": 3.0}, [1]),
+            >>>         ],
+            >>>     )
+            >>> ]
+            >>> op = Operator.from_operator_string(basis, nqubits, operations, operators)
+        """
+        pass
+
+    @abstractmethod
+    def __rmul__(self, scalar: complex) -> Operator:
+        """
+        Scale the operator by a scale factor.
+
+        Args:
+            scalar: the scale factor
+
+        Returns:
+            the scaled operator
+        """
+        pass
+
+    @abstractmethod
+    def __matmul__(self, other: Operator) -> Operator:
+        """
+        Compose two operators. The ordering is that
+        self is applied after other.
+
+        Args:
+            other: the operator to compose with self
+
+        Returns:
+            the composed operator
+        """
+        pass

emu_base/base_classes/results.py

@@ -0,0 +1,174 @@
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+from pathlib import Path
+import json
+import logging
+
+from emu_base.base_classes.callback import Callback, AggregationType
+from emu_base.base_classes.aggregators import aggregation_types_definitions
+
+
+@dataclass
+class Results:
+    """
+    This class contains emulation results. Since the results written by
+    an emulator are defined through callbacks, the contents of this class
+    are not known a-priori.
+    """
+
+    statistics: Any = None  # Backend-specific data
+
+    _results: dict[str, dict[int, Any]] = field(default_factory=dict)
+    _default_aggregation_types: dict[str, Optional[AggregationType]] = field(
+        default_factory=dict
+    )
+
+    @classmethod
+    def aggregate(
+        cls,
+        results_to_aggregate: list["Results"],
+        **aggregator_functions: Callable[[Any], Any],
+    ) -> "Results":
+        if len(results_to_aggregate) == 0:
+            raise ValueError("no results to aggregate")
+
+        if len(results_to_aggregate) == 1:
+            return results_to_aggregate[0]
+
+        stored_callbacks = set(results_to_aggregate[0].get_result_names())
+
+        if not all(
+            set(results.get_result_names()) == stored_callbacks
+            for results in results_to_aggregate
+        ):
+            raise ValueError(
+                "Monte-Carlo results seem to provide from incompatible simulations: "
+                "they do not all contain the same observables"
+            )
+
+        aggregated: Results = cls()
+
+        for stored_callback in stored_callbacks:
+            aggregation_type = aggregator_functions.get(
+                stored_callback,
+                results_to_aggregate[0].get_aggregation_type(stored_callback),
+            )
+
+            if aggregation_type is None:
+                logging.getLogger("global_logger").warning(
+                    f"Skipping aggregation of `{stored_callback}`"
+                )
+                continue
+
+            aggregation_function: Any = (
+                aggregation_type
+                if callable(aggregation_type)
+                else aggregation_types_definitions[aggregation_type]
+            )
+
+            evaluation_times = results_to_aggregate[0].get_result_times(stored_callback)
+            if not all(
+                results.get_result_times(stored_callback) == evaluation_times
+                for results in results_to_aggregate
+            ):
+                raise ValueError(
+                    "Monte-Carlo results seem to provide from incompatible simulations: "
+                    "the callbacks are not stored at the same times"
+                )
+
+            aggregated._results[stored_callback] = {
+                t: aggregation_function(
+                    [result[stored_callback, t] for result in results_to_aggregate]
+                )
+                for t in evaluation_times
+            }
+
+        return aggregated
+
+    def store(self, *, callback: Callback, time: Any, value: Any) -> None:
+        self._results.setdefault(callback.name, {})
+
+        if time in self._results[callback.name]:
+            raise ValueError(
+                f"A value is already stored for observable '{callback.name}' at time {time}"
+            )
+
+        self._results[callback.name][time] = value
+        self._default_aggregation_types[callback.name] = callback.default_aggregation_type
+
+    def __getitem__(self, key: Any) -> Any:
+        if isinstance(key, tuple):
+            # results["energy", t]
+            callback_name, time = key
+
+            if callback_name not in self._results:
+                raise ValueError(
+                    f"No value for observable '{callback_name}' has been stored"
+                )
+
+            if time not in self._results[callback_name]:
+                raise ValueError(
+                    f"No value stored at time {time} for observable '{callback_name}'"
+                )
+
+            return self._results[callback_name][time]
+
+        # results["energy"][t]
+        assert isinstance(key, str)
+        callback_name = key
+        if callback_name not in self._results:
+            raise ValueError(f"No value for observable '{callback_name}' has been stored")
+
+        return self._results[key]
+
+    def get_result_names(self) -> list[str]:
+        """
+        get a list of results present in this object
+
+        Args:
+
+        Returns:
+            list of results by name
+
+        """
+        return list(self._results.keys())
+
+    def get_result_times(self, name: str) -> list[int]:
+        """
+        get a list of times for which the given result has been stored
+
+        Args:
+            name: name of the result to get times of
+
+        Returns:
+            list of times in ns
+
+        """
+        return list(self._results[name].keys())
+
+    def get_result(self, name: str, time: int) -> Any:
+        """
+        get the given result at the given time
+
+        Args:
+            name: name of the result to get
+            time: time in ns at which to get the result
+
+        Returns:
+            the result
+
+        """
+        return self._results[name][time]
+
+    def get_aggregation_type(self, name: str) -> Optional[AggregationType]:
+        return self._default_aggregation_types[name]
+
+    def dump(self, file_path: Path) -> None:
+        with file_path.open("w") as file_handle:
+            json.dump(
+                {
+                    "observables": self._results,
+                    "statistics": self.statistics,
+                },
+                file_handle,
+            )

emu_base/base_classes/state.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+from typing import Any, Iterable
+from abc import ABC, abstractmethod
+from collections import Counter
+
+
+class State(ABC):
+    """
+    Base class enforcing an API for quantum states.
+    Each backend will implement its own type of state, and the
+    below methods.
+    """
+
+    @abstractmethod
+    def inner(self, other: State) -> float | complex:
+        """
+        Compute the inner product between this state and other.
+        Note that self is the left state in the inner product,
+        so this function is linear in other, and anti-linear in self
+
+        Args:
+            other: the other state
+
+        Returns:
+            inner product
+        """
+        pass
+
+    @abstractmethod
+    def sample(
+        self, num_shots: int, p_false_pos: float = 0.0, p_false_neg: float = 0.0
+    ) -> Counter[str]:
+        """
+        Sample bitstrings from the state, taking into account error rates.
+
+        Args:
+            num_shots: how many bitstrings to sample
+            p_false_pos: the rate at which a 0 is read as a 1
+            p_false_neg: the rate at which a 1 is read as a 0
+
+        Returns:
+            the measured bitstrings, by count
+        """
+        pass
+
+    @abstractmethod
+    def __add__(self, other: State) -> State:
+        """
+        Computes the sum of two states.
+
+        Args:
+            other: the other state
+
+        Returns:
+            the summed state
+        """
+        pass
+
+    @abstractmethod
+    def __rmul__(self, scalar: complex) -> State:
+        """
+        Scale the state by a scale factor.
+
+        Args:
+            scalar: the scale factor
+
+        Returns:
+            the scaled state
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def from_state_string(
+        *, basis: Iterable[str], nqubits: int, strings: dict[str, complex], **kwargs: Any
+    ) -> State:
+        """
+        Construct a state from the pulser abstract representation
+        <https://www.notion.so/pasqal/Abstract-State-and-Operator-Definition>
+        For a list of existing bases, see
+        <https://pulser.readthedocs.io/en/stable/conventions.html>
+
+        Args:
+            basis: A tuple containing the basis states.
+            nqubits: the number of qubits.
+            strings: A dictionary mapping state strings to complex or floats amplitudes
+
+        Returns:
+            the state in whatever format the backend provides.
+
+        Examples:
+            >>> afm_string_state = {"rrr": 1.0 / math.sqrt(2), "ggg": 1.0 / math.sqrt(2)}
+            >>> afm_state = State.from_state_string(
+            >>>     basis=("r", "g"), nqubits=3, strings=afm_string_state
+            >>> )
+        """
+        pass

emu_base/lindblad_operators.py

@@ -0,0 +1,44 @@
+from pulser.noise_model import NoiseModel
+import torch
+import math
+
+
+def get_lindblad_operators(
+    *, noise_type: str, noise_model: NoiseModel
+) -> list[torch.Tensor]:
+    assert noise_type in noise_model.noise_types
+
+    if noise_type == "relaxation":
+        c = math.sqrt(noise_model.relaxation_rate)
+        return [
+            torch.tensor([[0, c], [0, 0]], dtype=torch.complex128),
+        ]
+
+    if noise_type == "dephasing":
+        if noise_model.hyperfine_dephasing_rate != 0.0:
+            raise NotImplementedError("hyperfine_dephasing_rate is unsupported")
+
+        c = math.sqrt(noise_model.dephasing_rate / 2)
+        return [
+            torch.tensor([[-c, 0], [0, c]], dtype=torch.complex128),
+        ]
+
+    if noise_type == "depolarizing":
+        c = math.sqrt(noise_model.depolarizing_rate / 4)
+        return [
+            torch.tensor([[0, c], [c, 0]], dtype=torch.complex128),
+            torch.tensor([[0, 1j * c], [-1j * c, 0]], dtype=torch.complex128),
+            torch.tensor([[-c, 0], [0, c]], dtype=torch.complex128),
+        ]
+
+    if noise_type == "eff_noise":
+        if not all(op.shape == (2, 2) for op in noise_model.eff_noise_opers):
+            raise ValueError("Only 2 * 2 effective noise operator matrices are supported")
+
+        return [
+            math.sqrt(rate)
+            * torch.flip(op if isinstance(op, torch.Tensor) else torch.tensor(op), (0, 1))
+            for rate, op in zip(noise_model.eff_noise_rates, noise_model.eff_noise_opers)
+        ]
+
+    raise ValueError(f"Unknown noise type: {noise_type}")

emu_base/math/__init__.py

@@ -0,0 +1,3 @@
+from .krylov_exp import krylov_exp, krylov_exp_impl
+
+__all__ = ["krylov_exp", "krylov_exp_impl"]

emu_base/math/brents_root_finding.py

@@ -0,0 +1,121 @@
+from typing import Callable, Optional
+
+
+class BrentsRootFinder:
+    def __init__(
+        self,
+        *,
+        start: float,
+        end: float,
+        f_start: float,
+        f_end: float,
+        epsilon: float = 1e-6,
+    ):
+        self.epsilon = epsilon
+
+        assert start <= end
+        self.a, self.b = start, end
+        self.fa = f_start
+        self.fb = f_end
+
+        assert self.fa * self.fb < 0, "Function root needs to be between a and b"
+
+        # b has to be the better guess
+        if abs(self.fa) < abs(self.fb):
+            self.a, self.b = self.b, self.a
+            self.fa, self.fb = self.fb, self.fa
+
+        self.c = self.a
+        self.d = self.c
+        self.fc = self.fa
+
+        self.bisection = True
+        self.current_guess = self.b
+        self.next_abscissa: Optional[float] = None
+
+    def get_next_abscissa(self) -> float:
+        if abs(self.fc - self.fa) < self.epsilon or abs(self.fc - self.fb) < self.epsilon:
+            # Secant method
+            dx = self.fb * (self.b - self.a) / (self.fa - self.fb)
+        else:
+            # Inverse quadratic interpolation
+            s = self.fb / self.fa
+            r = self.fb / self.fc
+            t = self.fa / self.fc
+            q = (t - 1) * (s - 1) * (r - 1)
+            p = s * (t * (r - t) * (self.c - self.b) + (r - 1) * (self.b - self.a))
+            dx = p / q
+
+        # Use bisection instead of interpolation
+        # if the interpolation is not within bounds.
+        delta = abs(2 * self.epsilon * self.b)
+        adx = abs(dx)
+        delta_bc = abs(self.b - self.c)
+        delta_cd = abs(self.c - self.d)
+        delta_ab = self.a - self.b
+        if (
+            (adx >= abs(3 * delta_ab / 4) or dx * delta_ab < 0)
+            or (self.bisection and adx >= delta_bc / 2)
+            or (not self.bisection and adx >= delta_cd / 2)
+            or (self.bisection and delta_bc < delta)
+            or (not self.bisection and delta_cd < delta)
+        ):
+            dx = (self.a - self.b) / 2
+            self.bisection = True
+        else:
+            self.bisection = False
+
+        self.next_abscissa = self.b + dx
+        self.d = self.c
+        self.c, self.fc = self.b, self.fb
+
+        return self.next_abscissa
+
+    def provide_ordinate(self, abscissa: float, ordinate: float) -> None:
+        # First argument is just a safety
+        assert (
+            self.next_abscissa is not None and abscissa == self.next_abscissa
+        ), "Something went wrong"
+
+        # Update interval
+        if self.fa * ordinate < 0:
+            self.b, self.fb = abscissa, ordinate
+        else:
+            self.a, self.fa = abscissa, ordinate
+
+        # b has to be the better guess
+        if abs(self.fa) < abs(self.fb):
+            self.a, self.b = self.b, self.a
+            self.fa, self.fb = self.fb, self.fa
+
+        self.current_guess = self.b
+
+    def is_converged(self, tolerance: float) -> bool:
+        return abs(self.b - self.a) < tolerance
+
+
+def find_root_brents(
+    f: Callable[[float], float],
+    *,
+    start: float,
+    end: float,
+    f_start: Optional[float] = None,
+    f_end: Optional[float] = None,
+    tolerance: float = 1e-6,
+    epsilon: float = 1e-6,
+) -> float:
+    """
+    Approximates and returns the zero of a scalar function using Brent's method.
+    """
+    f_start = f_start if f_start is not None else f(start)
+    f_end = f_end if f_end is not None else f(end)
+
+    root_finder = BrentsRootFinder(
+        start=start, end=end, f_start=f_start, f_end=f_end, epsilon=epsilon
+    )
+
+    while not root_finder.is_converged(tolerance):
+        x = root_finder.get_next_abscissa()
+        root_finder.provide_ordinate(x, f(x))
+
+    return root_finder.current_guess

emu_base/math/krylov_exp.py

@@ -0,0 +1,127 @@
+from typing import Callable
+import torch
+
+DEFAULT_MAX_KRYLOV_DIM: int = 100
+
+
+class KrylovExpResult:
+    def __init__(
+        self,
+        result: torch.Tensor,
+        converged: bool,
+        happy_breakdown: bool,
+        iteration_count: int,
+    ):
+        assert (not happy_breakdown) or converged
+
+        self.converged = converged
+        self.happy_breakdown = happy_breakdown
+        self.iteration_count = iteration_count
+        self.result = result
+
+
+def krylov_exp_impl(
+    op: Callable,
+    v: torch.Tensor,
+    is_hermitian: bool,  # note: complex-proportional to its adjoint is enough
+    exp_tolerance: float,
+    norm_tolerance: float,
+    max_krylov_dim: int = DEFAULT_MAX_KRYLOV_DIM,
+) -> KrylovExpResult:
+    """
+    Computes exp(op).v using either the Lanczos or Arnoldi algorithm,
+    based on the `is_hermitian` flag.
+    All inputs must be on the same device.
+
+    Convergence is checked using the exponential of the "extended T matrix", a criterion
+    described in "Expokit: A Software Package for Computing Matrix Exponentials"
+    (https://www.maths.uq.edu.au/expokit/paper.pdf).
+    """
+
+    initial_norm = v.norm()
+
+    lanczos_vectors = [v / initial_norm]
+    T = torch.zeros(max_krylov_dim + 2, max_krylov_dim + 2, dtype=v.dtype)
+
+    for j in range(max_krylov_dim):
+        w = op(lanczos_vectors[-1])
+
+        n = w.norm()
+
+        k_start = max(0, j - 1) if is_hermitian else 0
+        for k in range(k_start, j + 1):
+            overlap = torch.tensordot(lanczos_vectors[k].conj(), w, dims=w.dim())
+            T[k, j] = overlap
+            w = w - overlap * lanczos_vectors[k]
+
+        n2 = w.norm()
+        T[j + 1, j] = n2
+
+        if n2 < norm_tolerance:
+            # Happy breakdown
+            expd = torch.linalg.matrix_exp(T[: j + 1, : j + 1])
+            result = initial_norm * sum(
+                a * b for a, b in zip(expd[:, 0], lanczos_vectors)
+            )
+            return KrylovExpResult(
+                result=result, converged=True, happy_breakdown=True, iteration_count=j + 1
+            )
+
+        lanczos_vectors.append(w / n2)
+
+        # Compute exponential of extended T matrix
+        T[j + 2, j + 1] = 1
+        expd = torch.linalg.matrix_exp(T[: j + 3, : j + 3])
+
+        # Local truncation error estimation
+        err1 = abs(expd[j + 1, 0])
+        err2 = abs(expd[j + 2, 0] * n)
+
+        err = err1 if err1 < err2 else (err1 * err2 / (err1 - err2))
+
+        if err < exp_tolerance:
+            # Converged
+            result = initial_norm * sum(
+                a * b for a, b in zip(expd[: len(lanczos_vectors), 0], lanczos_vectors)
+            )
+            return KrylovExpResult(
+                result=result,
+                converged=True,
+                happy_breakdown=False,
+                iteration_count=j + 1,
+            )
+
+    result = initial_norm * sum(
+        a * b for a, b in zip(expd[: len(lanczos_vectors), 0], lanczos_vectors)
+    )
+    return KrylovExpResult(
+        result=result,
+        converged=False,
+        happy_breakdown=False,
+        iteration_count=max_krylov_dim,
+    )
+
+
+def krylov_exp(
+    op: torch.Tensor,
+    v: torch.Tensor,
+    exp_tolerance: float,
+    norm_tolerance: float,
+    is_hermitian: bool = True,  # note: complex-proportional to its adjoint is enough
+    max_krylov_dim: int = DEFAULT_MAX_KRYLOV_DIM,
+) -> torch.Tensor:
+    krylov_result = krylov_exp_impl(
+        op,
+        v,
+        is_hermitian=is_hermitian,
+        exp_tolerance=exp_tolerance,
+        norm_tolerance=norm_tolerance,
+        max_krylov_dim=max_krylov_dim,
+    )
+
+    if not krylov_result.converged:
+        raise RecursionError(
+            "exponentiation algorithm did not converge to precision in allotted number of steps."
+        )
+
+    return krylov_result.result