qaravan 0.1.0__tar.gz

qaravan-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 Faisal Alam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

qaravan-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: qaravan
+Version: 0.1.0
+Summary: Unified classical simulation of noiseless and noisy quantum circuits
+Author: Faisal Alam
+Author-email: mfalam2@illinois.edu
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: numpy>=2.2.4
+Requires-Dist: scipy>=1.15.2
+Requires-Dist: matplotlib>=3.10.1
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: ncon>=2.0.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

qaravan-0.1.0/README.md

@@ -0,0 +1,11 @@
+# Qaravan
+
+**Qaravan** is a Python library for simulating quantum circuits with and without noise using a variety of classical simulation techniques. 
+
+## Overview
+
+Qaravan is organized into two main submodules
+
+**tensorQ**: contains simulators based on tensor contraction: statevector, density matrix, matrix product states and matrix product density operators
+
+**algebraQ**: contains simulators based on algebraic methods: Clifford, matchgate, Pauli path propagation and Lie algebraic simulation (in development)

qaravan-0.1.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"

qaravan-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

qaravan-0.1.0/setup.py

@@ -0,0 +1,19 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="qaravan",
+    packages=find_packages(where="src"),
+    python_requires='>=3.11',
+    package_dir={"": "src"},
+    version="0.1.0", 
+    author="Faisal Alam",
+    author_email="mfalam2@illinois.edu",
+    description="Unified classical simulation of noiseless and noisy quantum circuits",
+    install_requires=[
+    "numpy>=2.2.4",
+    "scipy>=1.15.2",
+    "matplotlib>=3.10.1",
+    "tqdm>=4.67.1",
+    "ncon>=2.0.0"
+    ]
+)

qaravan-0.1.0/src/qaravan/__init__.py

@@ -0,0 +1 @@
+__version__ = '0.1.0'

qaravan-0.1.0/src/qaravan/algebraQ/__init__.py

@@ -0,0 +1 @@
+from .matchgate_sim import *

qaravan-0.1.0/src/qaravan/algebraQ/matchgate_sim.py

@@ -0,0 +1,273 @@
+import numpy as np
+from qaravan.core import BaseSim, pauli_I, pauli_X, pauli_Y, pauli_Z
+from functools import reduce
+from scipy.linalg import block_diag
+import re
+
+def is_special_orthogonal(mat): 
+    return bool(np.allclose(np.dot(mat.T, mat), np.eye(mat.shape[0])) and np.allclose(np.dot(mat, mat.T), np.eye(mat.shape[0])) 
+            and np.isclose(np.linalg.det(mat), 1.0))
+
+def is_special_unitary(mat): 
+    return bool(np.allclose(np.dot(mat.T.conj(), mat), np.eye(mat.shape[0])) and np.allclose(np.dot(mat, mat.T.conj()), np.eye(mat.shape[0])) 
+            and np.isclose(np.linalg.det(mat), 1.0))
+
+def random_su2():
+    x = np.random.randn(4)
+    x = x / np.linalg.norm(x)
+    a = x[0] + 1j*x[1]
+    b = x[2] + 1j*x[3]
+    return np.array([[a, -b.conj()],
+                     [b,  a.conj()]], dtype=complex)
+
+def matchgate_from_blocks(A,B): 
+    G = np.zeros((4, 4), dtype=complex)
+    G[0, 0] = A[0,0]
+    G[0, 3] = A[0,1]
+    G[3, 0] = A[1,0]
+    G[3, 3] = A[1,1]
+    G[1, 1] = B[0,0]
+    G[1, 2] = B[0,1]
+    G[2, 1] = B[1,0]
+    G[2, 2] = B[1,1]
+    return G
+
+def random_matchgate():
+    A = random_su2()
+    B = random_su2()
+    return matchgate_from_blocks(A, B)
+
+def generate_majorana_ops(n):
+    majorana_ops = []
+    for i in range(n): 
+        kron_list = [pauli_Z] * i + [pauli_X] + [pauli_I] * (n - i - 1)
+        op = reduce(np.kron, kron_list)
+        majorana_ops.append(op)
+
+        kron_list = [pauli_Z] * i + [pauli_Y] + [pauli_I] * (n - i - 1)
+        op = reduce(np.kron, kron_list)
+        majorana_ops.append(op)
+
+    return majorana_ops
+
+def generate_R(n, U, indices): 
+    majorana_ops = generate_majorana_ops(2)
+    m_indices = np.arange(2*indices[0], 2*indices[1]+2)
+
+    R = np.eye(2*n, dtype=complex)
+    for i, ml in zip(m_indices, majorana_ops):
+        for j, mr in zip(m_indices, majorana_ops):
+            R[i,j] = np.trace(mr @ U @ ml @ U.conj().T)/(2**2)
+
+    Rp = np.array([R.T[2*i,:] + 1j*R.T[2*i+1,:] for i in range(n)])
+    assert is_special_orthogonal(R), "R is not special orthogonal"
+    return R, Rp
+
+def circuit_to_R(circ): 
+    R = np.eye(2*circ.num_sites, dtype=complex)
+    for gate in circ.gate_list:
+        if gate.name == "SWAP":
+            mats = [pauli_I, pauli_X, pauli_Y, pauli_Z]
+            ch = np.random.choice(np.arange(4))
+            mat = mats[ch]
+            matrix = np.kron(mat, mat)
+        elif gate.name == "M":
+            matrix = gate.matrix 
+        else: 
+            raise ValueError(f"Unsupported gate: {gate.name}")
+        
+        r, _ = generate_R(circ.num_sites, matrix, gate.indices)
+        R = R @ r
+
+    Rp = np.array([R.T[2*i,:] + 1j*R.T[2*i+1,:] for i in range(circ.num_sites)])
+    return R, Rp
+
+def generate_labels(instring, outstring):
+    in_labels = []
+    for i, bit in enumerate(instring):
+        if bit == '1':  
+            in_labels.append(f'gamma_{2*i}')
+
+    out_labels = []
+    for i, bit in enumerate(outstring):
+        if bit == '0':  
+            out_labels.append(f'gamma_m{i}')
+            out_labels.append(f'gamma_n{i}')
+        elif bit == '1':
+            out_labels.append(f'gamma_n{i}')
+            out_labels.append(f'gamma_m{i}')
+
+    return in_labels + out_labels + in_labels[::-1]
+ 
+def parse_label(label):
+    m = re.match(r"gamma_([nm]?)(\d+)", label)
+    if not m:
+        raise ValueError(f"Label '{label}' does not match expected pattern.")
+    kind = m.group(1)
+    if kind == "":
+        kind = "gamma"  # bare gamma, use its number directly
+    idx = int(m.group(2))
+    return kind, idx
+
+def get_entry(Rp, H, label_i, label_j):
+    kind_i, idx_i = parse_label(label_i)
+    kind_j, idx_j = parse_label(label_j)
+
+    if kind_i == 'm' and kind_j == 'm':
+        return (Rp @ H @ Rp.T)[idx_i, idx_j]  # gamma_mi, gamma_mj
+    
+    elif kind_i == 'm' and kind_j == 'n':
+        return (Rp @ H @ Rp.conj().T)[idx_i, idx_j] # gamma_mi, gamma_nj
+    
+    elif kind_i == 'm' and kind_j == 'gamma': 
+        return (Rp @ H)[idx_i, idx_j]
+    
+    elif kind_i == 'n' and kind_j == 'm':
+        return (Rp.conj() @ H @ Rp.T)[idx_i, idx_j]
+    
+    elif kind_i == 'n' and kind_j == 'n':
+        return (Rp.conj() @ H @ Rp.conj().T)[idx_i, idx_j]
+    
+    elif kind_i == 'n' and kind_j == 'gamma':
+        return (Rp.conj() @ H)[idx_i, idx_j]
+    
+    elif kind_i == 'gamma' and kind_j == 'm':
+        return (H @ Rp.T)[idx_i, idx_j]
+    
+    elif kind_i == 'gamma' and kind_j == 'n':
+        return (H @ Rp.conj().T)[idx_i, idx_j]
+    
+    elif kind_i == 'gamma' and kind_j == 'gamma':
+        return int(idx_i == idx_j)
+    
+    else:
+        raise ValueError(f"Invalid labels: {label_i}, {label_j}")
+    
+def exp_mat(n, labels, Rp): 
+    H = block_diag(*[np.array([[1,1j], [-1j,1]])] * n)
+    mat = np.zeros((len(labels), len(labels)), dtype=complex)
+    for i, label_i in enumerate(labels):
+        for j, label_j in enumerate(labels):
+            if i < j:
+                mat[i,j] = get_entry(Rp, H, label_i, label_j)
+            elif i > j:
+                mat[i,j] = -mat[j,i]
+
+    return mat
+
+def probability(instring, outstring, circ): 
+    n = len(instring) 
+    num_measured_qubits = len([bit for bit in outstring if bit != 'i'])
+
+    labels = generate_labels(instring, outstring)
+    _, Rp = circuit_to_R(circ)
+    mat = exp_mat(n, labels, Rp)
+
+    norm = 2**(2*num_measured_qubits)
+    return  (np.sqrt(np.linalg.det(mat))/norm).real
+
+def sample(instring, circ, epsilon=0.0): 
+    s = ''
+    prev_probs = [1.0]
+    for i in range(circ.num_sites):
+        outstring = s + '0' + 'i'*(circ.num_sites - i - 1)   
+        p = probability(instring, outstring, circ) + np.random.normal(0, epsilon)
+        if np.random.rand() < p/prev_probs[-1]: 
+            s += '0'  
+            normalizer = p
+        else: 
+            s += '1'
+            normalizer = prev_probs[-1] - p
+        prev_probs.append(normalizer)
+        
+    return s 
+
+class MatchgateSimH(BaseSim):
+    def __init__(self, circ, init_state=None):
+        super().__init__(circ, init_state=init_state, nm=None)
+
+    def initialize_state(self):
+        """ internal state is a SO(2n) matrix, where n is the number of sites """
+        self.state = np.eye(2*self.num_sites, dtype=complex)
+        self.instring = '0' * self.num_sites if self.init_state is None else self.init_state
+
+    def generate_R(self, gate): 
+        U, indices = gate.matrix, gate.indices
+        majorana_ops = generate_majorana_ops(2)
+        m_indices = np.arange(2*indices[0], 2*indices[1]+2)
+
+        R = np.eye(2*self.num_sites, dtype=complex)
+        for i, ml in zip(m_indices, majorana_ops):
+            for j, mr in zip(m_indices, majorana_ops):
+                R[i,j] = np.trace(mr @ U @ ml @ U.conj().T)/(2**2)
+
+        assert is_special_orthogonal(R), "R is not special orthogonal"
+        return R
+
+    def apply_gate(self, gate):
+        R = self.generate_R(gate)
+        self.state = R @ self.state
+
+    def probability(self, outstring): 
+        n = self.num_sites
+        num_measured_qubits = len([bit for bit in outstring if bit != 'i'])
+
+        labels = generate_labels(self.instring, outstring)
+        R = self.state
+        Rp = np.array([R.T[2*i,:] + 1j*R.T[2*i+1,:] for i in range(self.num_sites)])
+        mat = exp_mat(n, labels, Rp)
+
+        norm = 2**(2*num_measured_qubits)
+        return  (np.sqrt(np.linalg.det(mat))/norm).real
+    
+    def sample(self): 
+        s = ''
+        prev_probs = [1.0]
+        for i in range(self.num_sites):
+            outstring = s + '0' + 'i'*(self.num_sites - i - 1)
+            p = self.probability(outstring)
+            if np.random.rand() < p/prev_probs[-1]: 
+                s += '0'  
+                normalizer = p
+            else: 
+                s += '1'
+                normalizer = prev_probs[-1] - p
+            prev_probs.append(normalizer)
+            
+        return s 
+
+class MatchgateSimS(BaseSim):
+    def __init__(self, circ, init_state=None):
+        super().__init__(circ, init_state=init_state, nm=None)  
+
+    def initialize_state(self):
+        """ 
+        internal state is a covariance matrix, which is a 2n x 2n matrix where n is the number of sites
+        init_state can be provided as a bitstring or a covariance matrix
+        """
+        if self.init_state is None: 
+            summands = [np.array([[0,-1], [1,0]]) for i in range(self.num_sites)]
+            self.state = block_diag(*summands)
+
+        elif type(self.init_state) == str:
+            mat = np.array([[0,-1], [1,0]])
+            # summand will have mat or -mat on the diagonal depending on the bitstring
+            summands = [-mat if b == '1' else mat for b in self.init_state]
+            self.state = block_diag(*summands)
+
+        elif type(self.init_state) == np.ndarray:
+            self.state = self.init_state 
+
+        else:
+            raise ValueError("init_state must be either a covariance matrix or a bitstring.")
+        
+    def apply_gate(self, gate):
+        gammas = [np.kron(pauli_X, pauli_I), np.kron(pauli_Y, pauli_I), np.kron(pauli_Z, pauli_X), 
+                  np.kron(pauli_Z, pauli_Y)]
+        rot_matrix = np.array([[0.5 * np.trace(gamma1 @ gate.matrix.conj().T @ gamma2 @ gate.matrix) 
+                               for gamma2 in gammas] for gamma1 in gammas])
+        summands = [np.eye(2) for i in range(self.num_sites)]
+        summands[gate.indices[0]] = rot_matrix
+        summands.remove(gate.indices[1])
+        full_rot_matrix = block_diag(*summands)
+        self.state = full_rot_matrix @ self.state @ full_rot_matrix.conj().T

qaravan-0.1.0/src/qaravan/core/__init__.py

@@ -0,0 +1,9 @@
+from .noise import *
+from .gates import *
+from .paulis import *
+from .utils import *
+from .base_sim import *
+from .lattices import *
+from .hamiltonians import *
+from .circuits import *
+from .compilers import *

qaravan-0.1.0/src/qaravan/core/base_sim.py

@@ -0,0 +1,53 @@
+from tqdm import tqdm
+
+class BaseSim:
+    """ 
+    accepts Circuit object and Noise object 
+    different simulators use different representations of quantum state
+    and different methods for applying gates and measurements
+    """
+
+    def __init__(self, circ, init_state=None, nm=None):
+        self.circ = circ
+        self.num_sites = circ.num_sites
+        self.local_dim = circ.local_dim
+        self.nm = nm
+        self.init_state = init_state
+        self.state = None
+
+    def initialize_state(self):
+        raise NotImplementedError("must be implemented by child classes.")
+
+    def apply_gate(self, gate):
+        raise NotImplementedError("must be implemented by child classes.")
+
+    def run(self, progress_bar=True, debug=0):
+        """
+        progress_bar: If True, display a progress bar during simulation.
+        debug: If 1, prints intermediate state after each layer.
+        debug: If 2, prints intermediate state after each gate.
+        """
+        self.initialize_state()
+        circ = self.circ.build(self.nm) if not self.circ.built else self.circ
+        layers = tqdm(circ.layers) if progress_bar else circ.layers
+
+        for layer in layers:
+            for gate in layer:
+                self.apply_gate(gate)
+                if debug == 2:
+                    print(self)
+            
+            if debug == 1:
+                print(self)
+
+        if circ.meas_sites is not None:
+            self.measure(circ.meas_sites)
+
+        return self.state
+    
+    def measure(self, meas_sites):
+        raise NotImplementedError("must be implemented by child classes.")
+
+    def __str__(self):
+        """ pretty prints the state """
+        raise NotImplementedError("must be implemented by child classes.")

qaravan-0.1.0/src/qaravan/core/circuits.py

@@ -0,0 +1,147 @@
+from .gates import ID, SuperOp
+from .noise import gate_time, ThermalNoise
+import numpy as np
+import copy
+from functools import reduce 
+
+class Circuit:
+    def __init__(self, gate_list, n=None, meas_sites=None):
+        self.gate_list = gate_list
+        sites = np.concatenate([gate.indices for gate in gate_list])
+        self.num_sites = int(max(sites) + 1) if n is None else n
+        self.local_dim = gate_list[0].get_local_dim()
+        self.layers = None
+        self.built = False
+        self.meas_sites = meas_sites
+        
+    def update_gate(self, gate_idx, new_array): 
+        self.gate_list[gate_idx].matrix = new_array
+        if self.layers is not None:
+            self.construct_layers()
+        
+    def decompose(self, basis='ZSX'): 
+        gate_list = []
+        for gate in self.gate_list:
+            if gate.name == "U" and gate.angles is not None:
+                decomposed_gates = gate.decompose(basis)
+                gate_list.extend(decomposed_gates)
+            else:
+                gate_list.append(gate)
+
+        self.gate_list = gate_list
+        
+    def construct_layers(self): 
+        layers = []
+        for gate in self.gate_list:
+            place_available = True
+            layer_ind = len(layers) - 1
+
+            # first we find the oldest layer that fails to commute with current gate
+            while place_available and layer_ind >= 0:
+                g_indices = set(gate.indices)
+                existing_indices = {ind for gate in layers[layer_ind] for ind in gate.indices}
+                if g_indices.intersection(existing_indices): 
+                    place_available = False
+                else: 
+                    layer_ind -= 1
+
+            # then we add current gate to the following layer
+            if layer_ind < len(layers) - 1: 
+                layers[layer_ind + 1].append(gate)
+            else: 
+                layers.append([gate])
+
+        self.layers = layers
+    
+    def add_noise(self, nm): 
+        layers = []
+        for layer in self.layers: 
+            if not any(isinstance(obj, SuperOp) for obj in layer):
+                if isinstance(nm, ThermalNoise): 
+                    layer_time = max([gate_time(gate, nm) for gate in layer])
+                    active_qubits = set(np.concatenate([gate.indices for gate in layer]))
+                    idle_qubits = set(range(self.num_sites)) - active_qubits
+                    noise_layer = [ID(nm.local_dim, layer_time, i, nm=nm, dd=(i in idle_qubits))
+                                    for i in range(self.num_sites)] 
+                    
+                else: 
+                    noise_layer = [ID(2, 0.0, [i for i in range(self.num_sites)], nm=nm)] 
+                
+                layer.extend(noise_layer)
+                layers.append(layer)
+            else: 
+                layers.append(layer)
+        
+        self.layers = layers
+        
+    def build(self, nm=None): 
+        """ note that this returns a new circuit instance built with provided noise model
+        and leaves the current circuit instance unchanged """
+        new_circ = copy.deepcopy(self)
+        new_circ.decompose()
+        new_circ.construct_layers()
+        if nm is not None: 
+            new_circ.add_noise(nm)
+        
+        new_circ.built = True    
+        return new_circ
+    
+    def add_meas(self, meas_sites): 
+        self.meas_sites = meas_sites
+        
+    def dag(self): 
+        gate_list = [g.dag() for g in self.gate_list[::-1]]
+        return Circuit(gate_list, self.num_sites)
+        
+    def to_matrix(self): 
+        return circ_to_mat(self)
+        
+    def __str__(self): 
+        if self.layers is not None: 
+            full_str = []
+            for layer in self.layers:
+                layer_str = " \n".join([str(gate) for gate in layer])
+                full_str.append(layer_str)
+            full_str = " \n\n".join(full_str)
+            return full_str
+        
+        else: 
+            return " \n".join([str(gate) for gate in self.gate_list])  
+        
+    def draw(self): # TODO 
+        """ use svgwrite to visualize the circuit """
+        return None
+
+def compose_circuits(circ_list): 
+    gate_list = [circ.gate_list for circ in circ_list]
+    gate_list = [gate for sublist in gate_list for gate in sublist]
+    return Circuit(gate_list, n=circ_list[0].num_sites)
+
+def circ_to_mat(circ, n=None): 
+    if circ.layers == None: 
+        circ.construct_layers()
+    n = circ.num_sites if n is None else n
+    
+    layer_mats = []    
+    for layer in circ.layers: 
+        missing_indices = set(range(n)) - set(np.concatenate([gate.indices for gate in layer]))
+        for index in missing_indices: 
+            layer.append(ID(circ.local_dim, 0.0, [index]))
+        
+        sorted_layer = sorted(layer, key=lambda gate: gate.indices[0])
+        mat_list = [gate.matrix for gate in sorted_layer]
+        layer_mats.append(reduce(np.kron, mat_list))
+        
+    return np.linalg.multi_dot(layer_mats[::-1]) if len(layer_mats) > 1 else layer_mats[0]
+
+def shift_gate_list(circ, start_site):
+    """ return a new gate list with all gate indices shifted by start_site."""
+    def _shifted_gate(gate, start_site):
+        new_gate = copy.deepcopy(gate)
+        new_gate.indices = np.array(gate.indices) + start_site
+        return new_gate
+    
+    return [
+        _shifted_gate(gate, start_site)
+        for gate in circ.gate_list
+    ]