Gradient-Free Noise Characterization

docs/examples/characterizer_example.md

@@ -0,0 +1,140 @@
+# Characterizer example
+
+This document contains the example script `characterizer_example.py` converted to Markdown. It shows how to set up a simple Ising Hamiltonian, generate a reference trajectory with a given noise model, build a LossClass and Characterizer, and run the optimizer.
+
+## Requirements
+
+- numpy
+- mqt.yaqs package (propagation, optimization, characterizer, core.data_structures)
+- A working environment where PropagatorWithGradients can run (the example uses the package's propagator)
+
+## Usage
+
+Copy the Python code block below into a `.py` file and run it, or execute the cells if using a notebook.
+
+```python
+import numpy as np
+from pathlib import Path
+
+from mqt.yaqs.noise_char.propagation import PropagatorWithGradients
+from mqt.yaqs.noise_char.optimization import LossClass
+from mqt.yaqs.noise_char.characterizer import Characterizer
+
+from mqt.yaqs.core.data_structures.networks import MPO, MPS
+from mqt.yaqs.core.data_structures.noise_model import CompactNoiseModel
+from mqt.yaqs.core.data_structures.simulation_parameters import (
+    AnalogSimParams,
+    Observable,
+)
+from mqt.yaqs.core.libraries.gate_library import X, Y, Z, Create, Destroy
+
+if __name__ == "__main__":
+    work_dir = "test/scikit_characterizer/"
+    work_dir_path = Path(work_dir)
+    work_dir_path.mkdir(parents=True, exist_ok=True)
+
+    # Defining Hamiltonian and observable list
+    L = 2
+    J = 1
+    g = 0.5
+
+    H_0 = MPO()
+    H_0.init_ising(L, J, g)
+
+    # Define the initial state
+    init_state = MPS(L, state="zeros")
+
+    obs_list = [Observable(X(), site) for site in range(L)]
+
+    noise_operator = "pauli_y"
+
+    # Defining simulation parameters
+    T = 3
+    dt = 0.1
+    N = 1000
+    max_bond_dim = 8
+    threshold = 1e-6
+    order = 1
+
+    sim_params = AnalogSimParams(
+        observables=obs_list,
+        elapsed_time=T,
+        dt=dt,
+        num_traj=N,
+        max_bond_dim=max_bond_dim,
+        threshold=threshold,
+        order=order,
+        sample_timesteps=True,
+    )
+
+    # Defining reference noise model and reference trajectory
+    gamma_reference = 0.1
+
+    ref_noise_model = CompactNoiseModel(
+        [
+            {
+                "name": noise_operator,
+                "sites": [i for i in range(L)],
+                "strength": gamma_reference,
+            }
+        ]
+    )
+
+    # Write reference gammas to file
+    np.savetxt(
+        work_dir + "gammas.txt", ref_noise_model.strength_list, header="##", fmt="%.6f"
+    )
+
+    propagator = PropagatorWithGradients(
+        sim_params=sim_params,
+        hamiltonian=H_0,
+        compact_noise_model=ref_noise_model,
+        init_state=init_state,
+    )
+
+    propagator.set_observable_list(obs_list)
+
+    print("Computing reference trajectory ... ")
+    propagator.run(ref_noise_model)
+    ref_traj = propagator.obs_traj
+    print("Reference trajectory computed.")
+
+    # Optimizing the model
+    gamma_guess = 0.4
+
+    sim_params.num_traj = (
+        300  # Reducing the number of trajectories for the optimization
+    )
+
+    guess_noise_model = CompactNoiseModel(
+        [
+            {
+                "name": noise_operator,
+                "sites": [i for i in range(L)],
+                "strength": gamma_guess,
+            }
+        ]
+    )
+
+    opt_propagator = PropagatorWithGradients(
+        sim_params=sim_params,
+        hamiltonian=H_0,
+        compact_noise_model=guess_noise_model,
+        init_state=init_state,
+    )
+
+    loss = LossClass(
+        ref_traj=ref_traj,
+        traj_gradients=opt_propagator,
+        working_dir=work_dir,
+        print_to_file=True,
+    )
+
+    characterizer = Characterizer(
+        traj_gradients=opt_propagator, init_guess=guess_noise_model, loss=loss
+    )
+
+    print("Optimizing ... ")
+    characterizer.adam_optimize(max_iterations=50)
+    print("Optimization completed.")
+```

noxfile.py

@@ -30,7 +30,7 @@
 nox.options.default_venv_backend = "uv"
 
 
-PYTHON_ALL_VERSIONS = ["3.10", "3.11", "3.12", "3.13", "3.14"]
+PYTHON_ALL_VERSIONS = ["3.10", "3.11", "3.12"]
 
 if os.environ.get("CI", None):
     nox.options.error_on_missing_interpreters = True

pyproject.toml

@@ -29,8 +29,6 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-    "Programming Language :: Python :: 3.14",
     "Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)",
     "Typing :: Typed",
 ]
@@ -49,6 +47,16 @@ dependencies = [
     "qiskit>=1.3.0; python_version >= '3.13'",
     "opt-einsum>=3.4.0",
     "tqdm>=4.67.1",
+    "cma>=4.0.0",
+
+    "torch>=2.1.0; python_version < '3.12'",
+    "torch>=2.4.0; python_version >= '3.12' and python_version < '3.13'",
+
+
+    "botorch>=0.16.0; python_version < '3.13'",
+    "gpytorch>=1.14.2; python_version < '3.13'",
+    "pyro-ppl>=1.9.0; python_version < '3.13'",
+
     "threadpoolctl>=3.1.0",
     "numba>=0.61.0",
     "numba>=0.63.0; python_version >= '3.14'",

src/mqt/yaqs/core/data_structures/noise_model.py

@@ -23,6 +23,7 @@
 import numpy as np
 from scipy.stats import truncnorm
 
+from ..libraries.gate_library import GateLibrary
 from ..libraries.noise_library import NoiseLibrary
 
 if TYPE_CHECKING:
@@ -262,3 +263,89 @@ def get_operator(name: str) -> NDArray[np.complex128]:
 
         operator: BaseGate = operator_class()
         return operator.matrix
+
+
+class CompactNoiseModel:
+    """A class to represent a compact noise model with multi-site noise processes."""
+
+    def __init__(self, compact_processes: list[dict[str, Any]] | None = None) -> None:
+        """Initialize the compact noise model.
+
+        Parameters.
+        ----------
+        compact_processes : list[dict[str, Any]] | None, optional
+            A list of compact noise process specifications or None. Each process dict
+            must contain the following keys:
+              - "name" (str): name of a noise process available from GateLibrary.
+              - "sites" (iterable[int]): indices of sites the compact process acts on.
+              - "strength" (numeric): strength/amplitude of the noise process.
+        Behavior
+        --------
+        - If compact_processes is provided, a deep copy is stored in
+          self.compact_processes to avoid external mutation; otherwise an empty list
+          is used.
+        - Each process dict is validated:
+            - Must contain the keys "name", "sites", and "strength".
+            - The GateLibrary entry for the given "name" must exist and represent a
+              1-site interaction (GateLibrary.<name>().interaction == 1).
+          Violations raise AssertionError or ValueError.
+        - The compact processes are expanded into single-site process entries:
+            - For each site in a compact process, an expanded dict
+              {"name": name, "sites": [site], "strength": strength} is appended to
+              self.expanded_processes.
+            - For each expanded entry, the index of the originating compact process
+              is appended to self.index_list.
+        - A NoiseModel is created from the expanded processes and stored as
+          self.expanded_noise_model.
+        Attributes set
+        --------------
+        self.compact_processes : list[dict[str, Any]]
+            Deep-copied list of compact process definitions (or empty list).
+        self.expanded_processes : list[dict[str, Any]]
+            List of per-site expanded process dictionaries.
+        self.index_list : list[int]
+            Mapping from each expanded process to the index of its original compact
+            process in self.compact_processes.
+        self.expanded_noise_model : NoiseModel
+            NoiseModel constructed from self.expanded_processes.
+        self.strength_list : np.ndarray
+            Array of strengths corresponding to each compact process.
+
+        Raises:
+        ------
+        ValueError: If the named gate is not found in GateLibrary. The exception message is:
+                    "Gate '<name>' not found in GateLibrary".
+
+        Notes:
+        -----
+        - This initializer assumes GateLibrary and NoiseModel are available in the
+          surrounding module scope.
+        - The method performs input validation and expansion to ensure downstream
+          code can work with single-site noise process descriptions.
+        """
+        self.compact_processes: list[dict[str, Any]] = (
+            copy.deepcopy(compact_processes) if compact_processes is not None else []
+        )
+
+        self.expanded_processes: list[dict[str, Any]] = []
+
+        self.index_list: list[int] = []
+
+        for i, proc in enumerate(self.compact_processes):
+            assert "name" in proc, "Each process must have a 'name' key"
+            name = proc["name"]
+            if not hasattr(GateLibrary, name):
+                msg = f"Gate '{name}' not found in GateLibrary"
+                raise ValueError(msg)
+            msg = "Only 1-site noise processes are supported in CompactNoiseModel"
+            assert getattr(GateLibrary, name)().interaction == 1, msg
+            assert "sites" in proc, "Each process must have a 'sites' key"
+            assert "strength" in proc, "Each process must have a 'strength' key"
+
+            for site in proc["sites"]:
+                self.expanded_processes.append({"name": proc["name"], "sites": [site], "strength": proc["strength"]})
+                self.index_list.append(i)
+
+        self.strength_list: np.ndarray = np.array([proc["strength"] for proc in self.compact_processes])
+
+        self.expanded_noise_model: NoiseModel = NoiseModel(self.expanded_processes)

src/mqt/yaqs/core/libraries/gate_library.py

@@ -351,6 +351,15 @@ def id(cls) -> Id:
         """
         return Id()
 
+    @classmethod
+    def zero(cls) -> Zero:
+        """Returns the Zero gate.
+
+        Returns:
+            Zero: An instance of the Zero gate.
+        """
+        return Zero()
+
     @classmethod
     def sx(cls) -> SX:
         """Returns the SX gate.
@@ -780,6 +789,28 @@ def __init__(self) -> None:
         super().__init__(mat)
 
 
+class Zero(BaseGate):
+    """Class representing the Zero gate.
+
+    Attributes:
+        name: The name of the gate ("zero").
+        matrix: The 2x2 zero matrix.
+        interaction: The interaction level (1 for single-qubit gates).
+        tensor: The tensor representation of the gate (same as the matrix).
+
+    Methods:
+        set_sites(*sites: int) -> None:
+            Sets the site(s) where the gate is applied.
+    """
+
+    name = "zero"
+
+    def __init__(self) -> None:
+        """Initializes the Zero gate."""
+        mat = np.array([[0, 0], [0, 0]])
+        super().__init__(mat)
+
+
 class SX(BaseGate):
     """Class representing the square-root X (SX) gate.
 
@@ -1739,3 +1770,11 @@ class GateLibrary:
     schmidt_spectrum = SchmidtSpectrum
 
     custom = BaseGate
+    zero = Zero
+
+    # Added aliases to be compatible with naming conventions in noise models
+    raising = Create
+    lowering = Destroy
+    pauli_z = Z
+    pauli_x = X
+    pauli_y = Y

src/mqt/yaqs/noise_char/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (c) 2025 - 2026 Chair for Design Automation, TUM
+# All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+#
+# Licensed under the MIT License
+
+"""This module contains the optimization routines for noise characterization."""