qadence 1.1.0__tar.gz → 1.2.0__tar.gz

{qadence-1.1.0 → qadence-1.2.0}/.github/workflows/test_all.yml

@@ -10,6 +10,7 @@ concurrency:
   group: all-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
+
 jobs:
   test_qadence_ubuntu:
     name: Test Qadence (ubuntu)
@@ -33,3 +34,27 @@ jobs:
     - name: Run tests
       run: |
         hatch -v run test
+
+  test_fast_qadence_windows_mac:
+    name: Test Qadence (Windows, MacOS)
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [macos-latest, windows-latest]
+        python-version: ["3.10"]
+    steps:
+    - name: Checkout Qadence
+      uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install Hatch
+      run: |
+        pip install hatch
+
+    - name: Run tests
+      run: |
+        hatch -v run test -m "not slow"

{qadence-1.1.0 → qadence-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: qadence
-Version: 1.1.0
+Version: 1.2.0
 Summary: Pasqal interface for circuit-based quantum computing SDKs
 Author-email: Aleksander Wennersteen <aleksander.wennersteen@pasqal.com>, Gert-Jan Both <gert-jan.both@pasqal.com>, Niklas Heim <niklas.heim@pasqal.com>, Mario Dagrada <mario.dagrada@pasqal.com>, Vincent Elfving <vincent.elfving@pasqal.com>, Dominik Seitz <dominik.seitz@pasqal.com>, Roland Guichard <roland.guichard@pasqal.com>, "Joao P. Moutinho" <joao.moutinho@pasqal.com>, Vytautas Abramavicius <vytautas.abramavicius@pasqal.com>
 License: Apache 2.0
@@ -19,7 +19,7 @@ Requires-Dist: jsonschema
 Requires-Dist: matplotlib
 Requires-Dist: nevergrad
 Requires-Dist: openfermion
-Requires-Dist: pyqtorch==1.0.1
+Requires-Dist: pyqtorch==1.0.3
 Requires-Dist: rich
 Requires-Dist: scipy
 Requires-Dist: sympytorch>=0.1.2

{qadence-1.1.0 → qadence-1.2.0}/mkdocs.yml

@@ -23,10 +23,9 @@ nav:
     - digital_analog_qc/index.md
     - Basic operations on neutral-atoms: digital_analog_qc/analog-basics.md
     - Fitting a simple function: digital_analog_qc/analog-qcl.md
-    - Hardware efficient ansatz with restricted addressability: digital_analog_qc/rydberg-hea.md
+    - Restricted local addressability: digital_analog_qc/semi-local-addressing.md
     - Pulse-level programming with Pulser: digital_analog_qc/pulser-basic.md
     - Solve a QUBO problem: digital_analog_qc/analog-qubo.md
-    - Pulse-level programming with Pulser: digital_analog_qc/pulser-basic.md
     - CNOT with interacting qubits: digital_analog_qc/daqc-cnot.md
 
   - Variational quantum algorithms:

{qadence-1.1.0 → qadence-1.2.0}/pyproject.toml

@@ -19,7 +19,7 @@ authors = [
 ]
 requires-python = ">=3.9,<3.12"
 license = {text = "Apache 2.0"}
-version = "1.1.0"
+version = "1.2.0"
 classifiers=[
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python",
@@ -40,7 +40,7 @@ dependencies = [
     "jsonschema",
     "nevergrad",
     "scipy",
-    "pyqtorch==1.0.1",
+    "pyqtorch==1.0.3",
     "matplotlib"
 ]
 
@@ -111,11 +111,11 @@ filterwarnings = [
 
 [tool.hatch.envs.docs]
 dependencies = [
-  "mkdocs==1.5.2",
+  "mkdocs",
   "mkdocs-material",
   "mkdocstrings",
   "mkdocstrings-python",
-  "mkdocs-section-index==0.3.6",
+  "mkdocs-section-index",
   "mkdocs-exclude",
   "markdown-exec",
   "mike",

qadence-1.2.0/qadence/analog/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .addressing import AddressingPattern
+from .device import IdealDevice, RealisticDevice, RydbergDevice
+from .parse_analog import add_background_hamiltonian
+
+__all__ = ["RydbergDevice", "IdealDevice", "RealisticDevice", "AddressingPattern"]

qadence-1.2.0/qadence/analog/addressing.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+from typing import Union
+from warnings import warn
+
+from sympy import Expr, Heaviside, exp
+from torch import Tensor, pi
+
+from qadence.parameters import Parameter, evaluate
+
+# FIXME: Clarify the roles of these values in the context
+# device specification and how they relate with the
+# maximum values for delta and omega.
+GLOBAL_MAX_AMPLITUDE = 300
+GLOBAL_MAX_DETUNING = 2 * pi * 2000
+LOCAL_MAX_AMPLITUDE = 3
+LOCAL_MAX_DETUNING = 2 * pi * 20
+
+TWeight = Union[str, float, Tensor, Parameter]
+
+
+def sigmoid(x: Tensor, a: float, b: float) -> Expr:
+    return 1.0 / (1.0 + exp(-a * (x + b)))
+
+
+@dataclass
+class AddressingPattern:
+    """Semi-local addressing pattern."""
+
+    n_qubits: int
+    """Number of qubits in register."""
+
+    weights_amp: dict[int, TWeight]
+    """List of weights for fixed amplitude pattern that cannot be changed during the execution."""
+
+    weights_det: dict[int, TWeight]
+    """List of weights for fixed detuning pattern that cannot be changed during the execution."""
+
+    amp: TWeight = LOCAL_MAX_AMPLITUDE
+    """Maximum amplitude of the amplitude pattern felt by a single qubit."""
+
+    det: TWeight = LOCAL_MAX_DETUNING
+    """Maximum detuning of the detuning pattern felt by a single qubit."""
+
+    def _validate_weights(
+        self,
+        weights: dict[int, TWeight],
+    ) -> None:
+        for v in weights.values():
+            if not isinstance(v, (str, Parameter)):
+                if not (v >= 0.0 and v <= 1.0):
+                    raise ValueError("Addressing pattern weights must sum fall in range [0.0, 1.0]")
+
+    def _constrain_weights(
+        self,
+        weights: dict[int, TWeight],
+    ) -> dict:
+        # augment weight dict if needed
+        weights = {
+            i: Parameter(0.0)
+            if i not in weights
+            else (Parameter(weights[i]) if not isinstance(weights[i], Parameter) else weights[i])
+            for i in range(self.n_qubits)
+        }
+
+        # restrict weights to [0, 1] range - equal to 0 everywhere else
+        weights = {
+            k: v if v.is_number else abs(v * (sigmoid(v, 20, 1) - sigmoid(v, 20.0, -1)))  # type: ignore [union-attr]
+            for k, v in weights.items()
+        }
+
+        return weights
+
+    def _constrain_max_vals(self) -> None:
+        # enforce constraints:
+        # 0 <= amp <= GLOBAL_MAX_AMPLITUDE
+        # 0 <= abs(det) <= GLOBAL_MAX_DETUNING
+        self.amp = abs(
+            self.amp
+            * (
+                Heaviside(self.amp + GLOBAL_MAX_AMPLITUDE)  # type: ignore [operator]
+                - Heaviside(self.amp - GLOBAL_MAX_AMPLITUDE)  # type: ignore [operator]
+            )
+        )
+        self.det = -abs(
+            self.det
+            * (
+                Heaviside(self.det + GLOBAL_MAX_DETUNING)
+                - Heaviside(self.det - GLOBAL_MAX_DETUNING)
+            )
+        )
+
+    def _create_local_constraint(self, val: Expr, weights: dict, max_val: float) -> dict:
+        # enforce local constraints:
+        # amp * w_amp_i < LOCAL_MAX_AMPLITUDE or
+        # abs(det) * w_det_i < LOCAL_MAX_DETUNING
+        local_constr = {k: val * v for k, v in weights.items()}
+        local_constr = {k: Heaviside(v) - Heaviside(v - max_val) for k, v in local_constr.items()}
+
+        return local_constr
+
+    def _create_global_constraint(self, val: Expr, weights: dict, max_val: float) -> Expr:
+        # enforce global constraints:
+        # amp * sum(w_amp_0, w_amp_1, ...) < GLOBAL_MAX_AMPLITUDE or
+        # abs(det) * sum(w_det_0, w_det_1, ...) < GLOBAL_MAX_DETUNING
+        weighted_vals_global = val * sum([v for v in weights.values()])
+        weighted_vals_global = Heaviside(weighted_vals_global) - Heaviside(
+            weighted_vals_global - max_val
+        )
+
+        return weighted_vals_global
+
+    def __post_init__(self) -> None:
+        # validate amplitude/detuning weights
+        self._validate_weights(self.weights_amp)
+        self._validate_weights(self.weights_det)
+
+        # validate maximum global amplitude/detuning values
+        if not isinstance(self.amp, (str, Parameter)):
+            if self.amp > GLOBAL_MAX_AMPLITUDE:
+                warn("Maximum absolute value of amplitude is exceeded")
+        elif isinstance(self.amp, str):
+            self.amp = Parameter(self.amp, trainable=True)
+        if not isinstance(self.det, (str, Parameter)):
+            if abs(self.det) > GLOBAL_MAX_DETUNING:
+                warn("Maximum absolute value of detuning is exceeded")
+        elif isinstance(self.det, str):
+            self.det = Parameter(self.det, trainable=True)
+
+        # constrain amplitude/detuning parameterized weights to [0.0, 1.0] interval
+        self.weights_amp = self._constrain_weights(self.weights_amp)
+        self.weights_det = self._constrain_weights(self.weights_det)
+
+        # constrain max global amplitude and detuning to strict interval
+        self._constrain_max_vals()
+
+        # create additional local and global constraints for amplitude/detuning masks
+        self.local_constr_amp = self._create_local_constraint(
+            self.amp, self.weights_amp, LOCAL_MAX_AMPLITUDE
+        )
+        self.local_constr_det = self._create_local_constraint(
+            -self.det, self.weights_det, LOCAL_MAX_DETUNING
+        )
+        self.global_constr_amp = self._create_global_constraint(
+            self.amp, self.weights_amp, GLOBAL_MAX_AMPLITUDE
+        )
+        self.global_constr_det = self._create_global_constraint(
+            -self.det, self.weights_det, GLOBAL_MAX_DETUNING
+        )
+
+        # validate number of qubits in mask
+        if max(list(self.weights_amp.keys())) >= self.n_qubits:
+            raise ValueError("Amplitude weight specified for non-existing qubit")
+        if max(list(self.weights_det.keys())) >= self.n_qubits:
+            raise ValueError("Detuning weight specified for non-existing qubit")
+
+    def evaluate(self, weights: dict, values: dict) -> dict:
+        # evaluate weight expressions with actual values
+        return {k: evaluate(v, values, as_torch=True).flatten() for k, v in weights.items()}  # type: ignore [union-attr]
+
+    def _to_dict(self) -> dict:
+        return {field.name: getattr(self, field.name) for field in fields(self)}
+
+    @classmethod
+    def _from_dict(cls, d: dict) -> AddressingPattern | None:
+        return cls(**d) if len(d) > 0 else None

qadence-1.2.0/qadence/analog/constants.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+# Ising coupling coefficient depending on the Rydberg level
+# Include a normalization to the Planck constant hbar
+# In units of [rad . µm^6 / µs]
+
+C6_DICT = {
+    50: 96120.72,
+    51: 122241.6,
+    52: 154693.02,
+    53: 194740.36,
+    54: 243973.91,
+    55: 304495.01,
+    56: 378305.98,
+    57: 468027.05,
+    58: 576714.85,
+    59: 707911.38,
+    60: 865723.02,
+    61: 1054903.11,
+    62: 1281042.11,
+    63: 1550531.15,
+    64: 1870621.31,
+    65: 2249728.57,
+    66: 2697498.69,
+    67: 3224987.51,
+    68: 3844734.37,
+    69: 4571053.32,
+    70: 5420158.53,
+    71: 6410399.4,
+    72: 7562637.31,
+    73: 8900342.14,
+    74: 10449989.62,
+    75: 12241414.53,
+    76: 14308028.03,
+    77: 16687329.94,
+    78: 19421333.62,
+    79: 22557029.94,
+    80: 26146720.74,
+    81: 30248886.65,
+    82: 34928448.69,
+    83: 40257623.67,
+    84: 46316557.88,
+    85: 53194043.52,
+    86: 60988354.64,
+    87: 69808179.15,
+    88: 79773468.88,
+    89: 91016513.07,
+    90: 103677784.57,
+    91: 117933293.96,
+    92: 133943541.9,
+    93: 151907135.94,
+    94: 172036137.34,
+    95: 194562889.89,
+    96: 219741590.56,
+    97: 247850178.91,
+    98: 279192193.77,
+    99: 314098829.39,
+    100: 352931119.11,
+}

qadence-1.2.0/qadence/analog/device.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+
+from torch import pi
+
+from qadence.analog import AddressingPattern
+from qadence.types import DeviceType, Interaction
+
+
+@dataclass(frozen=True, eq=True)
+class RydbergDevice:
+    """
+    Dataclass for interacting Rydberg atoms under an Hamiltonian:
+
+    H = ∑_i [Ω/2 * (cos(φ) * Xᵢ - sin(φ) * Yᵢ) - δ * N_i] + H_int,
+
+    where:
+
+    H_int = ∑_(j<i) (C_6 / R**6) * (N_i @ N_j) for the NN interaction;
+
+    H_int = ∑_(j<i) (C_3 / R**3) * ((X_i @ X_j) + (Y_i @ Y_j)) for the XY interaction;
+    """
+
+    interaction: Interaction = Interaction.NN
+    """Defines the interaction Hamiltonian."""
+
+    rydberg_level: int = 60
+    """Rydberg level affecting the value of C_6."""
+
+    coeff_xy: float = 3700.00
+    """Value of C_3."""
+
+    max_detuning: float = 2 * pi * 4
+    """Maximum value of the detuning δ."""
+
+    max_amp: float = 2 * pi * 3
+    """Maximum value of the amplitude Ω."""
+
+    pattern: AddressingPattern | None = None
+    """Semi-local addressing pattern configuration."""
+
+    type: DeviceType = DeviceType.IDEALIZED
+    """DeviceType.IDEALIZED or REALISTIC to convert to the Pulser backend."""
+
+    def __post_init__(self) -> None:
+        # FIXME: Currently not supporting custom interaction functions.
+        if self.interaction not in [Interaction.NN, Interaction.XY]:
+            raise KeyError(
+                "RydbergDevice currently only supports Interaction.NN or Interaction.XY."
+            )
+
+    def _to_dict(self) -> dict:
+        device_dict = {}
+        for field in fields(self):
+            if field.name != "pattern":
+                device_dict[field.name] = getattr(self, field.name)
+            else:
+                device_dict[field.name] = (
+                    self.pattern._to_dict() if self.pattern is not None else {}
+                )
+        return device_dict
+
+    @classmethod
+    def _from_dict(cls, d: dict) -> RydbergDevice:
+        pattern = AddressingPattern._from_dict(d["pattern"])
+        d["pattern"] = pattern
+        return cls(**d)
+
+
+def IdealDevice(pattern: AddressingPattern | None = None) -> RydbergDevice:
+    return RydbergDevice(
+        pattern=pattern,
+        type=DeviceType.IDEALIZED,
+    )
+
+
+def RealisticDevice(pattern: AddressingPattern | None = None) -> RydbergDevice:
+    return RydbergDevice(
+        pattern=pattern,
+        type=DeviceType.REALISTIC,
+    )

qadence-1.2.0/qadence/analog/hamiltonian_terms.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from sympy import cos, sin
+from torch import float64, tensor
+
+from qadence.analog.constants import C6_DICT
+from qadence.blocks import add
+from qadence.blocks.abstract import AbstractBlock
+from qadence.blocks.analog import ConstantAnalogRotation
+from qadence.constructors import hamiltonian_factory
+from qadence.operations import I, N, X, Y, Z
+from qadence.register import Register
+from qadence.types import Interaction
+
+
+def rydberg_interaction_hamiltonian(
+    register: Register,
+) -> AbstractBlock:
+    """
+    Computes the Rydberg Ising or XY interaction Hamiltonian for a register of qubits.
+
+    H_int = ∑_(j<i) (C_6 / R**6) * kron(N_i, N_j)
+
+    H_int = ∑_(j<i) (C_3 / R**3) * (kron(X_i, X_j) + kron(Y_i, Y_j))
+
+    Args:
+        register: the register of qubits.
+    """
+
+    distances = tensor(list(register.distances.values()), dtype=float64)
+    device_specs = register.device_specs
+
+    if device_specs.interaction == Interaction.NN:
+        c6 = C6_DICT[device_specs.rydberg_level]
+        strength_list = c6 / (distances**6)
+    elif device_specs.interaction == Interaction.XY:
+        c3 = device_specs.coeff_xy
+        strength_list = c3 / (distances**3)
+
+    return hamiltonian_factory(
+        register,
+        interaction=device_specs.interaction,
+        interaction_strength=strength_list,
+        use_all_node_pairs=True,
+    )
+
+
+def rydberg_drive_hamiltonian(block: ConstantAnalogRotation, register: Register) -> AbstractBlock:
+    """
+    Computes the Rydberg drive Hamiltonian for some local or global rotation.
+
+    H_d = ∑_i (Ω/2 cos(φ) * X_i - sin(φ) * Y_i) - δ * N_i
+
+    Args:
+        block: the ConstantAnalogRotation block containing the parameters.
+        register: the register of qubits.
+    """
+
+    if block.qubit_support.is_global:
+        qubit_support = tuple(register.nodes)
+    else:
+        qubit_support = block.qubit_support
+
+    omega = block.parameters.omega
+    delta = block.parameters.delta
+    phase = block.parameters.phase
+
+    x_terms = (omega / 2) * add(cos(phase) * X(i) for i in qubit_support)
+    y_terms = (omega / 2) * add(sin(phase) * Y(i) for i in qubit_support)
+    n_terms = delta * add(N(i) for i in qubit_support)
+    h_drive: AbstractBlock = x_terms - y_terms - n_terms
+    return h_drive
+
+
+def rydberg_pattern_hamiltonian(register: Register) -> AbstractBlock | None:
+    support = tuple(range(register.n_qubits))
+    pattern = register.device_specs.pattern
+    if pattern is not None:
+        amp = pattern.amp
+        det = pattern.det
+        weights_amp = pattern.weights_amp
+        weights_det = pattern.weights_det
+        local_constr_amp = pattern.local_constr_amp
+        local_constr_det = pattern.local_constr_det
+        global_constr_amp = pattern.global_constr_amp
+        global_constr_det = pattern.global_constr_det
+
+        p_amp_terms: AbstractBlock = (
+            (1 / 2)  # type: ignore [operator]
+            * amp
+            * global_constr_amp
+            * add(X(i) * weights_amp[i] * local_constr_amp[i] for i in support)  # type: ignore [operator]
+        )
+        p_det_terms: AbstractBlock = (
+            -det  # type: ignore [operator]
+            * global_constr_det
+            * add(0.5 * (I(i) - Z(i)) * weights_det[i] * local_constr_det[i] for i in support)  # type: ignore [operator]
+        )
+        return p_amp_terms + p_det_terms
+    else:
+        return None

qadence-1.2.0/qadence/analog/parse_analog.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from qadence.analog.hamiltonian_terms import (
+    rydberg_drive_hamiltonian,
+    rydberg_interaction_hamiltonian,
+    rydberg_pattern_hamiltonian,
+)
+from qadence.blocks import chain
+from qadence.blocks.abstract import AbstractBlock
+from qadence.blocks.analog import (
+    AnalogKron,
+    ConstantAnalogRotation,
+    WaitBlock,
+)
+from qadence.circuit import QuantumCircuit
+from qadence.operations import HamEvo
+from qadence.register import Register
+from qadence.transpile import apply_fn_to_blocks
+
+
+def add_background_hamiltonian(
+    circuit: QuantumCircuit | AbstractBlock,
+    register: Register | None = None,
+) -> QuantumCircuit | AbstractBlock:
+    """
+    Parses a `QuantumCircuit` to transform `AnalogBlocks` to `HamEvo`.
+
+    Depends on the circuit `Register` and included `RydbergDevice` specifications.
+
+    Currently checks if input is either circuit or block and adjusts
+    the ouput accordingly. Running this function on single blocks is
+    currently used for eigenvalue computation for GPSR.
+
+    Arguments:
+        circuit: the circuit to parse, or single block to transform.
+        register: needed for calling the function on a single block.
+    """
+    # FIXME: revisit eigenvalues of analog blocks and clean this code.
+
+    is_circuit_input = isinstance(circuit, QuantumCircuit)
+
+    if not is_circuit_input and register is None:
+        raise ValueError("Block input requires an input to the `register` argument.")
+
+    input_block: AbstractBlock = circuit.block if is_circuit_input else circuit  # type: ignore
+    input_register: Register = circuit.register if is_circuit_input else register  # type: ignore
+
+    if input_register.device_specs is not None:
+        # Create interaction hamiltonian:
+        h_int = rydberg_interaction_hamiltonian(input_register)
+
+        # Create addressing pattern:
+        h_addr = rydberg_pattern_hamiltonian(input_register)
+
+        output_block = apply_fn_to_blocks(
+            input_block,
+            _analog_to_hevo,
+            input_register,
+            (h_int, h_addr),
+        )
+    else:
+        output_block = input_block
+
+    if is_circuit_input:
+        return QuantumCircuit(input_register, output_block)
+    else:
+        return output_block
+
+
+def _build_ham_evo(
+    block: WaitBlock | ConstantAnalogRotation,
+    h_int: AbstractBlock,
+    h_drive: AbstractBlock | None,
+    h_addr: AbstractBlock | None,
+) -> HamEvo:
+    duration = block.parameters.duration
+    h_block = h_int
+    if h_drive is not None:
+        h_block += h_drive
+    if block.add_pattern and h_addr is not None:
+        h_block += h_addr
+    return HamEvo(h_block, duration / 1000)
+
+
+def _analog_to_hevo(
+    block: AbstractBlock,
+    register: Register,
+    h_terms: tuple[AbstractBlock, AbstractBlock | None],
+) -> AbstractBlock:
+    """
+    Converter from AnalogBlock to the respective HamEvo.
+
+    Any other block not covered by the specific conditions below is left unchanged.
+    """
+
+    h_int, h_addr = h_terms
+
+    if isinstance(block, WaitBlock):
+        return _build_ham_evo(block, h_int, None, h_addr)
+
+    if isinstance(block, ConstantAnalogRotation):
+        h_drive = rydberg_drive_hamiltonian(block, register)
+        return _build_ham_evo(block, h_int, h_drive, h_addr)
+
+    if isinstance(block, AnalogKron):
+        # Needed to ensure kronned Analog blocks are implemented
+        # in sequence, consistent with the current Pulser implementation.
+        # FIXME: Revisit this assumption and the need for AnalogKron to have
+        # the same duration, and clean this code accordingly.
+        # https://github.com/pasqal-io/qadence/issues/226
+        ops = []
+        for block in block.blocks:
+            if isinstance(block, ConstantAnalogRotation):
+                h_drive = rydberg_drive_hamiltonian(block, register)
+                ops.append(_build_ham_evo(block, h_int, h_drive, h_addr))
+        if len(ops) == 0:
+            ops.append(_build_ham_evo(block, h_int, None, h_addr))  # type: ignore [arg-type]
+        return chain(*ops)
+
+    return block

{qadence-1.1.0 → qadence-1.2.0}/qadence/backend.py

@@ -26,6 +26,7 @@ from qadence.mitigations import Mitigations
 from qadence.noise import Noise
 from qadence.parameters import stringify
 from qadence.types import BackendName, DiffMode, Endianness
+from qadence.utils import validate_values_and_state
 
 logger = get_logger(__file__)
 
@@ -255,7 +256,7 @@ class Backend(ABC):
         raise NotImplementedError
 
     @abstractmethod
-    def run(
+    def _run(
         self,
         circuit: ConvertedCircuit,
         param_values: dict[str, Tensor] = {},
@@ -277,6 +278,31 @@ class Backend(ABC):
         """
         raise NotImplementedError
 
+    def run(
+        self,
+        circuit: ConvertedCircuit,
+        param_values: dict[str, Tensor] = {},
+        state: Tensor | None = None,
+        endianness: Endianness = Endianness.BIG,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Tensor:
+        """Run a circuit and return the resulting wave function.
+
+        Arguments:
+            circuit: A converted circuit as returned by `backend.circuit`.
+            param_values: _**Already embedded**_ parameters of the circuit. See
+                [`embedding`][qadence.blocks.embedding.embedding] for more info.
+            state: Initial state.
+            endianness: Endianness of the resulting wavefunction.
+
+        Returns:
+            A list of Counter objects where each key represents a bitstring
+            and its value the number of times it has been sampled from the given wave function.
+        """
+        validate_values_and_state(state, circuit.abstract.n_qubits, param_values)
+        return self._run(circuit, param_values, state, endianness, *args, **kwargs)
+
     @abstractmethod
     def run_dm(
         self,