qilisdk 0.1.6__py3-none-any.whl → 0.1.7__py3-none-any.whl

qilisdk/digital/circuit_transpiler_passes/decompose_multi_controlled_gates_pass.py

@@ -0,0 +1,216 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# 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.
+
+import math
+from typing import List
+
+from qilisdk.digital import RX, RY, RZ, U1, U2, U3, Circuit, Gate, H, I, S, T, X, Y, Z
+from qilisdk.digital.gates import BasicGate, Controlled
+
+from .circuit_transpiler_pass import CircuitTranspilerPass
+from .numeric_helpers import (
+    _unitary_sqrt_2x2,
+    _zyz_from_unitary,
+)
+
+
+class DecomposeMultiControlledGatesPass(CircuitTranspilerPass):
+    """Decompose multi-controlled (k >= 2) single-qubit gates.
+
+    The construction follows Lemma 7.5 from Barenco et al., *Elementary Gates for Quantum Computation*,
+    recursively replacing a k-controlled unitary with five layers of (k-1)-controlled operations built
+    from sqrt(U), its adjoint, and multi-controlled Pauli-X gates.
+    """
+
+    def run(self, circuit: Circuit) -> Circuit:
+        """Rewrite the circuit while decomposing multi-controlled gates.
+
+        Args:
+            circuit (Circuit): Circuit whose gates should be rewritten.
+        Returns:
+            Circuit: Newly built circuit containing only supported primitives.
+        """
+        out = Circuit(circuit.nqubits)
+        for g in circuit.gates:
+            for h in self._rewrite_gate(g):
+                out.add(h)
+
+        return out
+
+    def _rewrite_gate(self, gate: Gate) -> List[Gate]:  # noqa: PLR6301
+        """Expand unsupported gates into equivalent elementary gates.
+
+        Args:
+            gate (Gate): Candidate gate potentially containing multiple controls.
+        Returns:
+            list[Gate]: Sequence of equivalent gates that rely on supported primitives.
+        """
+        # --- Multi-controlled gates ---
+        if isinstance(gate, Controlled):
+            base: BasicGate = gate.basic_gate
+            if base.nqubits != 1:
+                raise NotImplementedError("Controlled version of multi-qubit gates is not supported.")
+
+            return _decompose(gate)
+
+        # Everything else is untouched.
+        return [gate]
+
+
+def _decompose(gate: Controlled) -> List[Gate]:
+    """Recursively decompose a multi-controlled single-qubit gate.
+
+    Args:
+        gate (Controlled): Controlled gate whose target operation is single-qubit.
+    Returns:
+        list[Gate]: Gate sequence computing the same unitary as `gate`.
+    """
+    if len(gate.control_qubits) == 1:
+        return [gate]
+
+    c_last = gate.control_qubits[-1]
+    rest = gate.control_qubits[:-1]
+
+    V = _sqrt_of(gate.basic_gate)
+    Vd = _adjoint_of(V)
+
+    seq: List[Gate] = []
+    seq += _decompose(Controlled(c_last, basic_gate=V))
+    seq += _decompose(X(c_last).controlled(*rest))
+    seq += _decompose(Controlled(c_last, basic_gate=Vd))
+    seq += _decompose(X(c_last).controlled(*rest))
+    seq += _decompose(Controlled(*rest, basic_gate=V))
+
+    return seq
+
+
+def _sqrt_of(gate: BasicGate) -> BasicGate:
+    """Return a gate V whose square equals the provided gate.
+
+    Args:
+        gate (BasicGate): Single-qubit gate to compute the principal square root for.
+    Returns:
+        BasicGate: New primitive V that satisfies V · V ≡ gate.
+    """
+    q = gate.qubits[0]
+
+    # Identity: sqrt(I) = I
+    if isinstance(gate, I):
+        return I(q)
+
+    # Direct parametric rotations.
+    if isinstance(gate, RZ):
+        return RZ(q, phi=gate.phi / 2.0)
+    if isinstance(gate, RX):
+        return RX(q, theta=gate.theta / 2.0)
+    if isinstance(gate, RY):
+        return RY(q, theta=gate.theta / 2.0)
+
+    # Pauli gates via half-angle rotations.
+    if isinstance(gate, Z):
+        return RZ(q, phi=math.pi / 2.0)
+    if isinstance(gate, X):
+        return RX(q, theta=math.pi / 2.0)
+    if isinstance(gate, Y):
+        return RY(q, theta=math.pi / 2.0)
+
+    # Phase gate U1(phi) = diag(1, e^{iphi}), sqrt is U1(phi/2).
+    if isinstance(gate, U1):
+        return RZ(q, phi=gate.phi / 2.0)
+
+    # S and T: phase gates with known relation to RZ
+    # S = RZ(pi/2) ⇒ sqrt(S) = RZ(pi/4) ≡ T
+    if isinstance(gate, S):
+        return T(q)
+
+    # T = RZ(pi/4) ⇒ sqrt(T) = RZ(pi/8)
+    if isinstance(gate, T):
+        return RZ(q, phi=math.pi / 8.0)
+
+    # Build the 2x2 unitary matrix for gate
+    if isinstance(gate, (U2, U3, H, BasicGate)):
+        U = gate.matrix
+    else:
+        raise NotImplementedError(f"_sqrt_1q_gate_as_basis only supports 1-qubit gates; got {type(gate).__name__}")
+
+    # Compute a matrix square root V such that V @ V ≈ U.
+    Vs = _unitary_sqrt_2x2(U)
+
+    # Express V as a U3 on the same qubit. This introduces a new gate in U3 form
+    # for the *square root*, but leaves the original g untouched.
+    th, ph, lam = _zyz_from_unitary(Vs)
+    return U3(q, theta=th, phi=ph, gamma=lam)
+
+
+def _adjoint_of(gate: BasicGate) -> BasicGate:
+    """Return the single-qubit adjoint (inverse) of a gate.
+
+    Args:
+        gate (BasicGate): Gate whose inverse should be produced.
+    Returns:
+        BasicGate: Gate that when composed with `gate` yields the identity.
+    """
+    q = gate.qubits[0]
+
+    # Identity: self-adjoint.
+    if isinstance(gate, I):
+        return I(q)
+
+    # Pauli & Hadamard: self-adjoint.
+    if isinstance(gate, X):
+        return X(q)
+    if isinstance(gate, Y):
+        return Y(q)
+    if isinstance(gate, Z):
+        return Z(q)
+    if isinstance(gate, H):
+        return H(q)
+
+    if isinstance(gate, RX):
+        return RX(q, theta=-gate.theta)
+    if isinstance(gate, RY):
+        return RY(q, theta=-gate.theta)
+    if isinstance(gate, RZ):
+        return RZ(q, phi=-gate.phi)
+
+    if isinstance(gate, U1):
+        # U1(gamma)† = U1(-gamma)
+        return RZ(q, phi=-gate.phi)
+    if isinstance(gate, U2):
+        # U2(phi, gamma)† = U3(pi/2, phi, gamma)† = U3(-pi/2, -phi, -gamma)
+        return U3(q, theta=-math.pi / 2.0, phi=-gate.gamma, gamma=-gate.phi)
+    if isinstance(gate, U3):
+        # U3(theta, phi, gamma)† = U3(-theta, -gamma, -phi)
+        return U3(q, theta=-gate.theta, phi=-gate.gamma, gamma=-gate.phi)
+
+    # S, T: phase gates about Z.
+    # S = RZ(pi/2)  ⇒ S† = RZ(-pi/2)
+    if isinstance(gate, S):
+        return RZ(q, phi=-math.pi / 2.0)
+
+    # T = RZ(pi/4)  ⇒ T† = RZ(-pi/4)
+    if isinstance(gate, T):
+        return RZ(q, phi=-math.pi / 4.0)
+
+    # ---------- Generic 1-qubit unitary via matrix adjoint ----------
+
+    if isinstance(gate, BasicGate) and gate.nqubits == 1:
+        U = gate.matrix
+    else:
+        raise NotImplementedError(f"_adjoint_1q only supports 1-qubit gates; got {type(gate).__name__}")
+
+    # Take the matrix adjoint U† and convert to ZYZ → U3.
+    U_dag = U.conj().T
+    theta, phi, gamma = _zyz_from_unitary(U_dag)
+    return U3(q, theta=theta, phi=phi, gamma=gamma)

qilisdk/digital/circuit_transpiler_passes/numeric_helpers.py

@@ -0,0 +1,82 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# 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.
+import math
+
+import numpy as np
+
+# ======================= numeric helpers =======================
+
+_EPS = 1e-12
+_SIG_DECIMALS = 12
+
+
+def _wrap_angle(a: float) -> float:
+    """Wrap an angle to the (-pi, pi] range.
+
+    Args:
+        a (float): Angle value in radians.
+    Returns:
+        float: Angle mapped into the open-closed interval (-pi, pi].
+    """
+    a = (a + math.pi) % (2.0 * math.pi) - math.pi
+    if a <= -math.pi:
+        a = math.pi
+    return a
+
+
+def _zyz_from_unitary(U: np.ndarray) -> tuple[float, float, float]:
+    """Recover ZYZ Euler angles from a 2x2 unitary.
+
+    Args:
+        U (np.ndarray): 2x2 unitary matrix.
+    Returns:
+        tuple[float, float, float]: Tuple containing theta, phi and gamma angles.
+    Raises:
+        ValueError: If matrix is not 2x2.
+    """
+    if U.shape != (2, 2):
+        raise ValueError("Expected 2x2 unitary for ZYZ decomposition.")
+    det = np.linalg.det(U)
+    if abs(det) < _EPS:
+        raise ValueError("Matrix is singular.")
+    # remove phase to a U3 rotation
+    phase = np.angle(U[0, 0])
+    U /= np.exp(1j * phase, dtype=complex)
+
+    a00, a01 = U[0, 0], U[0, 1]
+    a10, a11 = U[1, 0], U[1, 1]
+    theta = 2.0 * math.atan2(np.abs(a01), np.abs(a00))
+    s = math.sin(theta / 2.0)
+
+    if s < _EPS:
+        lam = _wrap_angle(np.angle(a11))
+        return (0.0, 0.0, lam)
+
+    phi = _wrap_angle(np.angle(a10))
+    lam = _wrap_angle(np.angle(-a01))
+    return (theta, phi, lam)
+
+
+def _unitary_sqrt_2x2(U: np.ndarray) -> np.ndarray:
+    """Compute the principal square root of a 2x2 unitary.
+
+    Args:
+        U (np.ndarray): 2x2 unitary matrix.
+    Returns:
+        np.ndarray: Matrix V such that V · V equals U.
+    """
+    w, V = np.linalg.eig(U)
+    ph = np.angle(w)
+    sqrt_w = np.exp(0.5j * ph)
+    return V @ np.diag(sqrt_w) @ np.linalg.inv(V)

qilisdk/digital/gates.py

@@ -212,13 +212,23 @@ class BasicGate(Gate):
     Represents a quantum gate that can be used in quantum circuits.
     """
 
-    def __init__(self, target_qubits: tuple[int, ...], parameters: dict[str, Parameter] = {}) -> None:
+    def __init__(self, target_qubits: tuple[int, ...], parameters: dict[str, Parameter] | None = None) -> None:
+        """Build a basic gate.
+
+        Args:
+            target_qubits (tuple[int, ...]): Qubit indices the gate acts on. Duplicate indices are rejected.
+            parameters (dict[str, Parameter] | None): Optional parameter objects keyed by label for parameterized gates.
+
+        Raises:
+            ValueError: if duplicate target qubits are found.
+        """
         # Check for duplicate integers in target_qubits.
+        super(BasicGate, self).__init__()
         if len(target_qubits) != len(set(target_qubits)):
             raise ValueError("Duplicate target qubits found.")
 
         self._target_qubits: tuple[int, ...] = target_qubits
-        self._parameters: dict[str, Parameter] = parameters
+        self._parameters: dict[str, Parameter] = parameters or {}
         self._matrix: np.ndarray = self._generate_matrix()
 
     @property

qilisdk/{speqtrum/experiments → experiments}/__init__.py

@@ -11,8 +11,15 @@
 # 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.
-from .experiment_functional import ExperimentFunctional, RabiExperiment, T1Experiment
-from .experiment_result import Dimension, ExperimentResult, RabiExperimentResult, T1ExperimentResult
+from .experiment_functional import ExperimentFunctional, RabiExperiment, T1Experiment, T2Experiment, TwoTonesExperiment
+from .experiment_result import (
+    Dimension,
+    ExperimentResult,
+    RabiExperimentResult,
+    T1ExperimentResult,
+    T2ExperimentResult,
+    TwoTonesExperimentResult,
+)
 
 __all__ = [
     "Dimension",
@@ -22,4 +29,8 @@ __all__ = [
     "RabiExperimentResult",
     "T1Experiment",
     "T1ExperimentResult",
+    "T2Experiment",
+    "T2ExperimentResult",
+    "TwoTonesExperiment",
+    "TwoTonesExperimentResult",
 ]

qilisdk/{speqtrum/experiments → experiments}/experiment_functional.py

@@ -16,12 +16,14 @@ from __future__ import annotations
 from abc import ABC
 from typing import TYPE_CHECKING, ClassVar, Generic, TypeVar
 
-from qilisdk.functionals.functional import Functional
-from qilisdk.speqtrum.experiments.experiment_result import (
+from qilisdk.experiments.experiment_result import (
     ExperimentResult,
     RabiExperimentResult,
     T1ExperimentResult,
+    T2ExperimentResult,
+    TwoTonesExperimentResult,
 )
+from qilisdk.functionals.functional import Functional
 from qilisdk.yaml import yaml
 
 if TYPE_CHECKING:
@@ -122,3 +124,89 @@ class T1Experiment(ExperimentFunctional[T1ExperimentResult]):
             np.ndarray: The set of delay durations (in nanoseconds) used in the T1 experiment.
         """
         return self._wait_duration_values
+
+
+@yaml.register_class
+class T2Experiment(ExperimentFunctional[T2ExperimentResult]):
+    """T2 dephasing experiment functional for a single qubit.
+
+    This functional defines a Ramsey/spin-echo style T2 experiment, where
+    the free-evolution delay between phase-sensitive pulses is swept to
+    extract the qubit coherence time.
+    """
+
+    result_type: ClassVar[type[T2ExperimentResult]] = T2ExperimentResult
+    """Result type returned by this functional."""
+
+    def __init__(self, qubit: int, wait_duration_values: np.ndarray) -> None:
+        """Initialize a T2 dephasing experiment functional.
+
+        Args:
+            qubit (int): The physical qubit index on which the experiment is performed.
+            wait_duration_values (np.ndarray): Array of free-evolution delays
+                (in nanoseconds) between the phase-sensitive pulses.
+        """
+        super().__init__(qubit=qubit)
+        self._wait_duration_values: np.ndarray = wait_duration_values
+
+    @property
+    def wait_duration_values(self) -> np.ndarray:
+        """Free-evolution delay sweep values.
+
+        Returns:
+            np.ndarray: The set of delay durations (in nanoseconds) used to estimate T2.
+        """
+        return self._wait_duration_values
+
+
+@yaml.register_class
+class TwoTonesExperiment(ExperimentFunctional[TwoTonesExperimentResult]):
+    """Two-tone spectroscopy functional for a single qubit.
+
+    Sweeps a drive tone frequency while monitoring the readout tone to
+    identify the qubit transition frequency.
+    """
+
+    result_type: ClassVar[type[TwoTonesExperimentResult]] = TwoTonesExperimentResult
+    """Result type returned by this functional."""
+
+    def __init__(self, qubit: int, frequency_start: float, frequency_stop: float, frequency_step: float) -> None:
+        """Initialize a two-tone spectroscopy functional.
+
+        Args:
+            qubit (int): The physical qubit index on which the experiment is performed.
+            frequency_start (float): Starting frequency of the swept drive tone (in Hz).
+            frequency_stop (float): Ending frequency of the swept drive tone (in Hz).
+            frequency_step (float): Frequency increment between sweep points (in Hz).
+        """
+        super().__init__(qubit=qubit)
+        self._frequency_start: float = frequency_start
+        self._frequency_stop: float = frequency_stop
+        self._frequency_step: float = frequency_step
+
+    @property
+    def frequency_start(self) -> float:
+        """Start frequency for the drive tone sweep.
+
+        Returns:
+            float: Starting frequency of the drive tone (in Hz).
+        """
+        return self._frequency_start
+
+    @property
+    def frequency_stop(self) -> float:
+        """Stop frequency for the drive tone sweep.
+
+        Returns:
+            float: Ending frequency of the drive tone (in Hz).
+        """
+        return self._frequency_stop
+
+    @property
+    def frequency_step(self) -> float:
+        """Step size for the drive tone sweep.
+
+        Returns:
+            float: Frequency increment between sweep points (in Hz).
+        """
+        return self._frequency_step

qilisdk/{speqtrum/experiments → experiments}/experiment_result.py

@@ -229,3 +229,19 @@ class T1ExperimentResult(ExperimentResult):
 
     plot_title: ClassVar[str] = "T1"
     """Default title for T1 experiment plots."""
+
+
+@yaml.register_class
+class T2ExperimentResult(ExperimentResult):
+    """Result container for T2 dephasing experiments."""
+
+    plot_title: ClassVar[str] = "T2"
+    """Default title for T2 experiment plots."""
+
+
+@yaml.register_class
+class TwoTonesExperimentResult(ExperimentResult):
+    """Result container for TwoTones experiments."""
+
+    plot_title: ClassVar[str] = "TwoTones"
+    """Default title for TwoTones experiment plots."""

qilisdk/functionals/sampling.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 from typing import ClassVar
 
-from qilisdk.core.variables import RealNumber
+from qilisdk.core.variables import ComparisonTerm, RealNumber
 from qilisdk.digital.circuit import Circuit
 from qilisdk.functionals.functional import PrimitiveFunctional
 from qilisdk.functionals.sampling_result import SamplingResult
@@ -79,3 +79,10 @@ class Sampling(PrimitiveFunctional[SamplingResult]):
     def set_parameter_bounds(self, ranges: dict[str, tuple[float, float]]) -> None:
         """Update the admissible range for selected circuit parameters."""
         self.circuit.set_parameter_bounds(ranges)
+
+    def get_constraints(self) -> list[ComparisonTerm]:
+        """Expose parameter constraints defined on the circuit.
+        Returns:
+            list[ComparisonTerm]: a list of constraints on the circuit parameters.
+        """
+        return self.circuit.get_constraints()

qilisdk/functionals/time_evolution.py

@@ -16,7 +16,7 @@ from typing import ClassVar
 from qilisdk.analog.hamiltonian import Hamiltonian, PauliOperator
 from qilisdk.analog.schedule import Schedule
 from qilisdk.core.qtensor import QTensor
-from qilisdk.core.variables import RealNumber
+from qilisdk.core.variables import ComparisonTerm, RealNumber
 from qilisdk.functionals.functional import PrimitiveFunctional
 from qilisdk.functionals.time_evolution_result import TimeEvolutionResult
 from qilisdk.yaml import yaml
@@ -35,7 +35,7 @@ class TimeEvolution(PrimitiveFunctional[TimeEvolutionResult]):
             from qilisdk.functionals.time_evolution import TimeEvolution
 
             h0 = Z(0)
-            schedule = Schedule(T=10.0, hamiltonians={"h0": h0})
+            schedule = Schedule(hamiltonians={"h0": h0}, total_time=10.0)
             functional = TimeEvolution(schedule, observables=[Z(0), X(0)], initial_state=ket(0))
     """
 
@@ -96,3 +96,7 @@ class TimeEvolution(PrimitiveFunctional[TimeEvolutionResult]):
     def set_parameter_bounds(self, ranges: dict[str, tuple[float, float]]) -> None:
         """Update bounds for selected schedule parameters."""
         self.schedule.set_parameter_bounds(ranges)
+
+    def get_constraints(self) -> list[ComparisonTerm]:
+        """Return the parameter constraints defined within the underlying schedule."""
+        return self.schedule.get_constraints()

qilisdk/functionals/variational_program.py

@@ -13,14 +13,18 @@
 # limitations under the License.
 from __future__ import annotations
 
+import functools
+import operator
 from typing import TYPE_CHECKING, ClassVar, Generic, TypeVar
 
+from qilisdk.core.variables import BaseVariable, Parameter
 from qilisdk.functionals.functional import Functional, PrimitiveFunctional
 from qilisdk.functionals.functional_result import FunctionalResult
 from qilisdk.functionals.variational_program_result import VariationalProgramResult
 from qilisdk.yaml import yaml
 
 if TYPE_CHECKING:
+    from qilisdk.core.variables import ComparisonTerm
     from qilisdk.cost_functions.cost_function import CostFunction
     from qilisdk.optimizers.optimizer import Optimizer
 
@@ -46,6 +50,7 @@ class VariationalProgram(Functional, Generic[TFunctional]):
         optimizer: Optimizer,
         cost_function: CostFunction,
         store_intermediate_results: bool = False,
+        parameter_constraints: list[ComparisonTerm] | None = None,
     ) -> None:
         """
         Args:
@@ -53,11 +58,29 @@ class VariationalProgram(Functional, Generic[TFunctional]):
             optimizer (Optimizer): Optimization routine controlling parameter updates.
             cost_function (CostFunction): Metric used to evaluate functional executions.
             store_intermediate_results (bool, optional): Persist intermediate executions if requested by the optimizer.
+            parameter_constraints (list[ComparisonTerm] | None): Optional constraints on parameter values that are
+                enforced before optimizer updates are applied.
+
+        Raises:
+            ValueError: if the user applies constraints on parameters that are not present in the variational program.
+                        Or the constraints contain Objects that are not parameters.
         """
         self._functional = functional
         self._optimizer = optimizer
         self._cost_function = cost_function
         self._store_intermediate_results = store_intermediate_results
+        parameter_constraints = parameter_constraints or []
+        functional_params = self._functional.get_parameters()
+        for p in parameter_constraints:
+            if not p.lhs.is_parameterized_term() or not p.rhs.is_parameterized_term():
+                raise ValueError("Only parameters are allowed to be constrained.")
+            variables = p.variables()
+            for v in variables:
+                if v.label not in functional_params:
+                    raise ValueError(
+                        f"Writing a constraint on the parameter ({v}) that is not present in the variational program "
+                    )
+        self._parameter_constraints = parameter_constraints
 
     @property
     def functional(self) -> TFunctional:
@@ -78,3 +101,38 @@ class VariationalProgram(Functional, Generic[TFunctional]):
     def store_intermediate_results(self) -> bool:
         """Indicate whether intermediate execution data should be stored."""
         return self._store_intermediate_results
+
+    def get_constraints(self) -> list[ComparisonTerm]:
+        """Return variational-program-level constraints plus those from the underlying functional."""
+        return self._parameter_constraints + self._functional.get_constraints()
+
+    def _check_constraints(self, parameters: dict[str, float]) -> list[bool]:
+        """Evaluate each constraint with a proposed parameter set.
+
+        Returns:
+            list[bool]: list of booleans that correspond to whether each constraint is satisfied or not.
+
+        Raises:
+            ValueError: if the parameter is not defined in the underlying functional.
+        """
+        params: list[BaseVariable] = functools.reduce(
+            operator.iadd, (con.variables() for con in self.get_constraints()), []
+        )
+        params = list(set(params))
+        if any(not isinstance(p, Parameter) for p in params):
+            raise ValueError("Only Parameters are allowed.")
+        params_dict = {p.label: p for p in params}
+        evaluate_dict: dict[BaseVariable, float] = {}
+        functional_params = self._functional.get_parameters()
+        for label, value in parameters.items():
+            if label not in functional_params:
+                raise ValueError(f"Parameter {label} is not defined in the functional.")
+            if label in params_dict:
+                evaluate_dict[params_dict[label]] = value
+        constraints = self.get_constraints()
+        return [con.evaluate(evaluate_dict) for con in constraints]
+
+    def check_parameter_constraints(self, parameters: dict[str, float]) -> int:
+        """Return a penalty-like score (0 if valid) indicating how many constraints are violated."""
+        const_list = self._check_constraints(parameters)
+        return sum((100 if not con else 0) for con in const_list)