feat: Scalar serialization and pyzx interop

.pre-commit-config.yaml

@@ -70,3 +70,10 @@ repos:
         language: system
         files: \.py$
         pass_filenames: false
+      - id: cargo-doc
+        name: cargo doc
+        description: Generate documentation with `cargo doc`.
+        entry: cargo doc --no-deps --all-features --workspace
+        language: system
+        files: \.rs$
+        pass_filenames: false

pybindings/Cargo.toml

@@ -14,4 +14,7 @@ crate-type = ["cdylib"]
 [dependencies]
 quizx = { workspace = true }
 num = { workspace = true }
-pyo3 = { workspace = true, features = ["extension-module"] }
+pyo3 = { workspace = true, features = ["extension-module", "num-complex"] }
+derive_more = { workspace = true }
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }

pybindings/quizx/__init__.py

@@ -1,10 +1,10 @@
-from . import _quizx
+from . import _quizx, simplify
 from .graph import VecGraph
 from .circuit import Circuit
-from . import simplify
 from .decompose import Decomposer
+from ._quizx import Scalar
 
-__all__ = ["VecGraph", "Circuit", "simplify", "Decomposer"]
+__all__ = ["VecGraph", "Circuit", "simplify", "Decomposer", "Scalar"]
 
 
 def extract_circuit(g):

pybindings/quizx/_quizx.pyi

@@ -1,9 +1,39 @@
 # Type stubs for the Rust bindings
 
 from typing import final
+from builtins import complex as complex_
+
+@final
+class Scalar:
+    @staticmethod
+    def complex(complex: complex_) -> Scalar: ...
+    @staticmethod
+    def real(real: float) -> Scalar: ...
+    @staticmethod
+    def from_phase(phase: float) -> Scalar: ...
+    @staticmethod
+    def from_int_coeffs(coeffs: list[int]) -> Scalar: ...
+    @staticmethod
+    def one_plus_phase(phase: float) -> Scalar: ...
+    @staticmethod
+    def sqrt2_pow(n: int) -> Scalar: ...
+    def complex_value(self) -> complex_: ...
+    def mul_sqrt2_pow(self, n: int) -> Scalar: ...
+    def mul_phase(self, phase: float) -> Scalar: ...
+    @staticmethod
+    def zero() -> Scalar: ...
+    @staticmethod
+    def one() -> Scalar: ...
+    def is_zero(self) -> bool: ...
+    def is_one(self) -> bool: ...
+    def conjugate(self) -> Scalar: ...
+    def to_json(self) -> str: ...
+    @staticmethod
+    def from_json(json: str) -> Scalar: ...
 
 @final
 class VecGraph:
+    scalar: Scalar
     def vindex(self) -> int: ...
     def neighbor_at(self, v: int, n: int) -> int: ...
     def num_vertices(self) -> int: ...
@@ -60,6 +90,7 @@ class CircuitStats:
 
 @final
 class Decomposer:
+    scalar: Scalar
     @staticmethod
     def empty() -> Decomposer: ...
     def __init__(self, g: VecGraph) -> None: ...

pybindings/quizx/decompose.py

@@ -2,6 +2,8 @@
 
 from . import _quizx
 from .graph import VecGraph
+from .scalar import from_pyzx_scalar, to_pyzx_scalar
+from pyzx.graph.scalar import Scalar
 
 
 class Decomposer(object):
@@ -30,3 +32,11 @@ def decomp_all(self):
 
     def decomp_until_depth(self, depth: int):
         self._d.decomp_until_depth(depth)
+
+    @property
+    def scalar(self) -> Scalar:
+        return to_pyzx_scalar(self._d.scalar)
+
+    @scalar.setter
+    def scalar(self, s: Scalar):
+        self._d.scalar = from_pyzx_scalar(s)

pybindings/quizx/graph.py

@@ -14,10 +14,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from .scalar import from_pyzx_scalar, to_pyzx_scalar
 from fractions import Fraction
 from typing import Tuple, Dict, Any, Optional
 from pyzx.graph.base import BaseGraph  # type: ignore
 from pyzx.utils import VertexType, EdgeType  # type: ignore
+from pyzx.graph.scalar import Scalar
 
 from . import _quizx
 
@@ -315,3 +317,11 @@ def num_outputs(self):
 
     def set_outputs(self, outputs):
         self._g.set_outputs(list(outputs))
+
+    @property
+    def scalar(self) -> Scalar:
+        return to_pyzx_scalar(self._g.scalar)
+
+    @scalar.setter
+    def scalar(self, s: Scalar):
+        self._g.scalar = from_pyzx_scalar(s)

pybindings/quizx/scalar.py

@@ -0,0 +1,14 @@
+"""Utilities for interfacing `quizx::Scalar` with `pyzx.Scalar`."""
+
+from ._quizx import Scalar as QuizxScalar
+from pyzx.graph.scalar import Scalar as PyzxScalar
+
+
+def from_pyzx_scalar(s: PyzxScalar) -> QuizxScalar:
+    """Convert a `pyzx.Scalar` to a `quizx::Scalar`."""
+    return QuizxScalar.from_json(s.to_json())
+
+
+def to_pyzx_scalar(s: QuizxScalar) -> PyzxScalar:
+    """Convert a `pyzx.Scalar` to a `quizx::Scalar`."""
+    return PyzxScalar.from_json(s.to_json())

pybindings/src/lib.rs

@@ -1,3 +1,7 @@
+pub mod scalar;
+
+use crate::scalar::Scalar;
+
 use num::Rational64;
 use pyo3::prelude::*;
 use pyo3::wrap_pyfunction;
@@ -16,6 +20,7 @@ fn _quizx(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<Circuit>()?;
     m.add_class::<CircuitStats>()?;
     m.add_class::<Decomposer>()?;
+    m.add_class::<Scalar>()?;
     Ok(())
 }
 
@@ -290,6 +295,18 @@ impl VecGraph {
     fn set_outputs(&mut self, outputs: Vec<V>) {
         self.g.set_outputs(outputs)
     }
+
+    /// Returns the graph scalar.
+    #[getter]
+    fn get_scalar(&self) -> Scalar {
+        self.g.scalar().clone().into()
+    }
+
+    /// Sets the graph scalar.
+    #[setter]
+    fn set_scalar(&mut self, scalar: Scalar) {
+        *self.g.scalar_mut() = scalar.into();
+    }
 }
 
 #[pyclass]
@@ -313,6 +330,16 @@ impl Decomposer {
         }
     }
 
+    #[getter]
+    fn get_scalar(&self) -> Scalar {
+        self.d.scalar.clone().into()
+    }
+
+    #[setter]
+    fn set_scalar(&mut self, scalar: Scalar) {
+        self.d.scalar = scalar.into();
+    }
+
     fn graphs(&self) -> PyResult<Vec<VecGraph>> {
         let mut gs = vec![];
         for (_a, g) in &self.d.stack {