qilisdk 0.1.4__py3-none-any.whl → 0.1.5__py3-none-any.whl

qilisdk/analog/hamiltonian.py

@@ -18,19 +18,24 @@ import re
 from abc import ABC
 from collections import defaultdict
 from functools import reduce
+from itertools import product
 from typing import TYPE_CHECKING, Callable, ClassVar
 
 import numpy as np
-from scipy.sparse import csc_array, identity, kron, spmatrix
+from scipy.sparse import csr_matrix, identity, kron, spmatrix
 
+from qilisdk.common.parameterizable import Parameterizable
+from qilisdk.common.qtensor import QTensor
+from qilisdk.common.variables import BaseVariable, Parameter, Term
 from qilisdk.yaml import yaml
 
-from .exceptions import InvalidHamiltonianOperation, NotSupportedOperation
+from .exceptions import InvalidHamiltonianOperation
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
-Complex = int | float | complex
+
+Number = int | float | complex
 
 
 ###############################################################################
@@ -62,20 +67,20 @@ def _get_pauli(name: str, qubit: int) -> PauliOperator:
 ###############################################################################
 # Public Factory Functions
 ###############################################################################
-def Z(qubit: int) -> PauliOperator:
-    return _get_pauli("Z", qubit)
+def Z(qubit: int) -> Hamiltonian:
+    return _get_pauli("Z", qubit).to_hamiltonian()
 
 
-def X(qubit: int) -> PauliOperator:
-    return _get_pauli("X", qubit)
+def X(qubit: int) -> Hamiltonian:
+    return _get_pauli("X", qubit).to_hamiltonian()
 
 
-def Y(qubit: int) -> PauliOperator:
-    return _get_pauli("Y", qubit)
+def Y(qubit: int) -> Hamiltonian:
+    return _get_pauli("Y", qubit).to_hamiltonian()
 
 
-def I(qubit: int = 0) -> PauliOperator:  # noqa: E743
-    return _get_pauli("I", qubit)
+def I(qubit: int = 0) -> Hamiltonian:  # noqa: E743
+    return _get_pauli("I", qubit).to_hamiltonian()
 
 
 ###############################################################################
@@ -83,8 +88,18 @@ def I(qubit: int = 0) -> PauliOperator:  # noqa: E743
 ###############################################################################
 class PauliOperator(ABC):
     """
-    A generic Pauli operator that acts on one qubit.
-    Flyweight usage: do NOT instantiate directly—use X(q), Y(q), etc.
+    A generic abstract Pauli operator that acts on one qubit.
+
+    Example:
+        .. code-block:: python
+
+            from qilisdk.analog import PauliX
+
+            op = PauliX(0)
+
+    Flyweight usage: do NOT instantiate directly—use PauliX(q), PauliY(q), etc.
+
+    Note: You can also use the factory functions X(q), Y(q), Z(q), I(q) to get a Hamiltonian object.
     """
 
     _NAME: ClassVar[str]
@@ -131,33 +146,33 @@ class PauliOperator(ABC):
 
     # ----------- Arithmetic Operators ------------
 
-    def __add__(self, other: Complex | PauliOperator | Hamiltonian) -> Hamiltonian:
+    def __add__(self, other: Number | PauliOperator | Hamiltonian) -> Hamiltonian:
         return self.to_hamiltonian() + other
 
     __radd__ = __add__
     __iadd__ = __add__
 
-    def __sub__(self, other: Complex | PauliOperator | Hamiltonian) -> Hamiltonian:
+    def __sub__(self, other: Number | PauliOperator | Hamiltonian) -> Hamiltonian:
         return self.to_hamiltonian() - other
 
-    def __rsub__(self, other: Complex | PauliOperator | Hamiltonian) -> Hamiltonian:
+    def __rsub__(self, other: Number | PauliOperator | Hamiltonian) -> Hamiltonian:
         return other - self.to_hamiltonian()
 
     __isub__ = __sub__
 
-    def __mul__(self, other: Complex | PauliOperator | Hamiltonian) -> Hamiltonian:
+    def __mul__(self, other: Number | PauliOperator | Hamiltonian) -> Hamiltonian:
         return self.to_hamiltonian() * other
 
-    def __rmul__(self, other: Complex | PauliOperator | Hamiltonian) -> Hamiltonian:
+    def __rmul__(self, other: Number | PauliOperator | Hamiltonian) -> Hamiltonian:
         return other * self.to_hamiltonian()
 
     __imul__ = __mul__
 
-    def __truediv__(self, other: Complex | PauliOperator | Hamiltonian) -> Hamiltonian:
+    def __truediv__(self, other: Number | PauliOperator | Hamiltonian) -> Hamiltonian:
         return self.to_hamiltonian() / other
 
-    def __rtruediv__(self, _: Complex | PauliOperator | Hamiltonian) -> Hamiltonian:
-        raise NotSupportedOperation("Division by operators is not supported")
+    def __rtruediv__(self, _: Number | PauliOperator | Hamiltonian) -> Hamiltonian:
+        raise InvalidHamiltonianOperation("Division by operators is not supported")
 
     __itruediv__ = __truediv__
 
@@ -194,53 +209,174 @@ class PauliI(PauliOperator):
 
 
 @yaml.register_class
-class Hamiltonian:
+class Hamiltonian(Parameterizable):
     """
-    The `elements` dictionary now maps from a tuple of PauliOperator objects
-    to a complex coefficient. For example:
-        {
-            (Z(0), Y(1)):  1,
-            (X(1),):       1j,
-        }
+    Represent a Hamiltonian expressed as a linear combination of Pauli operators.
+
+    Example:
+        .. code-block:: python
+
+            from qilisdk.analog.hamiltonian import Hamiltonian, X, Z
+
+            H = X(0) * X(1) + Z(1)
     """
 
     _EPS: float = 1e-14
     _PAULI_PRODUCT_TABLE: ClassVar[dict[tuple[str, str], tuple[complex, Callable[..., PauliOperator]]]] = {
-        ("X", "X"): (1, I),
-        ("X", "Y"): (1j, Z),
-        ("X", "Z"): (-1j, Y),
-        ("Y", "X"): (-1j, Z),
-        ("Y", "Y"): (1, I),
-        ("Y", "Z"): (1j, X),
-        ("Z", "X"): (1j, Y),
-        ("Z", "Y"): (-1j, X),
-        ("Z", "Z"): (1, I),
+        ("X", "X"): (1, PauliI),
+        ("X", "Y"): (1j, PauliZ),
+        ("X", "Z"): (-1j, PauliY),
+        ("Y", "X"): (-1j, PauliZ),
+        ("Y", "Y"): (1, PauliI),
+        ("Y", "Z"): (1j, PauliX),
+        ("Z", "X"): (1j, PauliY),
+        ("Z", "Y"): (-1j, PauliX),
+        ("Z", "Z"): (1, PauliI),
     }
 
     ZERO: int = 0
 
-    def __init__(self, elements: dict[tuple[PauliOperator, ...], complex] | None = None) -> None:
-        self._elements: dict[tuple[PauliOperator, ...], complex] = defaultdict(complex)
+    def __init__(self, elements: dict[tuple[PauliOperator, ...], complex | Term | Parameter] | None = None) -> None:
+        """
+        Build a Hamiltonian from a mapping of Pauli operator products to coefficients.
+
+        Args:
+            elements (dict[tuple[PauliOperator, ...], complex | Term | Parameter], optional):
+                Mapping from operator tuples to numerical coefficients or symbolic parameters. For example:
+
+                .. code-block:: python
+
+                    {
+                        (Z(0), Y(1)): 1.0,
+                        (X(1),): 1j,
+                    }
+
+                Defaults to None, which creates an empty Hamiltonian.
+
+        Raises:
+            ValueError: If the provided coefficients include generic variables instead of parameters.
+        """
+        self._elements: dict[tuple[PauliOperator, ...], complex | Term | Parameter] = defaultdict(complex)
+        self._parameters: dict[str, Parameter] = {}
         if elements:
             for key, val in elements.items():
+                if isinstance(val, Term):
+                    for v in val.variables():
+                        if isinstance(v, Parameter):
+                            self._parameters[v.label] = v
+                        else:
+                            raise ValueError(
+                                "Only Parameters are allowed to be used in hamiltonians. Generic Variables are not supported"
+                            )
+                elif isinstance(val, BaseVariable):
+                    if isinstance(val, Parameter):
+                        self._parameters[val.label] = val
+
+                    else:
+                        raise ValueError(
+                            "Only Parameters are allowed to be used in hamiltonians. Generic Variables are not supported"
+                        )
                 self._elements[key] += val
             self.simplify()
 
     @property
     def nqubits(self) -> int:
-        """Number of qubits acting on the hamiltonian."""
+        """Number of qubits on which the Hamiltonian acts."""
         qubits = {op.qubit for key in self._elements for op in key}
 
         return max(qubits) + 1 if qubits else 0
 
     @property
     def elements(self) -> dict[tuple[PauliOperator, ...], complex]:
-        """Returns the internal dictionary of elements (read-only)."""
-        return self._elements
+        """Return the stored operator-coefficient mapping with symbolic terms evaluated."""
+        return {
+            k: (v if isinstance(v, complex) else (v.evaluate({}) if isinstance(v, Term) else v.evaluate()))
+            for k, v in self._elements.items()
+        }
+
+    @property
+    def nparameters(self) -> int:
+        """Return the number of unique symbolic parameters contained in the Hamiltonian."""
+        return len(self._parameters)
+
+    @property
+    def parameters(self) -> dict[str, Parameter]:
+        """Return a mapping from parameter labels to their corresponding parameter objects."""
+        return self._parameters
+
+    def get_parameter_values(self) -> list[float]:
+        """Return the current numeric values of the Hamiltonian parameters."""
+        return [param.value for param in self._parameters.values()]
+
+    def get_parameter_names(self) -> list[str]:
+        """Return the ordered list of parameter labels defined in the Hamiltonian."""
+        return list(self._parameters.keys())
+
+    def get_parameters(self) -> dict[str, float]:
+        """Return a mapping from parameter labels to their current numerical values."""
+        return {label: param.value for label, param in self._parameters.items()}
+
+    def set_parameter_values(self, values: list[float]) -> None:
+        """
+        Update the numerical values of the Hamiltonian parameters.
+
+        Args:
+            values (list[float]): New values ordered according to ``get_parameter_names()``.
+
+        Raises:
+            ValueError: If the number of provided values does not match ``nparameters``.
+        """
+        if len(values) != self.nparameters:
+            raise ValueError(f"Provided {len(values)} but Hamiltonian has {self.nparameters} parameters.")
+        for i, parameter in enumerate(self._parameters.values()):
+            parameter.set_value(values[i])
+
+    def set_parameters(self, parameter_dict: dict[str, float]) -> None:
+        """
+        Update a subset of parameters by label.
+
+        Args:
+            parameter_dict (dict[str, float]): Mapping from parameter labels to new numerical values.
+
+        Raises:
+            ValueError: If an unknown parameter label is provided.
+        """
+        for label, param in parameter_dict.items():
+            if label not in self._parameters:
+                raise ValueError(f"Parameter {label} is not defined in this hamiltonian.")
+            self._parameters[label].set_value(param)
+
+    def get_parameter_bounds(self) -> dict[str, tuple[float, float]]:
+        """Return the lower and upper bounds currently associated with each parameter."""
+        return {k: v.bounds for k, v in self._parameters.items()}
+
+    def set_parameter_bounds(self, ranges: dict[str, tuple[float, float]]) -> None:
+        """
+        Update parameter bounds.
+
+        Args:
+            ranges (dict[str, tuple[float, float]]): Mapping from parameter labels to ``(lower, upper)`` bounds.
+
+        Raises:
+            ValueError: If an unknown parameter label is provided.
+        """
+        for label, bound in ranges.items():
+            if label not in self._parameters:
+                raise ValueError(
+                    f"The provided parameter label {label} is not defined in the list of parameters in this object."
+                )
+            self._parameters[label].set_bounds(bound[0], bound[1])
 
     def simplify(self) -> Hamiltonian:
+        """Simplify the Hamiltonian expression by removing near-zero terms and accumulating constant terms.
+
+        Returns:
+            Hamiltonian: Simplified Hamiltonian
+        """
         # 1) Remove near-zero
-        keys_to_remove = [key for key, value in self._elements.items() if abs(value) < Hamiltonian._EPS]
+        keys_to_remove = [
+            key for key, value in self._elements.items() if isinstance(value, complex) and abs(value) < Hamiltonian._EPS
+        ]
         for key in keys_to_remove:
             del self._elements[key]
 
@@ -252,11 +388,11 @@ class Hamiltonian:
         ]
         for key, value in to_accumulate:
             del self._elements[key]
-            self._elements[I(0),] += value
+            self._elements[PauliI(0),] += value
 
         return self
 
-    def _apply_operator_on_qubit(self, terms: list[PauliOperator]) -> spmatrix:
+    def _apply_operator_on_qubit(self, terms: list[PauliOperator], padding: int = 0) -> spmatrix:
         """Get the matrix representation of a single term by taking the tensor product
         of operators acting on each qubit. For qubits with no operator in `terms`,
         the identity is used.
@@ -269,12 +405,12 @@ class Hamiltonian:
         """
         # Build a list of factors for each qubit
         factors = []
-        for q in range(self.nqubits):
+        for q in range(self.nqubits + padding):
             # Look for an operator acting on qubit q
             op = next((t for t in terms if t.qubit == q), None)
             if op is not None:
                 # Wrap the operator's matrix as a sparse matrix.
-                factors.append(csc_array(np.array(op.matrix)))
+                factors.append(csr_matrix(np.array(op.matrix)))
             else:
                 factors.append(identity(2, format="csc"))
         # Compute the tensor (Kronecker) product over all qubits.
@@ -289,13 +425,51 @@ class Hamiltonian:
         """
         dim = 2**self.nqubits
         # Initialize a zero matrix of the appropriate dimension.
-        result = csc_array(np.zeros((dim, dim), dtype=complex))
+        result = csr_matrix(np.zeros((dim, dim), dtype=complex))
         for coeff, term in self:
             result += coeff * self._apply_operator_on_qubit(term)
         return result
 
+    def to_qtensor(self, total_nqubits: int | None = None) -> QTensor:
+        """Return the Hamiltonian as a ``QTensor`` built from the sparse matrix representation.
+
+        Args:
+            total_nqubits (int, optional): Specify the total number of qubits that this hamiltonian acts on. Defaults to None.
+
+        Returns:
+            QTensor: The QTensor object representation of the Hamiltonian.
+
+        Raises:
+            ValueError: If the total_nqubits provided is lower than the number of qubits effected by the hamiltonian.
+        """
+
+        nqubits = total_nqubits or self.nqubits
+        padding = nqubits - self.nqubits
+        if nqubits < self.nqubits:
+            raise ValueError(
+                f"The total number of qubits can't be less than the number of the qubits effected by this hamiltonian ({self.nqubits})"
+            )
+
+        dim = 2 ** (nqubits)
+
+        # Initialize a zero matrix of the appropriate dimension.
+        result = csr_matrix(np.zeros((dim, dim), dtype=complex))
+        for coeff, term in self:
+            result += coeff * self._apply_operator_on_qubit(term, padding=padding)
+        return QTensor(result)
+
+    def get_static_hamiltonian(self) -> Hamiltonian:
+        """Return a Hamiltonian containing only constant coefficients."""
+        out = Hamiltonian()
+        for pauli, value in self.elements.items():
+            aux: Hamiltonian | PauliOperator = pauli[0]
+            for p in list(pauli)[1:]:
+                aux *= p
+            out += aux * value
+        return out
+
     def __iter__(self) -> Iterator[tuple[complex, list[PauliOperator]]]:
-        for key, value in self._elements.items():
+        for key, value in self.elements.items():
             yield value, list(key)
 
     # ------- Equality & hashing --------
@@ -304,10 +478,12 @@ class Hamiltonian:
         if other == Hamiltonian.ZERO:
             return bool(
                 len(self._elements) == 0
-                or (len(self._elements) == 1 and (I(0),) in self._elements and self._elements[I(0),] == 0)
+                or (len(self._elements) == 1 and (PauliI(0),) in self._elements and self._elements[PauliI(0),] == 0)
+            )
+        if isinstance(other, Number):
+            return bool(
+                len(self._elements) == 1 and (PauliI(0),) in self._elements and self._elements[PauliI(0),] == other
             )
-        if isinstance(other, Complex):
-            return bool(len(self._elements) == 1 and (I(0),) in self._elements and self._elements[I(0),] == other)
         if isinstance(other, PauliOperator):
             other = other.to_hamiltonian()
         if not isinstance(other, Hamiltonian):
@@ -322,7 +498,7 @@ class Hamiltonian:
         return hash(items_frozen)
 
     def __copy__(self) -> Hamiltonian:
-        return Hamiltonian(elements=self.elements.copy())
+        return Hamiltonian(elements=self._elements.copy())
 
     # ------- String representation --------
 
@@ -356,9 +532,9 @@ class Hamiltonian:
             return s
 
         # We want to place the single identity term (I(0),) at the front if it exists
-        items = list(self._elements.items())
+        items = list(self.elements.items())
         try:
-            i = next(idx for idx, (key, _) in enumerate(items) if len(key) == 1 and key[0] == (I(0)))
+            i = next(idx for idx, (key, _) in enumerate(items) if len(key) == 1 and key[0] == (PauliI(0)))
             item = items.pop(i)
             items.insert(0, item)
         except StopIteration:
@@ -397,23 +573,102 @@ class Hamiltonian:
         return " ".join(parts)
 
     @classmethod
-    def parse(cls, ham_str: str) -> Hamiltonian:
-        ham_str = ham_str.strip()
+    def from_qtensor(cls, tensor: QTensor, tol: float = 1e-10, prune: float = 1e-12) -> Hamiltonian:
+        """
+        Expand a qtensor (dense operator) on n qubits into a sum of Pauli strings,
+        returning a qilisdk.analog.Hamiltonian.
+
+        Args:
+            tol (float): Hermiticity check tolerance.
+            prune (float): Drop coefficients whose absolute value satisfies ``abs(c) < prune`` to reduce numerical noise.
+
+        Returns:
+            Hamiltonian: Sum_{P in {I,X,Y,Z}^{⊗ n}} c_P * P  with c_P = Tr(qt * P) / 2^n
+
+        Raises
+            ValueError: If the input is not square, not a power-of-two dimension, or not Hermitian w.r.t. `tol`.
+        """
+        A = np.asarray(tensor.dense)
+
+        dim = tensor.shape[0]
+        n = round(np.log2(dim))
+        if 2**n != dim:
+            raise ValueError(f"Matrix dimension {dim} is not a power of two.")
+        if not tensor.is_hermitian():
+            raise ValueError("Matrix is not Hermitian within tolerance; cannot form a Hamiltonian.")
+
+        # QiliSDK Pauli constructors indexed by qubit id
+        pauli_for: dict[int, Callable[[int], Hamiltonian]] = {0: I, 1: X, 2: Y, 3: Z}
+
+        # Normalization from orthonormality: Tr(P_a P_b) = 2^n δ_ab
+        norm = 1.0 / (2**n)
+
+        # Prebuild per-qubit operator “letters” so we can construct full strings quickly
+
+        H = Hamiltonian()  # start additive Hamiltonian expression
+        # Full Pauli basis (includes identity on any subset automatically)
+        for word in product((0, 1, 2, 3), repeat=n):
+            # Compose the word into a QiliSDK operator acting on the proper qubits
+            # Example word=(3,1,0) for n=3 -> Z(0)*X(1)*I(2)
+            op = Hamiltonian()
+            for q, letter in enumerate(word):
+                # multiply by the operator on qubit q
+                op = op * pauli_for[letter](q) if op != 0 else pauli_for[letter](q)
+
+            # Convert to dense once; no padding needed because it spans all n qubits
+            P_dense = op.to_qtensor(n).dense
+
+            # Coefficient c_P = Tr(A P) / 2^n  (P is Hermitian)
+            c = norm * np.trace(A @ P_dense)
+
+            # Numerical safety: coefficients should be real for Hermitian A and P
+            if abs(c.imag) < tol:
+                c = c.real
+
+            if abs(c) > prune:
+                H += c * op
+
+        # Optional: verify round-trip (use a slightly looser atol to tolerate pruning)
+        if not np.allclose(H.to_qtensor(n).dense, A, atol=max(10 * prune, 1e-9)):
+            # If this triggers, consider lowering `prune` or raising `tol`.
+            raise ValueError("Pauli expansion failed round-trip check; try adjusting tolerances.")
+
+        return H
+
+    @classmethod
+    def parse(cls, hamiltonian_str: str) -> Hamiltonian:
+        hamiltonian_str = hamiltonian_str.strip()
+
+        # 1) remove *all* spaces inside any ( … ) group (coefficients or indices)
+        hamiltonian_str = re.sub(
+            r"\(\s*([0-9A-Za-z.+\-j\s]+?)\s*\)",
+            lambda m: "(" + re.sub(r"\s+", "", str(m.group(1))) + ")",
+            hamiltonian_str,
+        )
+
+        # 2) collapse multiple spaces down to one (outside the parens now)
+        hamiltonian_str = re.sub(r"\s+", " ", hamiltonian_str)
+
+        # 3) ensure a single space between a closing “)” and the next operator token like X(0)/Y(1)/etc.
+        hamiltonian_str = re.sub(r"\)\s*(?=[XYZI]\()", ") ", hamiltonian_str)
+
         # Special case: "0" => empty Hamiltonian
-        if ham_str == "0":
+        if hamiltonian_str == "0":
             return cls({})
 
-        elements: dict[tuple[PauliOperator, ...], complex] = defaultdict(complex)
+        elements: dict[tuple[PauliOperator, ...], complex | Term | Parameter] = defaultdict(
+            complex
+        )  # TODO (ameer): the parsing doesn't support Term and Parameters
 
         # If there's no initial +/- sign, prepend '+ ' for easier splitting
-        if not ham_str.startswith("+") and not ham_str.startswith("-"):
-            ham_str = "+ " + ham_str
+        if not hamiltonian_str.startswith("+") and not hamiltonian_str.startswith("-"):
+            hamiltonian_str = "+ " + hamiltonian_str
 
         # Replace " - " with " + - " so each term is split on " + "
-        ham_str = ham_str.replace(" - ", " + - ")
+        hamiltonian_str = hamiltonian_str.replace(" - ", " + - ")
 
         # Split on " + "
-        tokens = ham_str.split(" + ")
+        tokens = hamiltonian_str.split(" + ")
         # Remove any empty tokens (can happen if the string started "+ ")
         tokens = [t.strip() for t in tokens if t.strip()]
 
@@ -475,19 +730,74 @@ class Hamiltonian:
 
             return coeff_val, ops
 
-        for tok in tokens:
-            coeff, op_list = parse_token(tok)
+        for token in tokens:
+            coeff, op_list = parse_token(token)
             if not op_list:
                 # purely scalar => store as (I(0),)
-                elements[I(0),] += coeff
+                elements[PauliI(0),] += coeff
             else:
                 # Sort operators by qubit for canonical ordering
                 op_list.sort(key=lambda op: op.qubit)
                 elements[tuple(op_list)] += coeff
 
-        ham = cls(elements)
-        ham.simplify()
-        return ham
+        hamiltonian = cls(elements)
+        hamiltonian.simplify()
+        return hamiltonian
+
+    def commutator(self, h: Hamiltonian) -> Hamiltonian:
+        """compute the commutator of the current hamiltonian with another hamiltonian (h)
+
+        Args:
+            h (Hamiltonian): the second hamiltonian.
+
+        Returns:
+            Hamiltonian: the commutator.
+        """
+        return self * h - h * self
+
+    def anticommutator(self, h: Hamiltonian) -> Hamiltonian:
+        """compute the anticommutator of the current hamiltonian with another hamiltonian (h)
+
+        Args:
+            h (Hamiltonian): the second hamiltonian.
+
+        Returns:
+            Hamiltonian: the anticommutator.
+        """
+        return self * h + h * self
+
+    def vector_norm(self) -> float:
+        """
+        Returns:
+            float: the vector norm of the hamiltonian.
+        """
+        s = 0
+        for coeff, _ in self:
+            s += np.conj(coeff) * coeff
+        return np.real(np.sqrt(s))
+
+    def frobenius_norm(self) -> float:
+        """
+        Returns:
+            float: the forbenius norm of the hamiltonian.
+        """
+        n = self.nqubits
+        s = 0
+        for coeff, _ in self:
+            s += np.conj(coeff) * coeff
+        return np.real(np.sqrt(s) * np.sqrt(2**n))
+
+    def trace(self) -> Number:
+        """
+        Returns:
+            float: the trace of the hamiltonian.
+        """
+        t = self._elements.get((PauliI(0),), 0)
+        if isinstance(t, Parameter):
+            return t.evaluate()
+        if isinstance(t, Term):
+            return t.evaluate({})
+        return t
 
     # ------- Internal multiplication helpers --------
 
@@ -520,7 +830,7 @@ class Hamiltonian:
 
         # If everything simplified to identity, we store I(0)
         if not final_ops:
-            final_ops = [I(0)]
+            final_ops = [PauliI(0)]
 
         # Sort again by qubit (to keep canonical form)
         final_ops.sort(key=lambda op: op.qubit)
@@ -541,87 +851,87 @@ class Hamiltonian:
         key = (op1.name, op2.name)
         result = Hamiltonian._PAULI_PRODUCT_TABLE.get(key)
         if result is None:
-            raise NotSupportedOperation(f"Multiplying {op1} and {op2} not supported.")
+            raise InvalidHamiltonianOperation(f"Multiplying {op1} and {op2} not supported.")
         phase, op_cls = result
 
         # By convention, an I operator is always I(0) in this code
-        if op_cls is I:
-            return phase, I(0)
+        if op_cls is PauliI:
+            return phase, PauliI(0)
         # Otherwise, keep the same qubit
         return phase, op_cls(op1.qubit)
 
-    @staticmethod
-    def _multiply_hamiltonians(h1: Hamiltonian, h2: Hamiltonian) -> Hamiltonian:
-        out = Hamiltonian()
-        for key1, c1 in h1.elements.items():
-            for key2, c2 in h2.elements.items():
-                phase, new_key = Hamiltonian._multiply_sets(key1, key2)
-                out.elements[new_key] += phase * c1 * c2
-        return out.simplify()
-
     # ------- Public arithmetic operators --------
 
-    def __add__(self, other: Complex | PauliOperator | Hamiltonian) -> Hamiltonian:
+    def __add__(self, other: Number | PauliOperator | Hamiltonian | Term | Parameter) -> Hamiltonian:
         out = copy.copy(self)
+        if isinstance(other, Term) and not other.is_parameterized_term():
+            raise ValueError("Term provided contains generic variables that are not Parameter.")
         out._add_inplace(other)
         return out.simplify()
 
-    def __radd__(self, other: Complex | PauliOperator | Hamiltonian) -> Hamiltonian:
+    def __radd__(self, other: Number | PauliOperator | Hamiltonian | Term | Parameter) -> Hamiltonian:
+        if isinstance(other, Term) and not other.is_parameterized_term():
+            raise ValueError("Term provided contains generic variables that are not Parameter.")
         return self.__add__(other)
 
-    def __sub__(self, other: Complex | PauliOperator | Hamiltonian) -> Hamiltonian:
+    def __sub__(self, other: Number | PauliOperator | Hamiltonian | Term | Parameter) -> Hamiltonian:
+        if isinstance(other, Term) and not other.is_parameterized_term():
+            raise ValueError("Term provided contains generic variables that are not Parameter.")
         out = copy.copy(self)
         out._sub_inplace(other)
         return out.simplify()
 
-    def __rsub__(self, other: Complex | PauliOperator | Hamiltonian) -> Hamiltonian:
+    def __rsub__(self, other: Number | PauliOperator | Hamiltonian | Term | Parameter) -> Hamiltonian:
         # (other - self)
+        if isinstance(other, Term) and not other.is_parameterized_term():
+            raise ValueError("Term provided contains generic variables that are not Parameter.")
         out = copy.copy(other if isinstance(other, Hamiltonian) else Hamiltonian() + other)
         out._sub_inplace(self)
         return out.simplify()
 
-    def __mul__(self, other: Complex | PauliOperator | Hamiltonian) -> Hamiltonian:
+    def __neg__(self) -> Hamiltonian:
+        return -1 * self
+
+    def __mul__(self, other: Number | PauliOperator | Hamiltonian | Term | Parameter) -> Hamiltonian:
+        if isinstance(other, Term) and not other.is_parameterized_term():
+            raise ValueError("Term provided contains generic variables that are not Parameter.")
         out = copy.copy(self)
         out._mul_inplace(other)
         return out.simplify()
 
-    def __rmul__(self, other: Complex | PauliOperator | Hamiltonian) -> Hamiltonian:
+    def __rmul__(self, other: Number | PauliOperator | Hamiltonian | Term | Parameter) -> Hamiltonian:
+        if isinstance(other, Term) and not other.is_parameterized_term():
+            raise ValueError("Term provided contains generic variables that are not Parameter.")
         if isinstance(other, Hamiltonian):
             out = copy.copy(other)
             out._mul_inplace(self)
             return out.simplify()
         return self.__mul__(other)
 
-    def __truediv__(self, other: Complex | PauliOperator | Hamiltonian) -> Hamiltonian:
+    def __truediv__(self, other: Number | PauliOperator | Hamiltonian) -> Hamiltonian:
         out = copy.copy(self)
         out._div_inplace(other)
         return out.simplify()
 
-    def __rtruediv__(self, other: Complex | PauliOperator | Hamiltonian) -> Hamiltonian:
+    def __rtruediv__(self, other: Number | PauliOperator | Hamiltonian) -> Hamiltonian:
         # (other / self)
-        if not isinstance(other, (int, float, complex)):
-            raise InvalidHamiltonianOperation("Division by operators is not supported")
-        out = copy.copy(self)
-        return (1 / other) * out
-
-    def __rfloordiv__(self, other: Complex | PauliOperator | Hamiltonian) -> Hamiltonian:
-        if not isinstance(other, (int, float, complex)):
-            raise NotSupportedOperation("Division of operators is not supported")
-        return (1 / other) * self
+        raise InvalidHamiltonianOperation("Division by operators is not supported")
 
     __iadd__ = __add__
     __isub__ = __sub__
     __imul__ = __mul__
     __itruediv__ = __truediv__
 
-    def _add_inplace(self, other: Complex | PauliOperator | Hamiltonian) -> None:
+    def _add_inplace(self, other: Number | PauliOperator | Hamiltonian | Term | Parameter) -> None:
         if isinstance(other, Hamiltonian):
             # If it's empty, do nothing
             if not other.elements:
                 return
             # Otherwise, add each term
-            for key, val in other.elements.items():
+            for key, val in other._elements.items():  # noqa: SLF001
                 self._elements[key] += val
+
+            self._parameters.update(other.parameters)
         elif isinstance(other, PauliOperator):
             # Just add 1 to that single operator key
             self._elements[other,] += 1
@@ -629,26 +939,47 @@ class Hamiltonian:
             if other == 0:
                 return
             # Add the scalar to (I(0),)
-            self._elements[I(0),] += other
+            self._elements[PauliI(0),] += other
+        elif isinstance(other, (Term, Parameter)):
+            if isinstance(other, Term):
+                if not other.is_parameterized_term():
+                    raise ValueError(
+                        "Only Parameters are allowed to be used in hamiltonians. Generic Variables are not supported"
+                    )
+                self._parameters.update({v.label: v for v in other if isinstance(v, Parameter)})
+            else:
+                self._parameters[other.label] = other
+            self._elements[PauliI(0),] += other
         else:
             raise InvalidHamiltonianOperation(f"Invalid addition between Hamiltonian and {other.__class__.__name__}.")
 
-    def _sub_inplace(self, other: Complex | PauliOperator | Hamiltonian) -> None:
+    def _sub_inplace(self, other: Number | PauliOperator | Hamiltonian | Term | Parameter) -> None:
         if isinstance(other, Hamiltonian):
-            for key, val in other.elements.items():
+            for key, val in other._elements.items():  # noqa: SLF001
                 self._elements[key] -= val
+            self._parameters.update(other._parameters)  # noqa: SLF001
         elif isinstance(other, PauliOperator):
             self._elements[other,] -= 1
         elif isinstance(other, (int, float, complex)):
             if other == 0:
                 return
-            self._elements[I(0),] -= other
+            self._elements[PauliI(0),] -= other
+        elif isinstance(other, (Term, Parameter)):
+            if isinstance(other, Term):
+                if not other.is_parameterized_term():
+                    raise ValueError(
+                        "Only Parameters are allowed to be used in hamiltonians. Generic Variables are not supported"
+                    )
+                self._parameters.update({v.label: v for v in other if isinstance(v, Parameter)})
+            else:
+                self._parameters[other.label] = other
+            self._elements[PauliI(0),] -= other
         else:
             raise InvalidHamiltonianOperation(
                 f"Invalid subtraction between Hamiltonian and {other.__class__.__name__}."
             )
 
-    def _mul_inplace(self, other: Complex | PauliOperator | Hamiltonian) -> None:
+    def _mul_inplace(self, other: Number | PauliOperator | Hamiltonian | Term | Parameter) -> None:
         if isinstance(other, (int, float, complex)):
             # 0 short-circuit
             if other == 0:
@@ -663,6 +994,19 @@ class Hamiltonian:
                 self._elements[k] *= other
             return None
 
+        if isinstance(other, (Term, Parameter)):
+            if isinstance(other, Term):
+                if not other.is_parameterized_term():
+                    raise ValueError(
+                        "Only Parameters are allowed to be used in hamiltonians. Generic Variables are not supported"
+                    )
+                self._parameters.update({v.label: v for v in other if isinstance(v, Parameter)})
+            else:
+                self._parameters[other.label] = other
+            for k in self._elements:
+                self._elements[k] *= other
+            return None
+
         if isinstance(other, PauliOperator):
             # Convert single PauliOperator -> Hamiltonian with 1 key
             # Then do the single-key Hamiltonian path below
@@ -676,7 +1020,7 @@ class Hamiltonian:
 
             # Check if 'other' is purely scalar identity => short-circuit
             if len(other.elements) == 1:
-                ((ops2, c2),) = other.elements.items()  # single item
+                ((ops2, c2),) = other._elements.items()  # single item  # noqa: SLF001
                 if len(ops2) == 1:
                     op2 = ops2[0]
                     if op2.name == "I" and op2.qubit == 0:
@@ -684,12 +1028,13 @@ class Hamiltonian:
                         return self._mul_inplace(c2)
 
             # Otherwise, we do the general multiply
-            new_dict: dict[tuple[PauliOperator, ...], complex] = defaultdict(complex)
+            new_dict: dict[tuple[PauliOperator, ...], complex | Term | Parameter] = defaultdict(complex)
             for ops1, c1 in self._elements.items():
-                for ops2, c2 in other.elements.items():
+                for ops2, c2 in other._elements.items():  # noqa: SLF001
                     phase, new_ops = self._multiply_sets(ops1, ops2)
                     new_dict[new_ops] += phase * c1 * c2
             self._elements = new_dict
+            self._parameters.update(other._parameters)  # noqa: SLF001
 
         else:
             raise InvalidHamiltonianOperation(
@@ -697,7 +1042,7 @@ class Hamiltonian:
             )
         return None
 
-    def _div_inplace(self, other: Complex | PauliOperator | Hamiltonian) -> None:
+    def _div_inplace(self, other: Number | PauliOperator | Hamiltonian) -> None:
         # Only valid for scalars
         if not isinstance(other, (int, float, complex)):
             raise InvalidHamiltonianOperation("Division by operators is not supported")