qemcmc 0.1.0__py3-none-any.whl

qemcmc/__init__.py

@@ -0,0 +1,25 @@
+from .sampler import MCMC, ClassicalMCMC, QeMCMC
+from .model import EnergyModel
+from .circuits import CircuitMaker
+from .utils import MCMCState, MCMCChain, plot_chains, get_random_state, get_all_possible_states, ModelMaker
+from .spectralgap import SpectralGap
+
+__all__ = [
+    "EnergyModel",
+    "MCMC",
+    "ClassicalMCMC",
+    "QeMCMC",
+    "MCMCState",
+    "MCMCChain",
+    "ModelMaker",
+    "plot_chains",
+    "get_random_state",
+    "get_all_possible_states",
+    "SpectralGap",
+    "CircuitMaker",
+    "CoarseGraining",
+]
+
+
+def main() -> None:
+    print("Hello from QeMCMC!")

qemcmc/circuits.py

@@ -0,0 +1,180 @@
+import pennylane as qml
+import numpy as np
+
+
+class CircuitMaker:
+    """
+    Constructs and simulates quantum circuits used to generate QeMCMC proposals.
+
+    This class builds the Hamiltonian corresponding to a given energy model and
+    simulates its time evolution using PennyLane. Starting from a classical
+    bitstring configuration, the circuit performs Trotterised quantum evolution
+    and samples a new configuration from the resulting quantum state.
+
+    The generated sample serves as the proposal state in the quantum-enhanced
+    MCMC algorithm.
+
+    Parameters
+    ----------
+    model : EnergyModel
+        Energy model defining the problem Hamiltonian.
+    gamma : float
+        Strength of the transverse-field (mixer) term in the Hamiltonian.
+    time : int or tuple[int, int]
+        Total evolution time or range of evolution times used in the simulation.
+    delta_time : float, optional
+        Duration of each Trotter step used in the approximate time evolution.
+        Default is 0.8.
+
+    Notes
+    -----
+    The total Hamiltonian simulated by the circuit is
+
+        H = γ H_mixer + (1 - γ) α H_problem
+
+    where ``H_problem`` encodes the classical energy model and ``H_mixer``
+    corresponds to a transverse-field term. The evolution is approximated
+    using Trotterisation via ``qml.ApproxTimeEvolution``.
+    """
+
+    def __init__(self, model, gamma, time, delta_time=0.8):
+        self.model = model
+        self.gamma = gamma
+        self.time = time
+        self.delta_time = delta_time
+        self.n_qubits = model.n
+
+        # Calculate number of Trotter steps
+        t_val = self.time[0] if isinstance(self.time, tuple) else self.time
+        self.num_trotter_steps = int(np.floor((t_val / self.delta_time)))
+
+        self.dev = qml.device("lightning.qubit", wires=self.n_qubits)
+
+    def get_problem_hamiltonian(self, couplings, sign=-1):
+        """
+        Construct Problem Hamiltonian from symmetric coupling tensors.
+        """
+        coeffs = []
+        obs = []
+
+        for coupling_tensor in couplings:
+            coupling_tensor = np.asarray(coupling_tensor)
+            order = coupling_tensor.ndim
+            if order == 0:
+                continue
+            spin_sign = (-1) ** order
+            non_zero_indices = np.transpose(np.nonzero(coupling_tensor))
+            for index_tuple in non_zero_indices:
+                index_tuple = tuple(int(i) for i in index_tuple)
+
+                # skip repeated indices
+                if len(set(index_tuple)) != len(index_tuple):
+                    continue
+                # keep only strictly increasing tuples i1 < i2 < ... < ik
+                if index_tuple != tuple(sorted(index_tuple)):
+                    continue
+                coeff = coupling_tensor[index_tuple]
+                if coeff == 0:
+                    continue
+
+                term = qml.PauliZ(index_tuple[0])
+                for q in index_tuple[1:]:
+                    term = term @ qml.PauliZ(q)
+                coeffs.append(sign * spin_sign * float(coeff))
+                obs.append(term)
+
+        return qml.Hamiltonian(coeffs, obs)
+
+    def get_mixer_hamiltonian(self):
+        """Constructs the Mixer Hamiltonian: Σ X_i."""
+        return qml.Hamiltonian([1.0] * self.n_qubits, [qml.PauliX(i) for i in range(self.n_qubits)])
+
+    def get_state_vector(self, s: str) -> str:
+        """Return the state vector."""
+        # Coefficients
+        alpha = self.model.calculate_alpha(couplings=self.local_couplings)
+        coeff_mixer = self.gamma
+        coeff_problem = -(1 - self.gamma) * alpha
+
+        H_total = qml.Hamiltonian([coeff_mixer] + [1.0], [self.get_mixer_hamiltonian(), self.get_problem_hamiltonian(couplings=self.local_couplings, sign=coeff_problem)])
+
+        @qml.qnode(self.dev)
+        def quantum_evolution(input_string):
+            for i, bit in enumerate(input_string):
+                if bit == "1":
+                    qml.PauliX(i)
+            qml.ApproxTimeEvolution(H_total, self.time, self.num_trotter_steps)
+            return qml.state()
+
+        state_vector = quantum_evolution(s)
+        return state_vector
+
+    def get_sample_from_state_vector(self, s: str) -> str:
+        """Returns a single sampled bitstring s' using the quantum distribution."""
+        # Get the full state vector probabilities
+        state_vector = self.get_state_vector(s)  # This returns the complex amplitudes
+        probs = np.abs(state_vector) ** 2
+
+        # Sample one index based on the probabilities
+        n_states = len(probs)
+        idx = np.random.choice(n_states, p=probs)
+
+        # Convert that index back to a bitstring (e.g., 3 -> "011")
+        s_prime = np.binary_repr(idx, width=self.model.n)
+        return s_prime
+
+    def get_sample(self, s: str):
+        """Returns a measured sample after time evolution"""
+        # Coefficients
+        alpha = self.model.calculate_alpha(n=self.spin_length, couplings=self.local_couplings)
+        coeff_mixer = self.gamma
+        coeff_problem = -(1 - self.gamma) * alpha
+
+        H_total = qml.Hamiltonian([coeff_mixer] + [1.0], [self.get_mixer_hamiltonian(), self.get_problem_hamiltonian(couplings=self.local_couplings, sign=coeff_problem)])
+
+        @qml.qnode(self.dev, shots=1)
+        def quantum_evolution(input_string):
+            for i, bit in enumerate(input_string):
+                if bit == "1":
+                    qml.PauliX(i)
+            qml.ApproxTimeEvolution(H_total, self.time, self.num_trotter_steps)
+            return qml.sample()
+
+        # Get the first shot from the sample
+        sample = quantum_evolution(s)[0]  # pennylane update doesnt squeeze singletons anymore
+        bitstring = "".join(str(int(b)) for b in sample)
+        return bitstring
+
+    def update(self, s, subgroup_choice, local_couplings, gamma, time) -> str:
+        """
+        Performs time evolution on coarse grained hamiltonian update to get s' from s
+        """
+        self._assert_bitstring(s)
+        self.gamma = gamma
+        self.time = time
+        self.local_couplings = local_couplings
+        self.spin_length = len(subgroup_choice)
+
+        # Get s_cg' for the subgroup and reconstruct full s' using s and s_cg'
+        s_cg = "".join([s[i] for i in subgroup_choice])
+        s_cg_prime = self.get_sample(s_cg)
+
+        s_list = list(s)
+        for i, global_index in enumerate(subgroup_choice):
+            s_list[global_index] = s_cg_prime[i]
+
+        return "".join(s_list)
+
+    def _assert_bitstring(self, s, *, length=None):
+        # Accept numpy strings etc.
+        if not isinstance(s, str):
+            raise TypeError(f"bitstring must be of type str, got {type(s)}: {s!r}")
+
+        if length is not None and len(s) != length:
+            raise ValueError(f"bitstring must have length {length}, got {len(s)}: {s!r}")
+
+        bad = set(s) - {"0", "1"}
+        if bad:
+            raise ValueError(f"bitstring must contain only '0'/'1'. Bad chars: {bad}. Value: {s!r}")
+
+        return s

qemcmc/coarse_grain.py

@@ -0,0 +1,28 @@
+# Internal
+from qemcmc.utils.helpers import validate_subgroups
+
+# External
+import numpy as np
+
+
+class CoarseGraining:
+    def __init__(self, n, subgroups=None, subgroup_probs=None):
+        if subgroups is None:
+            used = False
+            subgroups = [list(range(n))]
+            subgroup_probs = [1.0]
+        else:
+            used = True
+            if subgroup_probs is None:
+                subgroup_probs = [1.0 / len(subgroups)] * len(subgroups)
+
+        validate_subgroups(subgroups=subgroups, subgroup_probs=subgroup_probs, n_spins=n)
+
+        self.n = n
+        self.subgroups = subgroups
+        self.subgroup_probs = subgroup_probs
+        self.used = used
+
+    def sample(self, rng=np.random):
+        idx = rng.choice(len(self.subgroups), p=self.subgroup_probs)
+        return self.subgroups[idx]

qemcmc/main.py

@@ -0,0 +1,78 @@
+# Internal
+from qemcmc.sampler import ClassicalMCMC, QeMCMC
+from qemcmc.utils import ModelMaker, MCMCChain
+
+# External
+from matplotlib import pyplot as plt
+from joblib import Parallel, delayed
+
+
+if __name__ == "__main__":
+
+    def plot_chains(chains: list[MCMCChain], color: str, label: str):
+        for chain in chains:
+            energies = chain.get_current_energy_array()
+            pos = chain.get_pos_array()
+            plt.plot(pos, energies, color=color, alpha=0.3)
+        avg_energy = sum(chain.get_current_energy_array() for chain in chains) / len(chains)
+        plt.plot(pos, avg_energy, color=color, label=f"Average {label}")
+
+    n = 15
+    steps = 300
+    reps = 10
+    model_type = "Fully Connected Ising"
+    model_type2 = "Coarse Grained Ising"
+    name = "Test Ising model"
+
+    model_maker = ModelMaker(n, model_type2, name)
+    model = model_maker.model
+    cg = model_maker.cg
+
+    temp = 0.1
+    initial_states = model.initial_state
+
+    uni_chains = []
+    for rep in range(reps):
+        classical_uniform_MCMC = ClassicalMCMC(model, temp, method="uniform")
+        uni_chain = classical_uniform_MCMC.run(
+            steps,
+            initial_state=initial_states[rep],
+            name="classical uniform MCMC",
+            verbose=True,
+            sample_frequency=1,
+        )
+        uni_chains.append(uni_chain)
+    plot_chains(uni_chains, "orange", "classical uniform MCMC")
+
+    loc_chains = []
+    for rep in range(reps):
+        classical_local_MCMC = ClassicalMCMC(model, temp, method="local")
+        loc_chain = classical_local_MCMC.run(
+            steps,
+            initial_state=initial_states[rep],
+            name="classical local MCMC",
+            verbose=True,
+            sample_frequency=1,
+        )
+        loc_chains.append(loc_chain)
+    plot_chains(loc_chains, "lightgreen", "classical local MCMC")
+
+    def run_qemcmc(rep):
+        qemcmc = QeMCMC(model, gamma=(0.3, 0.6), time=(2, 20), temp=temp, coarse_graining=cg)
+        return qemcmc.run(
+            steps,
+            initial_state=initial_states[rep],
+            name="QeMCMC",
+            verbose=True,
+            sample_frequency=1,
+        )
+
+    Qe_chains = Parallel(n_jobs=-1)(delayed(run_qemcmc)(rep) for rep in range(reps))
+    plot_chains(Qe_chains, "lightblue", "QeMCMC")
+
+    plt.xlabel("MCMC step")
+    plt.ylabel("Energy")
+    plt.title("MCMC chains")
+    plt.legend()
+    plt.show()
+    # plt.savefig("plots/MCMC_chains.png")

qemcmc/model/__init__.py

@@ -0,0 +1,4 @@
+from .energy_model import EnergyModel
+
+
+__all__ = ["EnergyModel"]

qemcmc/model/energy_model.py

@@ -0,0 +1,328 @@
+import itertools
+import typing
+from typing import List
+import numpy as np
+
+
+class EnergyModel:
+    """
+    A base class for energy models for a classical energy function over n spins,
+    defined by arbitrary-order coupling tensors.
+
+    Parameters
+    ----------
+    n:
+        Number of spins
+    couplings:
+        List of numpy arrays representing interaction tensors. A 1D array encodes linear terms,
+        a 2D array encodes pairwise terms (expected symmetric), and higher-rank tensors encode
+        higher-order interactions.
+    name:
+        Optional label for the model (used in plotting / logging).
+    cost_function_signs:
+        Sign convention(s) used by downstream components (e.g. proposal/acceptance conventions).
+
+    Notes
+    -----
+    - Energies are computed by mapping binary states ``{0,1}`` to spin values ``{-1,+1}`` internally.
+    - Brute-force methods such as ``get_all_energies`` scale as O(2^n) and are intended only for
+      small systems.
+    """
+
+    def __init__(
+        self,
+        n: int,
+        couplings: List[np.ndarray] = [],
+        name: str = None,
+        cost_function_signs: list = [-1, -1],
+    ):
+        self.n = n
+        self.n_spins = n
+        self.couplings = couplings
+        self.name = name
+        self.alpha = self.calculate_alpha(n, couplings)
+        self.cost_function_signs = cost_function_signs
+        self.initial_state = []
+
+        for i in range(100):
+            self.initial_state.append("".join(str(i) for i in np.random.randint(0, 2, self.n, dtype=int)))
+
+    def calculate_energy(self, state, couplings, spin_type="binary", sign=1):
+        """
+        Calculate the energy of a given state for an arbitrary-order Ising/QUBO model.
+
+        Parameters:
+        -----------
+            state : array-like (str, list, tuple, np.array)
+                State configuration. Can be:
+                - Binary: "011", [0,1,1], (0,1,1), etc. (uses values 0 and 1 directly)
+                - Spin: [-1,1,1], (-1,1,1), etc. (uses values -1 and +1 directly)
+
+            couplings : list of numpy arrays
+                List of coupling tensors where:
+                - 1D arrays represent linear terms (h_i)
+                - 2D arrays represent quadratic terms (J_ij)
+                - 3D arrays represent cubic terms, etc.
+
+            spin_type : str, optional (default='binary')
+                - 'binary': state uses 0/1 values
+                - 'spin': state uses -1/+1 values
+                Note: The actual values in 'state' are used directly in the calculations
+
+        Returns:
+        --------
+            float : Total energy of the state
+        """
+        if isinstance(state, str):
+            state = np.array([int(bit) for bit in state])
+        else:
+            state = np.array(state)
+
+        if spin_type == "binary":
+            state = 2 * state - 1
+
+        total_energy = 0.0
+        for coupling in couplings:
+            coupling = np.array(coupling)
+            order = coupling.ndim
+
+            if order == 1:
+                total_energy += np.dot(coupling, state)
+            elif order == 2:
+                total_energy += np.einsum("ij, i, j->", coupling, state, state)
+            else:
+                # General case for any order >=3 (cubic, quartic etc.)
+                indices = "".join(chr(97 + i) for i in range(order))  # 'abc...', 'ijkl...'
+                einsum_str = f"{indices}," + ",".join([indices[i] for i in range(order)]) + "->"
+                total_energy += np.einsum(einsum_str, coupling, *([state] * order))
+
+        return sign * total_energy
+
+    def get_subgroup_couplings(self, subgroup: List[int], current_state: str):
+        """
+        Calculates local couplings for a subgroup.
+        Spins outside the group are treated as frozen constants.
+        """
+        n_sub = len(subgroup)
+        subgroup_set = set(subgroup)
+        g_to_l = {g_idx: l_idx for l_idx, g_idx in enumerate(subgroup)}
+
+        # Map bitstring '0'/'1' to spin values -1/+1
+        state_vals = np.array([1 if b == "1" else -1 for b in current_state])
+        max_order = max(c.ndim for c in self.couplings)
+        new_couplings = [np.zeros((n_sub,) * d) for d in range(1, max_order + 1)]
+
+        for coupling in self.couplings:
+            for indices in np.ndindex(coupling.shape):
+                coeff = coupling[indices]
+                if coeff == 0 or len(set(indices)) != len(indices):
+                    continue
+
+                in_group = [i for i in indices if i in subgroup_set]
+                out_group = [i for i in indices if i not in subgroup_set]
+
+                # Multiply coefficient by values of fixed spins outside the subgroup
+                multiplier = np.prod(state_vals[out_group])
+                effective_coeff = coeff * multiplier
+
+                if in_group:
+                    new_order = len(in_group)
+                    local_indices = tuple(g_to_l[i] for i in in_group)
+                    new_couplings[new_order - 1][local_indices] += effective_coeff
+
+        return new_couplings
+
+    def calculate_alpha(self, n, couplings, eps: float = 1e-15) -> float:
+        """
+        Compute alpha = sqrt(n) / sqrt(sum of squares of UNIQUE coupling coefficients),
+        assuming coupling tensors are symmetric representations.
+
+        Any non-symmetric 2-body input raises ValueError.
+
+        Parameters
+        ----------
+        couplings : list[np.ndarray] | None
+            Couplings to use. Defaults to self.couplings.
+        eps : float
+            Small threshold to avoid division by zero.
+
+        Returns
+        -------
+        float : alpha
+        """
+        if couplings is None:
+            couplings = self.couplings
+
+        norm_sq = 0.0
+
+        for T in couplings:
+            T = np.asarray(T)
+            order = T.ndim
+
+            if order == 0:
+                continue
+
+            # 1-body: h_i
+            if order == 1:
+                if T.shape != (n,):
+                    raise ValueError(f"1-body tensor has shape {T.shape}, expected ({n},)")
+                for i in range(n):
+                    c = float(T[i])
+                    norm_sq += c * c
+                continue
+
+            # 2-body: symmetric J
+            if order == 2:
+                if T.shape != (n, n):
+                    raise ValueError(f"2-body tensor has shape {T.shape}, expected ({n},{n})")
+
+                # Enforce symmetry (rejects pure upper/lower triangular)
+                if not np.allclose(T, T.T):
+                    raise ValueError("Non-symmetric J provided. This alpha function only accepts symmetric J.")
+
+                # Count each interaction once: i<j
+                for i in range(n):
+                    for j in range(i + 1, n):
+                        c = float(T[i, j])
+                        if c != 0.0:
+                            norm_sq += c * c
+                continue
+
+            # Order >= 3: count each unordered interaction once using i1<i2<...<ik
+            if T.shape != (n,) * order:
+                raise ValueError(f"{order}-body tensor has shape {T.shape}, expected {(n,) * order}")
+
+            for comb in itertools.combinations(range(n), order):
+                c = float(T[comb])
+                if c != 0.0:
+                    norm_sq += c * c
+
+        if norm_sq < eps:
+            raise ValueError("Cannot compute alpha: no nonzero (non-constant) couplings found.")
+
+        return np.sqrt(n / norm_sq)
+
+    def get_energy(self, state: str) -> float:
+        """
+        Returns the energy of a given state
+        """
+        if not isinstance(state, str):
+            raise TypeError(f"State must be a string, but got {type(state)}")
+        energy = self.calculate_energy(state, self.couplings)
+        return energy
+
+    def get_all_energies(self) -> np.ndarray:
+        """
+        Calculate the energies for all possible spin states.
+        This method generates all possible spin states for the
+        system and calculates the energy for each state.
+
+        Returns
+        -------
+            np.ndarray: An array containing the energies of all possible spin states.
+        """
+        self.S = ["".join(i) for i in itertools.product("01", repeat=self.n)]
+        all_energies = np.zeros(len(self.S))
+        for state in self.S:
+            all_energies[int(state, 2)] = self.calculate_energy(state, self.couplings)
+        return all_energies
+
+    def get_lowest_energies(self, num_states: int) -> typing.Tuple[np.ndarray, np.ndarray]:
+        """
+        Retrieve the lowest energy states and their degeneracies.
+        This method computes all possible energies and then finds the specified number
+        of lowest energy states along with their degeneracies. Note that this method
+        is intended for small instances due to its brute-force nature, which is extremely
+        memory intensive and slow.
+        Args:
+            num_states (int): The number of lowest energy states to retrieve.
+        Returns:
+            Two numpy arrays:
+                - The first array contains the lowest energy values.
+                - The second array contains the degeneracies of the corresponding energy values.
+        """
+        # only to be used for small instances, it is just brute force so extremely memory intensive and slow
+        all_energies = self.get_all_energies()
+
+        # very slow (sorts whole array)
+        self.lowest_energies, self.lowest_energy_degeneracy = self.find_lowest_values(all_energies, num_values=num_states)
+
+        return self.lowest_energies, self.lowest_energy_degeneracy
+
+    def find_lowest_values(self, arr: np.ndarray, num_values: int = 5):
+        """
+        Find the lowest unique values in an array and their degeneracies.
+
+        Args:
+            arr (np.ndarray): The input array from which to find the lowest values.
+            num_values (int, optional): The number of lowest unique values to find. Defaults to 5.
+
+        Returns:
+        tuple: A tuple containing two numpy arrays:
+            - lowest_values (np.ndarray): The lowest unique values in the array.
+            - degeneracy (np.ndarray): The counts of each of the lowest unique values.
+        """
+        # Count the occurrences of each value
+        unique_values, counts = np.unique(arr, return_counts=True)
+        # Sort the unique values and counts by value
+        sorted_indices = np.argsort(unique_values)
+        unique_values_sorted = unique_values[sorted_indices]
+        counts_sorted = counts[sorted_indices]
+        # Find the first num_values
+        lowest_values = unique_values_sorted[:num_values]
+        degeneracy = counts_sorted[:num_values]
+        return lowest_values, degeneracy
+
+    def get_lowest_energy(self):
+        """
+        Calculate and return the lowest energy from all possible energies.
+        This method uses a brute force approach to find the lowest energy,
+        making it extremely memory intensive and slow. It is recommended
+        to use this method only for small instances.
+        Returns:
+            float: The lowest energy value.
+        Notes:
+            If the lowest energy has already been calculated and stored
+            in `self.lowest_energy`, it will return that value directly
+            to save computation time.
+        """
+
+        # Only to be used for small instances, it is just brute force so extremely memory intensive and slow
+        if self.lowest_energy is not None:
+            return self.lowest_energy
+        else:
+            all_energies = self.get_all_energies()
+
+        lowest_energy = np.min(all_energies)
+
+        return lowest_energy
+
+    def get_boltzmann_factor(self, state: str, beta: float = 1.0) -> float:
+        """
+        Get un-normalised boltzmann probability of a given state
+
+        Args:
+            state (str): configuration of spins for which probability is to be calculated
+            beta (float): inverse temperature (1/T) at which the probability is to be calculated.
+
+        Returns:
+            float corresponding to the un-normalised boltzmann probability of the given state.
+        """
+        E = self.get_energy(state)
+        r = np.exp(-1 * beta * E, dtype=np.longdouble)
+
+        return r
+
+    def get_boltzmann_factor_from_energy(self, E, beta: float = 1.0) -> float:
+        """
+        Get un-normalized Boltzmann probability for a given energy.
+
+        Args:
+            E (float): Energy for which the Boltzmann factor is to be calculated.
+            beta (float): Inverse temperature (1/T) at which the probability is to be calculated.
+
+        Returns:
+            float: The un-normalized Boltzmann probability for the given energy.
+        """
+
+        return np.exp(-1 * beta * E, dtype=np.longdouble)

qemcmc/sampler/__init__.py

@@ -0,0 +1,6 @@
+from .mcmc import MCMC
+from .classical_mcmc import ClassicalMCMC
+from .qe_mcmc import QeMCMC
+
+
+__all__ = ["MCMC", "ClassicalMCMC", "QeMCMC"]