emu-base 1.2.1__py3-none-any.whl

emu_base/__init__.py

@@ -0,0 +1,47 @@
+from .base_classes.results import Results
+from .base_classes.callback import Callback, AggregationType
+from .base_classes.config import BackendConfig
+from .base_classes.operator import Operator
+from .base_classes.state import State
+from .base_classes.backend import Backend
+from .base_classes.default_callbacks import (
+    BitStrings,
+    CorrelationMatrix,
+    Energy,
+    EnergyVariance,
+    Expectation,
+    Fidelity,
+    QubitDensity,
+    StateResult,
+    SecondMomentOfEnergy,
+)
+from .pulser_adapter import PulserData, HamiltonianType
+from .math.brents_root_finding import find_root_brents
+from .math.krylov_exp import krylov_exp, DEFAULT_MAX_KRYLOV_DIM
+
+__all__ = [
+    "__version__",
+    "Results",
+    "BackendConfig",
+    "Operator",
+    "State",
+    "Backend",
+    "AggregationType",
+    "Callback",
+    "StateResult",
+    "BitStrings",
+    "QubitDensity",
+    "CorrelationMatrix",
+    "Expectation",
+    "Fidelity",
+    "Energy",
+    "EnergyVariance",
+    "SecondMomentOfEnergy",
+    "PulserData",
+    "find_root_brents",
+    "krylov_exp",
+    "HamiltonianType",
+    "DEFAULT_MAX_KRYLOV_DIM",
+]
+
+__version__ = "1.2.1"

emu_base/base_classes/__init__.py

@@ -0,0 +1,31 @@
+from .operator import Operator
+from .state import State
+from .results import Results
+from .callback import Callback
+from .default_callbacks import (
+    StateResult,
+    BitStrings,
+    QubitDensity,
+    CorrelationMatrix,
+    Expectation,
+    Fidelity,
+    Energy,
+    EnergyVariance,
+    SecondMomentOfEnergy,
+)
+
+__all__ = [
+    "Operator",
+    "State",
+    "Results",
+    "Callback",
+    "StateResult",
+    "BitStrings",
+    "QubitDensity",
+    "CorrelationMatrix",
+    "Expectation",
+    "Fidelity",
+    "Energy",
+    "EnergyVariance",
+    "SecondMomentOfEnergy",
+]

emu_base/base_classes/aggregators.py

@@ -0,0 +1,59 @@
+import statistics
+from typing import Any, Callable
+import collections
+from emu_base.base_classes.callback import AggregationType
+
+
+_NUMERIC_TYPES = {int, float, complex}
+
+
+def mean_aggregator(
+    values: list[Any],
+) -> complex | float | list[complex] | list[float] | list[list[complex]] | list[
+    list[float]
+]:  # FIXME: support tuples?
+    if values == []:
+        raise ValueError("Cannot average 0 samples")
+
+    element_type = type(values[0])
+
+    if element_type in _NUMERIC_TYPES:
+        return statistics.fmean(values)
+
+    if element_type != list:
+        raise NotImplementedError("Cannot average this type of data")
+
+    if values[0] == []:
+        raise ValueError("Cannot average list of empty lists")
+
+    sub_element_type = type(values[0][0])
+
+    if sub_element_type in _NUMERIC_TYPES:
+        dim = len(values[0])
+        return [statistics.fmean(value[i] for value in values) for i in range(dim)]
+
+    if sub_element_type != list:  # FIXME: ABC.Iterable? Collection? subclass?
+        raise ValueError(f"Cannot average list of lists of {sub_element_type}")
+
+    if values[0][0] == []:
+        raise ValueError("Cannot average list of matrices with no columns")
+
+    if (sub_sub_element_type := type(values[0][0][0])) not in _NUMERIC_TYPES:
+        raise ValueError(f"Cannot average list of matrices of {sub_sub_element_type}")
+
+    dim1 = len(values[0])
+    dim2 = len(values[0][0])
+    return [
+        [statistics.fmean(value[i][j] for value in values) for j in range(dim2)]
+        for i in range(dim1)
+    ]
+
+
+def bag_union_aggregator(values: list[collections.Counter]) -> collections.Counter:
+    return sum(values, start=collections.Counter())
+
+
+aggregation_types_definitions: dict[AggregationType, Callable] = {
+    AggregationType.MEAN: mean_aggregator,
+    AggregationType.BAG_UNION: bag_union_aggregator,
+}

emu_base/base_classes/backend.py

@@ -0,0 +1,48 @@
+import warnings
+from abc import ABC, abstractmethod
+
+from pulser import Sequence
+
+from emu_base.base_classes.config import BackendConfig
+from emu_base.base_classes.results import Results
+
+
+class Backend(ABC):
+    """
+    Base class for different emulation backends.
+    Forces backends to implement a run method.
+    """
+
+    @staticmethod
+    def validate_sequence(sequence: Sequence) -> None:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", category=DeprecationWarning)
+
+        if not isinstance(sequence, Sequence):
+            raise TypeError(
+                "The provided sequence has to be a valid " "pulser.Sequence instance."
+            )
+        if sequence.is_parametrized() or sequence.is_register_mappable():
+            raise ValueError(
+                "Not supported"
+                "The provided sequence needs to be built to be simulated. Call"
+                " `Sequence.build()` with the necessary parameters."
+            )
+        if not sequence._schedule:
+            raise ValueError("The provided sequence has no declared channels.")
+        if all(sequence._schedule[x][-1].tf == 0 for x in sequence.declared_channels):
+            raise ValueError("No instructions given for the channels in the sequence.")
+
+    @abstractmethod
+    def run(self, sequence: Sequence, config: BackendConfig) -> Results:
+        """
+        Emulates the given sequence.
+
+        Args:
+            sequence: a Pulser sequence to simulate
+            config: the config. Should be of the appropriate type for the backend
+
+        Returns:
+            the simulation results
+        """
+        pass

emu_base/base_classes/callback.py

@@ -0,0 +1,90 @@
+from abc import ABC, abstractmethod
+from typing import Any, Optional, TYPE_CHECKING
+from enum import Enum, auto
+
+from emu_base.base_classes.config import BackendConfig
+from emu_base.base_classes.operator import Operator
+from emu_base.base_classes.state import State
+
+if TYPE_CHECKING:
+    from emu_base.base_classes.results import Results
+
+
+class AggregationType(Enum):
+    """
+    Defines how to combine multiple values from different simulation results.
+    """
+
+    MEAN = auto()  # statistics.fmean or list/matrix-wise equivalent
+    BAG_UNION = auto()  # Counter.__add__
+
+
+class Callback(ABC):
+    def __init__(self, evaluation_times: set[int]):
+        """
+        The callback base class that can be subclassed to add new kinds of results
+        to the Results object returned by the Backend
+
+        Args:
+            evaluation_times: the times at which to add a result to Results
+        """
+        self.evaluation_times = evaluation_times
+
+    def __call__(
+        self, config: BackendConfig, t: int, state: State, H: Operator, result: "Results"
+    ) -> None:
+        """
+        This function is called after each time step performed by the emulator.
+        By default it calls apply to compute a result and put it in `result`
+        if `t` in `self.evaluation_times`.
+        It can be overloaded to define any custom behaviour for a `Callback`.
+
+        Args:
+            config: the config object passed to the run method
+            t: the current time in ns
+            state: the current state
+            H: the Hamiltonian at this time
+            result: the results object
+        """
+        if t in self.evaluation_times:
+            value_to_store = self.apply(config, t, state, H)
+            result.store(callback=self, time=t, value=value_to_store)
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """
+        The name of the observable, can be used to index into the Results object.
+        Some Callbacks might have multiple instances, such as a callback to compute
+        a fidelity on some given state. In that case, this method could make sure
+        each instance has a unique name.
+
+        Returns:
+            the name of the callback
+        """
+        pass
+
+    @abstractmethod
+    def apply(self, config: BackendConfig, t: int, state: State, H: Operator) -> Any:
+        """
+        This method must be implemented by subclasses. The result of this method
+        gets put in the Results object.
+
+        Args:
+            config: the config object passed to the run method
+            t: the current time in ns
+            state: the current state
+            H: the Hamiltonian at this time
+
+        Returns:
+            the result to put in Results
+        """
+        pass
+
+    @property
+    def default_aggregation_type(self) -> Optional[AggregationType]:
+        """
+        Defines how to combine by default multiple values from different simulation results.
+        None means no default, therefore aggregator function is always user-provided.
+        """
+        return None

emu_base/base_classes/config.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+from pulser.noise_model import NoiseModel
+import logging
+import sys
+import pathlib
+
+
+class BackendConfig:
+    """The base backend configuration.
+
+    Args:
+        observables: a list of callbacks to compute observables
+        with_modulation: if True, run the sequence with hardware modulation
+        noise_model: The pulser.NoiseModel to use in the simulation.
+        interaction_matrix: When specified, override the interaction terms in the Hamiltonian.
+            This corresponds to the $U_{ij}$ terms in the documentation. Must be symmetric.
+        interaction_cutoff: set interaction coefficients smaller than this to 0.
+            This can improve the memory profile of the application for some backends.
+        log_level: The output verbosity. Should be one of the constants from logging.
+        log_file: a path to a file where to store the log, instead of printing to stdout
+
+    Examples:
+        >>> observables = [BitStrings(400, 100)] #compute 100 bitstrings at 400ns
+        >>> noise_model = pulser.noise_model.NoiseModel()
+        >>> interaction_matrix = [[1 for _ in range(nqubits)] for _ in range(nqubits)]
+        >>> interaction_cutoff = 2.0 #this will turn off all the above interactions again
+        >>> log_level = logging.warn
+    """
+
+    def __init__(
+        self,
+        *,
+        # "Callback" is a forward type reference because of the circular import otherwise.
+        observables: list["Callback"] | None = None,  # type: ignore # noqa: F821
+        with_modulation: bool = False,
+        noise_model: NoiseModel = None,
+        interaction_matrix: list[list[float]] | None = None,
+        interaction_cutoff: float = 0.0,
+        log_level: int = logging.INFO,
+        log_file: pathlib.Path | None = None,
+    ):
+        if observables is None:
+            observables = []
+        self.callbacks = (
+            observables  # we can add other types of callbacks, and just stack them
+        )
+        self.with_modulation = with_modulation
+        self.noise_model = noise_model
+
+        if interaction_matrix is not None and (
+            not isinstance(interaction_matrix, list)
+            or not isinstance(interaction_matrix[0], list)
+        ):
+            raise ValueError(
+                "Interaction matrix must be provided as a Python list of lists of floats"
+            )
+
+        self.interaction_matrix = interaction_matrix
+        self.interaction_cutoff = interaction_cutoff
+        self.logger = logging.getLogger("global_logger")
+        if log_file is None:
+            logging.basicConfig(
+                level=log_level, format="%(message)s", stream=sys.stdout, force=True
+            )  # default to stream = sys.stderr
+        else:
+            logging.basicConfig(
+                level=log_level,
+                format="%(message)s",
+                filename=str(log_file),
+                filemode="w",
+                force=True,
+            )
+        if noise_model is not None and (
+            noise_model.runs != 1
+            or noise_model.samples_per_run != 1
+            or noise_model.runs is not None
+            or noise_model.samples_per_run is not None
+        ):
+            self.logger.warning(
+                "Warning: The runs and samples_per_run values of the NoiseModel are ignored!"
+            )

emu_base/base_classes/default_callbacks.py

@@ -0,0 +1,300 @@
+from copy import deepcopy
+from typing import Any
+
+from emu_base.base_classes.callback import Callback, AggregationType
+from emu_base.base_classes.config import BackendConfig
+from emu_base.base_classes.operator import Operator
+from emu_base.base_classes.state import State
+
+
+class StateResult(Callback):
+    """
+    Store the quantum state in whatever format the backend provides
+
+    Args:
+        evaluation_times: the times at which to store the state
+    """
+
+    def __init__(self, evaluation_times: set[int]):
+        super().__init__(evaluation_times)
+
+    name = "state"
+
+    def apply(self, config: BackendConfig, t: int, state: State, H: Operator) -> Any:
+        return deepcopy(state)
+
+
+class BitStrings(Callback):
+    """
+    Store bitstrings sampled from the current state. Error rates are taken from the config
+    passed to the run method of the backend. The bitstrings are stored as a Counter[str].
+
+    Args:
+        evaluation_times: the times at which to sample bitstrings
+        num_shots: how many bitstrings to sample each time this observable is computed
+    """
+
+    def __init__(self, evaluation_times: set[int], num_shots: int = 1000):
+        super().__init__(evaluation_times)
+        self.num_shots = num_shots
+
+    name = "bitstrings"
+
+    def apply(self, config: BackendConfig, t: int, state: State, H: Operator) -> Any:
+        p_false_pos = (
+            0.0 if config.noise_model is None else config.noise_model.p_false_pos
+        )
+        p_false_neg = (
+            0.0 if config.noise_model is None else config.noise_model.p_false_neg
+        )
+
+        return state.sample(self.num_shots, p_false_pos, p_false_neg)
+
+    default_aggregation_type = AggregationType.BAG_UNION
+
+
+_fidelity_counter = -1
+
+
+class Fidelity(Callback):
+    """
+    Store $<ψ|φ(t)>$ for the given state $|ψ>$,
+    and the state $|φ(t)>$ obtained by time evolution.
+
+    Args:
+        evaluation_times: the times at which to compute the fidelity
+        state: the state |ψ>. Note that this must be of appropriate type for the backend
+
+    Examples:
+        >>> state = State.from_state_string(...) #see State API
+        >>> fidelity = Fidelity([400], state) #measure fidelity on state at t=400ns
+    """
+
+    def __init__(self, evaluation_times: set[int], state: State):
+        super().__init__(evaluation_times)
+        global _fidelity_counter
+        _fidelity_counter += 1
+        self.index = _fidelity_counter
+        self.state = state
+
+    @property
+    def name(self) -> str:
+        return f"fidelity_{self.index}"
+
+    def apply(self, config: BackendConfig, t: int, state: State, H: Operator) -> Any:
+        return self.state.inner(state)
+
+
+_expectation_counter = -1
+
+
+class Expectation(Callback):
+    """
+    Store the expectation of the given operator on the current state
+    (i.e. $\\langle φ(t)|\\mathrm{operator}|φ(t)\\rangle$).
+
+    Args:
+        evaluation_times: the times at which to compute the expectation
+        operator: the operator to measure. Must be of appropriate type for the backend.
+
+    Examples:
+        >>> op = Operator.from_operator_string(...) #see Operator API
+        >>> expectation = Expectation([400], op) #measure the expecation of op at t=400ns
+    """
+
+    def __init__(self, evaluation_times: set[int], operator: Operator):
+        super().__init__(evaluation_times)
+        global _expectation_counter
+        _expectation_counter += 1
+        self.index = _expectation_counter
+        self.operator = operator
+
+    @property
+    def name(self) -> str:
+        return f"expectation_{self.index}"
+
+    def apply(self, config: BackendConfig, t: int, state: State, H: Operator) -> Any:
+        return self.operator.expect(state)
+
+    default_aggregation_type = AggregationType.MEAN
+
+
+class CorrelationMatrix(Callback):
+    """
+    Store the correlation matrix for the current state.
+    Requires specification of the basis used in the emulation
+    https://pulser.readthedocs.io/en/stable/conventions.html
+    It currently supports
+    - the rydberg basis ('r','g')
+    - the xy basis ('0', '1')
+    and returns
+
+    `[[<φ(t)|n_i n_j|φ(t)> for j in qubits] for i in qubits]`
+
+    n_i being the operator that projects qubit i onto the state that measures as 1.
+    The diagonal of this matrix is the QubitDensity. The correlation matrix
+    is stored as a list of lists.
+
+    Args:
+        evaluation_times: the times at which to compute the correlation matrix
+        basis: the basis used by the sequence
+        nqubits: the number of qubits in the Register
+
+    Notes:
+        See the API for `Operator.from_operator_string` for an example of what to do with
+        basis and nqubits.
+    """
+
+    def __init__(self, evaluation_times: set[int], basis: tuple[str, ...], nqubits: int):
+        super().__init__(evaluation_times)
+        self.operators: list[list[Operator]] | None = None
+        self.basis = set(basis)
+        if self.basis == {"r", "g"}:
+            self.op_string = "rr"
+        elif self.basis == {"0", "1"}:
+            self.op_string = "11"
+        else:
+            raise ValueError("Unsupported basis provided")
+        self.nqubits = nqubits
+
+    name = "correlation_matrix"
+
+    def apply(self, config: BackendConfig, t: int, state: State, H: Operator) -> Any:
+        if hasattr(state, "get_correlation_matrix") and callable(
+            state.get_correlation_matrix
+        ):
+            return state.get_correlation_matrix()
+
+        if self.operators is None or not isinstance(self.operators[0], type(H)):
+            self.operators = [
+                [
+                    H.from_operator_string(
+                        self.basis,
+                        self.nqubits,
+                        [(1.0, [({self.op_string: 1.0}, list({i, j}))])],
+                    )
+                    for j in range(self.nqubits)
+                ]
+                for i in range(self.nqubits)
+            ]
+        return [[op.expect(state).real for op in ops] for ops in self.operators]
+
+    default_aggregation_type = AggregationType.MEAN
+
+
+class QubitDensity(Callback):
+    """
+    Requires specification of the basis used in the emulation
+    https://pulser.readthedocs.io/en/stable/conventions.html
+    It currently supports
+    - the rydberg basis ('r','g')
+    - the xy basis ('0', '1')
+    and returns
+
+    `[<φ(t)|n_i|φ(t)> for i in qubits]`
+
+    n_i being the operator that projects qubit i onto the state that measures as 1.
+    The qubit density is stored as a list.
+
+    Args:
+        evaluation_times: the times at which to compute the density
+        basis: the basis used by the sequence
+        nqubits: the number of qubits in the Register
+
+    Notes:
+        See the API for `State.from_state_string` for an example of what to do with
+        basis and nqubits.
+    """
+
+    def __init__(self, evaluation_times: set[int], basis: tuple[str, ...], nqubits: int):
+        super().__init__(evaluation_times)
+        self.operators: list[Operator] | None = None
+        self.basis = set(basis)
+        if self.basis == {"r", "g"}:
+            self.op_string = "rr"
+        elif self.basis == {"0", "1"}:
+            self.op_string = "11"
+        else:
+            raise ValueError("Unsupported basis provided")
+        self.nqubits = nqubits
+
+    name = "qubit_density"
+
+    def apply(self, config: BackendConfig, t: int, state: State, H: Operator) -> Any:
+        if self.operators is None or not isinstance(self.operators[0], type(H)):
+            self.operators = [
+                H.from_operator_string(
+                    self.basis, self.nqubits, [(1.0, [({self.op_string: 1.0}, [i])])]
+                )
+                for i in range(self.nqubits)
+            ]
+        return [op.expect(state).real for op in self.operators]
+
+    default_aggregation_type = AggregationType.MEAN
+
+
+class Energy(Callback):
+    """
+    Store the expectation value of the current Hamiltonian
+    (i.e. $\\langle φ(t)|H(t)|φ(t) \\rangle$)
+
+    Args:
+        evaluation_times: the times at which to compute the expectation
+    """
+
+    def __init__(self, evaluation_times: set[int]):
+        super().__init__(evaluation_times)
+
+    name = "energy"
+
+    def apply(self, config: BackendConfig, t: int, state: State, H: Operator) -> Any:
+        return H.expect(state).real
+
+    default_aggregation_type = AggregationType.MEAN
+
+
+class EnergyVariance(Callback):
+    """
+    Store the variance of the current Hamiltonian
+    (i.e. $\\langle φ(t)|H(t)^2|φ(t)\\rangle - \\langle φ(t)|H(t)|φ(t)\\rangle^2$)
+
+    Args:
+        evaluation_times: the times at which to compute the variance
+    """
+
+    def __init__(self, evaluation_times: set[int]):
+        super().__init__(evaluation_times)
+
+    name = "energy_variance"
+
+    def apply(self, config: BackendConfig, t: int, state: State, H: Operator) -> Any:
+        h_squared = H @ H
+        return h_squared.expect(state).real - H.expect(state).real ** 2
+
+    # Explicitely setting this to None out of safety: in the case of MonteCarlo,
+    # the aggregated variance cannot be computed from this callback.
+    # Instead, one first need to average Energy and SecondMomentOfEnergy,
+    # and then compute the variance with the formula:
+    # AggregatedEnergyVariance = AveragedSecondMomentOfEnergy - AveragedEnergy**2
+    default_aggregation_type = None
+
+
+class SecondMomentOfEnergy(Callback):
+    """
+    Store the expectation value $\\langle φ(t)|H(t)^2|φ(t)\\rangle$.
+    Useful for computing the variance when averaging over many executions of the program.
+
+    Args:
+        evaluation_times: the times at which to compute the variance
+    """
+
+    def __init__(self, evaluation_times: set[int]):
+        super().__init__(evaluation_times)
+
+    name = "second_moment_of_energy"
+
+    def apply(self, config: BackendConfig, t: int, state: State, H: Operator) -> Any:
+        h_squared = H @ H
+        return h_squared.expect(state).real
+
+    default_aggregation_type = AggregationType.MEAN