loqs 1.1__py3-none-any.whl

loqs/__init__.py

@@ -0,0 +1,25 @@
+#####################################################################################################################
+# Logical Qubit Simulator (LoQS) v. 1.1                                                                             #
+# Copyright 2026 National Technology & Engineering Solutions of Sandia, LLC (NTESS).                                #
+# Under the terms of Contract DE-NA0003525 with NTESS, the U.S. Government retains certain rights in this software. #
+# 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 or in the LICENSE file in the root LoQS directory.                     #
+#####################################################################################################################
+
+"""Logical Qubit Simulator (LoQS)
+
+A simulator for logical qubits with arbitrary noise and flexible QEC code definitions
+"""
+
+# Import first (most dependencies)
+from . import internal
+
+# Import before core
+from . import backends
+
+from . import core
+
+# Import after core
+from . import codepacks
+from . import tools

loqs/backends/__init__.py

@@ -0,0 +1,224 @@
+#####################################################################################################################
+# Logical Qubit Simulator (LoQS) v. 1.1                                                                             #
+# Copyright 2026 National Technology & Engineering Solutions of Sandia, LLC (NTESS).                                #
+# Under the terms of Contract DE-NA0003525 with NTESS, the U.S. Government retains certain rights in this software. #
+# 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 or in the LICENSE file in the root LoQS directory.                     #
+#####################################################################################################################
+
+"""Quantum simulation backends for LoQS
+
+There are three kinds of backends in LoQS: [](api:backends.circuit),
+[](api:backends.model), and [](api:backends.state).
+
+!!! warning
+
+    For backends that depend on optional third-party packages,
+    it is recommended to not import from the module/class file directly.
+    Instead, try to import from `loqs.backends`, which dynamically checks
+    if that backend is available using the below methods.
+
+Examples
+--------
+>>> from loqs.backends import get_available_backends
+>>> list_of_backends = get_available_backends()
+"""
+
+from typing import TYPE_CHECKING, Any
+from importlib import import_module
+from dataclasses import dataclass
+
+from .reps import RepEnum, GateRep, InstrumentRep, RepTuple
+
+from .circuit import BasePhysicalCircuit, ListPhysicalCircuit
+from .model import BaseNoiseModel, DictNoiseModel, TimeDependentBaseNoiseModel
+from .state import BaseQuantumState, NumpyStatevectorQuantumState
+from .state.basestate import OutcomeDict
+
+
+@dataclass
+class BackendAvailability:
+    """Dataclass to track backend availability"""
+
+    name: str
+    """Backend name"""
+    available: bool
+    """Whether the backend is available or not"""
+    error: str | None = None
+    """Error message when trying to import the backend"""
+
+
+# Backend availability tracking
+_backend_availability: dict[str, BackendAvailability] = {}
+
+
+def _check_backend_availability(backend_name: str, import_path: str) -> bool:
+    """Check if a backend is available and update availability tracking"""
+    try:
+        import_module(import_path)
+        _backend_availability[backend_name] = BackendAvailability(
+            backend_name, True
+        )
+        return True
+    except ImportError as e:
+        _backend_availability[backend_name] = BackendAvailability(
+            backend_name, False, str(e)
+        )
+        return False
+
+
+def get_available_backends() -> list[str]:
+    """Get list of available backend names"""
+    return [
+        name
+        for name, avail in _backend_availability.items()
+        if avail.available
+    ]
+
+
+def is_backend_available(backend_name: str) -> bool:
+    """Check if a specific backend is available"""
+    return _backend_availability.get(
+        backend_name, BackendAvailability(backend_name, False)
+    ).available
+
+
+def get_backend_error(backend_name: str) -> str | None:
+    """Get the error message for an unavailable backend"""
+    return _backend_availability.get(
+        backend_name, BackendAvailability(backend_name, False)
+    ).error
+
+
+# Check availability of all backends at import time
+_check_backend_availability("pygsti_circuit", "pygsti")
+_check_backend_availability("pygsti_model", "pygsti")
+_check_backend_availability("stim_circuit", "stim")
+_check_backend_availability("stim_state", "stim")
+_check_backend_availability("qsim_state", "quantumsim")
+
+
+# Import concrete backend classes with conditional availability
+def __getattr__(name: str) -> Any:
+    """Lazy import of backend classes based on availability"""
+    if name == "PyGSTiPhysicalCircuit":
+        if is_backend_available("pygsti_circuit"):
+            from .circuit.pygsticircuit import PyGSTiPhysicalCircuit
+
+            return PyGSTiPhysicalCircuit
+        else:
+            raise ImportError(
+                f"PyGSTi circuit backend is not available. "
+                f"Error: {get_backend_error('pygsti_circuit')}"
+            )
+    elif name == "STIMPhysicalCircuit":
+        if is_backend_available("stim_circuit"):
+            from .circuit.stimcircuit import STIMPhysicalCircuit
+
+            return STIMPhysicalCircuit
+        else:
+            raise ImportError(
+                f"STIM circuit backend is not available. "
+                f"Error: {get_backend_error('stim_circuit')}"
+            )
+    elif name == "PyGSTiNoiseModel":
+        if is_backend_available("pygsti_model"):
+            from .model.pygstimodel import PyGSTiNoiseModel
+
+            return PyGSTiNoiseModel
+        else:
+            raise ImportError(
+                f"PyGSTi model backend is not available. "
+                f"Error: {get_backend_error('pygsti_model')}"
+            )
+    elif name == "STIMQuantumState":
+        if is_backend_available("stim_state"):
+            from .state.stimstate import STIMQuantumState
+
+            return STIMQuantumState
+        else:
+            raise ImportError(
+                f"STIM state backend is not available. "
+                f"Error: {get_backend_error('stim_state')}"
+            )
+    elif name == "QSimQuantumState":
+        if is_backend_available("qsim_state"):
+            from .state.qsimstate import QSimQuantumState
+
+            return QSimQuantumState
+        else:
+            raise ImportError(
+                f"QSim backend is not available. "
+                f"Error: {get_backend_error('qsim')}"
+            )
+
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+def propagate_state(
+    circuit: BasePhysicalCircuit,
+    model: BaseNoiseModel,
+    state: BaseQuantumState,
+    inplace: bool = True,
+) -> tuple[BaseQuantumState, OutcomeDict]:
+    """Given a circuit and model, propagate a state forward in time.
+
+    This is a wrapper for [](api:BaseNoiseModel.get_reps)
+    and [](api:BaseQuantumState.apply_reps_inplace) (or
+    the non-inplace version if `inplace=False`).
+    It does also try to find compatible reptypes by
+    searching for a match in output reps from `model`
+    and input reps from `state`.
+
+    Parameters
+    ----------
+    circuit:
+        The circuit to run
+
+    model:
+        The noise model to use to convert circuit operations
+        into representations the state can apply
+
+    state:
+        The state to move forward in time
+
+    inplace:
+        Whether to modify the state in-place (`True`, default)
+        or propagate a copy forward (`False`).
+        This should probably remain `True` for memory reasons.
+
+    Returns
+    -------
+    BaseQuantumState, OutcomeDict
+        The output of [](api:BaseQuantumState.apply_reps).
+        If `inplace=True`, then the state is also returned
+        to provide a consistent API.
+    """
+    # Find a compatible model/state oprep
+    opreps = []
+    for oprep in model.output_gate_reps:
+        if oprep in state.input_reps:
+            opreps.append(oprep)
+    assert (
+        len(opreps) > 0
+    ), "Could not find matching gate rep between model output and state input"
+
+    instreps = []
+    for instrep in model.output_instrument_reps:
+        if instrep in state.input_reps:
+            instreps.append(instrep)
+    assert (
+        len(instreps) > 0
+    ), "Could not find matching instrument rep between model output and state input"
+
+    # Look up reps from model
+    reps = model.get_reps(circuit, list(opreps), list(instreps))
+
+    # Apply operator reps to state
+    if inplace:
+        outcomes = state.apply_reps_inplace(reps)
+    else:
+        state, outcomes = state.apply_reps(reps)
+
+    return state, outcomes

loqs/backends/circuit/__init__.py

@@ -0,0 +1,120 @@
+#####################################################################################################################
+# Logical Qubit Simulator (LoQS) v. 1.1                                                                             #
+# Copyright 2026 National Technology & Engineering Solutions of Sandia, LLC (NTESS).                                #
+# Under the terms of Contract DE-NA0003525 with NTESS, the U.S. Government retains certain rights in this software. #
+# 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 or in the LICENSE file in the root LoQS directory.                     #
+#####################################################################################################################
+
+"""Circuit backend classes.
+
+For LoQS, a circuit is essentially a list of layers that are lists of gate names and target qubits.
+Qubit labels are assumed to be either a `str` or `int`.
+
+The circuit backend interface is enforced by the abstract [](api:BasePhysicalCircuit) class,
+which generally has the capabilities:
+
+- Property getters for:
+    - The underlying circuit
+    - Circuit depth
+    - Qubit labels
+- Append circuit (in-place and copy)
+- Delete qubits (in-place and copy)
+- Insert circuit (in-place and copy)
+- Map qubit labels (in-place and copy)
+- Merge, i.e. layer combination (in-place and copy)
+- Set qubit labels (in-place and copy)
+
+The packages currently available as circuit backends:
+
+- Native `list` via [](api:ListPhysicalCircuit)
+- `pygsti` via [](api:PyGSTiPhysicalCircuit) (requires `loqs[pygsti]`)
+- `stim` via [](api:STIMPhysicalCircuit) (requires `loqs[stim]`)
+
+!!! warning
+
+    For backends that depend on optional third-party packages,
+    it is recommended to not import from the module/class file directly.
+    Instead, try to import from [](api:loqs.backends), which dynamically checks
+    if that backend is available.
+
+Examples
+--------
+
+Below use syndrome extraction circuits for the surface code
+as an example for how to generate complex tiled circuits
+from simple templates.
+
+TODO: This should probably be shifted to a codepack?
+Here we generate the syndrome extraction circuit
+for Surface-17 based on [@tomita_lowdistance_2014].
+
+>>> from loqs.backends import PyGSTiPhysicalCircuit as PhysCirc
+>>> X_template = PhysCirc([('Gh', 'aux'), ('Gcnot', 'aux', 'b'),
+...     ('Gcnot', 'aux', 'a'), ('Gcnot', 'aux', 'd'),
+...     ('Gcnot', 'aux', 'c'), ('Gh', 'aux'), ('Iz', 'aux')],
+...     qubit_labels=['a', 'b', 'c', 'd', 'aux']
+... ) # Fig 2a
+>>> Z_template = PhysCirc([[], ('Gcnot', 'b', 'aux'),
+...     ('Gcnot', 'a', 'aux'), ('Gcnot', 'd', 'aux'),
+...     ('Gcnot', 'c', 'aux'), [], ('Iz','aux')],
+...     qubit_labels=['a', 'b', 'c', 'd', 'aux']
+... ) # Fig 2b (with idle layers to match X check H layers)
+>>> qubits = [f"D{i}" for i in range(9)] + [f"A{i}" for i in range(9, 17)]
+>>> X_syndrome = PhysCirc.from_circuit_tiling(
+...     X_template,
+...     qubits,
+...     [
+...         [None, None, "D1", "D2" , "A9"],
+...         ["D0", "D1", "D3", "D4", "A11"],
+...         ["D4", "D5", "D7", "D8", "A14"],
+...         ["D6", "D7", None, None, "A16"],
+...     ],
+...     merge_offsets=0 # Can all overlap
+... )
+>>> Z_syndrome = PhysCirc.from_circuit_tiling(
+...     Z_template,
+...     qubits,
+...     [
+...             [None, "D0", None, "D3", "A10"],
+...             ["D1", "D2", "D4", "D5", "A12"],
+...             ["D3", "D4", "D6", "D7", "A13"],
+...             ["D5", None, "D8", None, "A15"],
+...     ],
+...     merge_offsets=0 # Can all overlap
+... )
+>>> full_syndrome = X_syndrome.merge(Z_syndrome, 0)
+>>> print(full_syndrome)
+Physical pyGSTi circuit:
+  Qubit D0  ---|  |-|CA10|-|TA11|-|    |-|    |-|  |-|  |---
+  Qubit D1  ---|  |-|TA11|-|CA12|-|    |-|TA9 |-|  |-|  |---
+  Qubit D2  ---|  |-|CA12|-|    |-|TA9 |-|    |-|  |-|  |---
+  Qubit D3  ---|  |-|    |-|CA13|-|CA10|-|TA11|-|  |-|  |---
+  Qubit D4  ---|  |-|CA13|-|TA14|-|TA11|-|CA12|-|  |-|  |---
+  Qubit D5  ---|  |-|TA14|-|CA15|-|CA12|-|    |-|  |-|  |---
+  Qubit D6  ---|  |-|    |-|TA16|-|    |-|CA13|-|  |-|  |---
+  Qubit D7  ---|  |-|TA16|-|    |-|CA13|-|TA14|-|  |-|  |---
+  Qubit D8  ---|  |-|    |-|    |-|TA14|-|CA15|-|  |-|  |---
+  Qubit A9  ---|Gh|-|    |-|    |-|CD2 |-|CD1 |-|Gh|-|Iz|---
+  Qubit A10 ---|  |-|TD0 |-|    |-|TD3 |-|    |-|  |-|Iz|---
+  Qubit A11 ---|Gh|-|CD1 |-|CD0 |-|CD4 |-|CD3 |-|Gh|-|Iz|---
+  Qubit A12 ---|  |-|TD2 |-|TD1 |-|TD5 |-|TD4 |-|  |-|Iz|---
+  Qubit A13 ---|  |-|TD4 |-|TD3 |-|TD7 |-|TD6 |-|  |-|Iz|---
+  Qubit A14 ---|Gh|-|CD5 |-|CD4 |-|CD8 |-|CD7 |-|Gh|-|Iz|---
+  Qubit A15 ---|  |-|    |-|TD5 |-|    |-|TD8 |-|  |-|Iz|---
+  Qubit A16 ---|Gh|-|CD7 |-|CD6 |-|    |-|    |-|Gh|-|Iz|---
+<BLANKLINE>
+>>> print(repr(full_syndrome))
+Physical pyGSTi circuit: \
+Circuit([Gh:A9Gh:A11Gh:A14Gh:A16][Gcnot:A11:D1Gcnot:A14:D5Gcnot:A16:D7\
+Gcnot:D0:A10Gcnot:D2:A12Gcnot:D4:A13][Gcnot:A11:D0Gcnot:A14:D4Gcnot:A16:D6\
+Gcnot:D1:A12Gcnot:D3:A13Gcnot:D5:A15][Gcnot:A9:D2Gcnot:A11:D4Gcnot:A14:D8\
+Gcnot:D3:A10Gcnot:D5:A12Gcnot:D7:A13][Gcnot:A9:D1Gcnot:A11:D3Gcnot:A14:D7\
+Gcnot:D4:A12Gcnot:D6:A13Gcnot:D8:A15][Gh:A9Gh:A11Gh:A14Gh:A16]\
+[Iz:A9Iz:A11Iz:A14Iz:A16Iz:A10Iz:A12Iz:A13Iz:A15]\
+@(D0,D1,D2,D3,D4,D5,D6,D7,D8,A9,A10,A11,A12,A13,A14,A15,A16))
+"""
+
+from .basecircuit import BasePhysicalCircuit
+from .listcircuit import ListPhysicalCircuit