Generic QRE model for neutral atoms.

source/pip/qsharp/qre/application/magnets/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+# flake8: noqa F403
+# pyright: ignore[reportWildcardImportFromLibrary]
+
+"""Magnets application module.
+
+Re-exports from the submodules."""
+
+from .geometry import *
+from .models import *
+from .trotter import *
+from .utilities import *

source/pip/qsharp/qre/application/magnets/geometry/__init__.py

@@ -0,0 +1,22 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Geometry module for representing quantum system topologies.
+
+This module provides hypergraph data structures for representing the
+geometric structure of quantum systems, including lattice topologies
+and interaction graphs.
+"""
+
+from .complete import CompleteBipartiteGraph, CompleteGraph
+from .lattice1d import Chain1D, Ring1D
+from .lattice2d import Patch2D, Torus2D
+
+__all__ = [
+    "CompleteBipartiteGraph",
+    "CompleteGraph",
+    "Chain1D",
+    "Ring1D",
+    "Patch2D",
+    "Torus2D",
+]

source/pip/qsharp/qre/application/magnets/geometry/complete.py

@@ -0,0 +1,150 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Complete graph geometries for quantum simulations.
+
+This module provides classes for representing complete graphs and complete
+bipartite graphs as hypergraphs. These structures are useful for quantum
+systems with all-to-all or bipartite all-to-all interactions.
+"""
+
+from ..utilities import (
+    Hyperedge,
+    Hypergraph,
+    HypergraphEdgeColoring,
+)
+
+
+class CompleteGraph(Hypergraph):
+    """A complete graph where every vertex is connected to every other vertex.
+
+    In a complete graph K_n, there are n vertices and n(n-1)/2 edges,
+    with each pair of distinct vertices connected by exactly one edge.
+
+    Attributes:
+        n: Number of vertices in the graph.
+
+    Example:
+
+    .. code-block:: python
+        >>> graph = CompleteGraph(4)
+        >>> graph.nvertices
+        4
+        >>> graph.nedges
+        6
+    """
+
+    def __init__(self, n: int, self_loops: bool = False) -> None:
+        """Initialize a complete graph.
+
+        Args:
+            n: Number of vertices in the graph.
+            self_loops: If True, include self-loop edges on each vertex
+                for single-site terms.
+        """
+        if self_loops:
+            _edges = [Hyperedge([i]) for i in range(n)]
+        else:
+            _edges = []
+
+        # Add all pairs of vertices
+        for i in range(n):
+            for j in range(i + 1, n):
+                _edges.append(Hyperedge([i, j]))
+        super().__init__(_edges)
+
+        self.n = n
+
+    def edge_coloring(self) -> HypergraphEdgeColoring:
+        """Compute edge coloring for this complete graph."""
+        coloring = HypergraphEdgeColoring(self)
+        for edge in self.edges():
+            if len(edge.vertices) == 1:
+                coloring.add_edge(edge, -1)
+            else:
+                if self.n % 2 == 0:
+                    i, j = edge.vertices
+                    m = self.n - 1
+                    if j == m:
+                        coloring.add_edge(edge, i)
+                    elif (j - i) % 2 == 0:
+                        coloring.add_edge(edge, (j - i) // 2)
+                    else:
+                        coloring.add_edge(edge, (j - i + m) // 2)
+                else:
+                    m = self.n
+                    i, j = edge.vertices
+                    if (j - i) % 2 == 0:
+                        coloring.add_edge(edge, (j - i) // 2)
+                    else:
+                        coloring.add_edge(edge, (j - i + m) // 2)
+        return coloring
+
+
+class CompleteBipartiteGraph(Hypergraph):
+    """A complete bipartite graph with two vertex sets.
+
+    In a complete bipartite graph K_{m,n} (m <= n), there are m + n
+    vertices partitioned into two sets of sizes m and n. Every vertex
+    in the first set is connected to every vertex in the second set,
+    giving m * n edges total.
+
+    Vertices 0 to m-1 form the first set, and vertices m to m+n-1
+    form the second set.
+
+    Attributes:
+        m: Number of vertices in the first set.
+        n: Number of vertices in the second set.
+
+    Requires:
+        m <= n
+
+    Example:
+
+    .. code-block:: python
+        >>> graph = CompleteBipartiteGraph(2, 3)
+        >>> graph.nvertices
+        5
+        >>> graph.nedges
+        6
+    """
+
+    def __init__(self, m: int, n: int, self_loops: bool = False) -> None:
+        """Initialize a complete bipartite graph.
+
+        Args:
+            m: Number of vertices in the first set (vertices 0 to m-1).
+            n: Number of vertices in the second set (vertices m to m+n-1).
+            self_loops: If True, include self-loop edges on each vertex
+                for single-site terms.
+        """
+        assert m <= n, "Require m <= n for CompleteBipartiteGraph."
+        total_vertices = m + n
+
+        if self_loops:
+            _edges = [Hyperedge([i]) for i in range(total_vertices)]
+
+        else:
+            _edges = []
+
+        # Connect every vertex in first set to every vertex in second set
+        for i in range(m):
+            for j in range(m, m + n):
+                _edges.append(Hyperedge([i, j]))
+        super().__init__(_edges)
+
+        self.m = m
+        self.n = n
+
+    def edge_coloring(self) -> HypergraphEdgeColoring:
+        """Compute edge coloring for this complete bipartite graph."""
+        coloring = HypergraphEdgeColoring(self)
+        m = self.m
+        n = self.n
+        for edge in self.edges():
+            if len(edge.vertices) == 1:
+                coloring.add_edge(edge, -1)
+            else:
+                i, j = edge.vertices
+                coloring.add_edge(edge, (i + j - m) % n)
+        return coloring

source/pip/qsharp/qre/application/magnets/geometry/lattice1d.py

@@ -0,0 +1,123 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""One-dimensional lattice geometries for quantum simulations.
+
+This module provides classes for representing 1D lattice structures as
+hypergraphs. These lattices are commonly used in quantum spin chain
+simulations and other one-dimensional quantum systems.
+"""
+
+from ..utilities import (
+    Hyperedge,
+    Hypergraph,
+    HypergraphEdgeColoring,
+)
+
+
+class Chain1D(Hypergraph):
+    """A one-dimensional open chain lattice.
+
+    Represents a linear chain of vertices with nearest-neighbor edges.
+    The chain has open boundary conditions, meaning the first and last
+    vertices are not connected.
+
+    Attributes:
+        length: Number of vertices in the chain.
+
+    Example:
+
+    .. code-block:: python
+        >>> chain = Chain1D(4)
+        >>> chain.nvertices
+        4
+        >>> chain.nedges
+        3
+    """
+
+    def __init__(self, length: int, self_loops: bool = False) -> None:
+        """Initialize a 1D chain lattice.
+
+        Args:
+            length: Number of vertices in the chain.
+            self_loops: If True, include self-loop edges on each vertex
+                for single-site terms.
+        """
+        if self_loops:
+            _edges = [Hyperedge([i]) for i in range(length)]
+
+        else:
+            _edges = []
+
+        for i in range(length - 1):
+            _edges.append(Hyperedge([i, i + 1]))
+
+        super().__init__(_edges)
+        self.length = length
+
+    def edge_coloring(self) -> HypergraphEdgeColoring:
+        """Compute a valid edge coloring for this chain."""
+        coloring = HypergraphEdgeColoring(self)
+        for edge in self.edges():
+            if len(edge.vertices) == 1:
+                coloring.add_edge(edge, -1)
+            else:
+                i, j = edge.vertices
+                color = min(i, j) % 2
+                coloring.add_edge(edge, color)
+        return coloring
+
+
+class Ring1D(Hypergraph):
+    """A one-dimensional ring (periodic chain) lattice.
+
+    Represents a circular chain of vertices with nearest-neighbor edges.
+    The ring has periodic boundary conditions, meaning the first and last
+    vertices are connected.
+
+    Attributes:
+        length: Number of vertices in the ring.
+
+    Example:
+
+    .. code-block:: python
+        >>> ring = Ring1D(4)
+        >>> ring.nvertices
+        4
+        >>> ring.nedges
+        4
+    """
+
+    def __init__(self, length: int, self_loops: bool = False) -> None:
+        """Initialize a 1D ring lattice.
+
+        Args:
+            length: Number of vertices in the ring.
+            self_loops: If True, include self-loop edges on each vertex
+                for single-site terms.
+        """
+        if self_loops:
+            _edges = [Hyperedge([i]) for i in range(length)]
+        else:
+            _edges = []
+
+        for i in range(length):
+            _edges.append(Hyperedge([i, (i + 1) % length]))
+        super().__init__(_edges)
+
+        self.length = length
+
+    def edge_coloring(self) -> HypergraphEdgeColoring:
+        """Compute a valid edge coloring for this ring."""
+        coloring = HypergraphEdgeColoring(self)
+        for edge in self.edges():
+            if len(edge.vertices) == 1:
+                coloring.add_edge(edge, -1)
+            else:
+                i, j = edge.vertices
+                if {i, j} == {0, self.length - 1}:
+                    color = (self.length % 2) + 1
+                else:
+                    color = min(i, j) % 2
+                coloring.add_edge(edge, color)
+        return coloring