hugr 0.1.0a1__tar.gz

hugr-0.1.0a1/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.1
+Name: hugr
+Version: 0.1.0a1
+Summary: Quantinuum's common representation for quantum programs
+Home-page: https://github.com/CQCL/hugr
+License: Apache-2.0
+Author: TKET development team
+Author-email: tket-support@cambridgequantum.com
+Maintainer: TKET development team
+Maintainer-email: tket-support@cambridgequantum.com
+Requires-Python: >=3.10
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: pydantic (>=2.6.4,<3.0.0)
+Project-URL: Repository, https://github.com/CQCL/hugr
+Description-Content-Type: text/markdown
+
+hugr
+===============
+
+[![build_status][]](https://github.com/CQCL/hugr/actions)
+[![codecov][]](https://codecov.io/gh/CQCL/hugr)
+
+The Hierarchical Unified Graph Representation (HUGR, pronounced _hugger_) is the
+common representation of quantum circuits and operations in the Quantinuum
+ecosystem.
+
+This library provides a pure-python implementation of the HUGR data model, and
+a low-level API for constructing HUGR objects.
+
+This library is intended to be used as a dependency for other high-level tools.
+See [`guppylang`][] and [`tket2`][] for examples of such tools.
+
+The HUGR specification is [here](https://github.com/CQCL/hugr/blob/main/specification/hugr.md).
+
+  [`guppylang`]: https://pypi.org/project/guppylang/
+  [`tket2`]: https://github.com/CQCL/tket2
+
+
+## Installation
+
+The package name is `hugr`. It can be installed from PyPI:
+```bash
+pip install hugr
+```
+
+The current releases are in alpha stage, and the API is subject to change.
+
+## Usage
+
+TODO
+
+## Recent Changes
+
+TODO
+
+## Development
+
+TODO
+
+## License
+
+This project is licensed under Apache License, Version 2.0 ([LICENSE][] or http://www.apache.org/licenses/LICENSE-2.0).
+
+  [build_status]: https://github.com/CQCL/hugr/actions/workflows/ci-py.yml/badge.svg?branch=main
+  [codecov]: https://img.shields.io/codecov/c/gh/CQCL/hugr?logo=codecov
+  [LICENSE]: https://github.com/CQCL/hugr/blob/main/LICENCE
+  [CHANGELOG]: https://github.com/CQCL/hugr/blob/main/hugr-py/CHANGELOG.md
+

hugr-0.1.0a1/README.md

@@ -0,0 +1,51 @@
+hugr
+===============
+
+[![build_status][]](https://github.com/CQCL/hugr/actions)
+[![codecov][]](https://codecov.io/gh/CQCL/hugr)
+
+The Hierarchical Unified Graph Representation (HUGR, pronounced _hugger_) is the
+common representation of quantum circuits and operations in the Quantinuum
+ecosystem.
+
+This library provides a pure-python implementation of the HUGR data model, and
+a low-level API for constructing HUGR objects.
+
+This library is intended to be used as a dependency for other high-level tools.
+See [`guppylang`][] and [`tket2`][] for examples of such tools.
+
+The HUGR specification is [here](https://github.com/CQCL/hugr/blob/main/specification/hugr.md).
+
+  [`guppylang`]: https://pypi.org/project/guppylang/
+  [`tket2`]: https://github.com/CQCL/tket2
+
+
+## Installation
+
+The package name is `hugr`. It can be installed from PyPI:
+```bash
+pip install hugr
+```
+
+The current releases are in alpha stage, and the API is subject to change.
+
+## Usage
+
+TODO
+
+## Recent Changes
+
+TODO
+
+## Development
+
+TODO
+
+## License
+
+This project is licensed under Apache License, Version 2.0 ([LICENSE][] or http://www.apache.org/licenses/LICENSE-2.0).
+
+  [build_status]: https://github.com/CQCL/hugr/actions/workflows/ci-py.yml/badge.svg?branch=main
+  [codecov]: https://img.shields.io/codecov/c/gh/CQCL/hugr?logo=codecov
+  [LICENSE]: https://github.com/CQCL/hugr/blob/main/LICENCE
+  [CHANGELOG]: https://github.com/CQCL/hugr/blob/main/hugr-py/CHANGELOG.md

hugr-0.1.0a1/pyproject.toml

@@ -0,0 +1,32 @@
+[tool.poetry]
+classifiers = [
+    "Environment :: Console",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+]
+name = "hugr"
+version = "0.1.0a1"
+description = "Quantinuum's common representation for quantum programs"
+#keywords = []
+authors = ["TKET development team <tket-support@cambridgequantum.com>"]
+maintainers = ["TKET development team <tket-support@cambridgequantum.com>"]
+license = "Apache-2.0"
+readme = "README.md"
+homepage = "https://github.com/CQCL/hugr"
+repository = "https://github.com/CQCL/hugr"
+
+[tool.poetry.dependencies]
+python = ">=3.10"
+pydantic = "^2.6.4"
+
+[tool.pytest.ini_options]
+# Lark throws deprecation warnings for `src_parse` and `src_constants`.
+filterwarnings = "ignore::DeprecationWarning:lark.*"

hugr-0.1.0a1/src/hugr/__init__.py

@@ -0,0 +1,8 @@
+"""`hugr` is a Python package for the Quantinuum HUGR common
+representation.
+"""
+
+
+def it_works() -> str:
+    """Return a string to confirm that the package is installed and working."""
+    return "It works!"

hugr-0.1.0a1/src/hugr/serialization/__init__.py

@@ -0,0 +1,3 @@
+from .serial_hugr import SerialHugr
+
+__all__ = ["SerialHugr"]

hugr-0.1.0a1/src/hugr/serialization/ops.py

@@ -0,0 +1,557 @@
+import inspect
+import sys
+from abc import ABC
+from typing import Any, Literal, cast
+
+from pydantic import BaseModel, Field, RootModel
+
+from . import tys
+from .tys import (
+    ExtensionId,
+    ExtensionSet,
+    FunctionType,
+    PolyFuncType,
+    Type,
+    TypeRow,
+)
+
+NodeID = int
+
+
+class BaseOp(ABC, BaseModel):
+    """Base class for ops that store their node's input/output types"""
+
+    # Parent node index of node the op belongs to, used only at serialization time
+    parent: NodeID
+    input_extensions: ExtensionSet = Field(default_factory=ExtensionSet)
+
+    def insert_port_types(self, in_types: TypeRow, out_types: TypeRow) -> None:
+        """Hook to insert type information from the input and output ports into the
+        op"""
+
+    def insert_child_dfg_signature(self, inputs: TypeRow, outputs: TypeRow) -> None:
+        """Hook to insert type information from a child dataflow graph"""
+
+    def display_name(self) -> str:
+        """Name of the op for visualisation"""
+        return self.__class__.__name__
+
+
+# ----------------------------------------------------------
+# --------------- Module level operations ------------------
+# ----------------------------------------------------------
+
+
+class Module(BaseOp):
+    """The root of a module, parent of all other `ModuleOp`s."""
+
+    op: Literal["Module"] = "Module"
+
+
+class FuncDefn(BaseOp):
+    """A function definition. Children nodes are the body of the definition."""
+
+    op: Literal["FuncDefn"] = "FuncDefn"
+
+    name: str
+    signature: PolyFuncType = Field(default_factory=PolyFuncType.empty)
+
+    def insert_port_types(self, in_types: TypeRow, out_types: TypeRow) -> None:
+        assert len(in_types) == 0
+        assert len(out_types) == 1
+        out = out_types[0]
+        assert isinstance(out, PolyFuncType)
+        self.signature = out  # TODO: Extensions
+
+
+class FuncDecl(BaseOp):
+    """External function declaration, linked at runtime."""
+
+    op: Literal["FuncDecl"] = "FuncDecl"
+    name: str
+    signature: PolyFuncType = Field(default_factory=PolyFuncType.empty)
+
+    def insert_port_types(self, in_types: TypeRow, out_types: TypeRow) -> None:
+        assert len(in_types) == 0
+        assert len(out_types) == 1
+        out = out_types[0]
+        assert isinstance(out, PolyFuncType)
+        self.signature = out
+
+
+class ConstBase(BaseOp):
+    """A constant operation definition."""
+
+    op: Literal["Const"] = "Const"
+
+
+CustomConst = Any  # TODO
+
+
+class ExtensionConst(ConstBase):
+    """An extension constant value, that can check it is of a given [CustomType]."""
+
+    c: Literal["Extension"] = Field("Extension", title="ConstTag")
+    e: CustomConst = Field(title="CustomConst")
+
+    class Config:
+        json_schema_extra = {
+            "required": ["parent", "op", "c", "e"],
+        }
+
+
+class FunctionConst(ConstBase):
+    """A higher-order function value."""
+
+    c: Literal["Function"] = Field("Function", title="ConstTag")
+    hugr: Any  # TODO
+
+    class Config:
+        json_schema_extra = {
+            "required": ["parent", "op", "c", "hugr"],
+        }
+
+
+class Tuple(ConstBase):
+    """A constant tuple value."""
+
+    c: Literal["Tuple"] = Field("Tuple", title="ConstTag")
+    vs: list["Const"]
+
+    class Config:
+        json_schema_extra = {
+            "required": ["parent", "op", "c", "vs"],
+        }
+
+
+class Sum(ConstBase):
+    """A Sum variant
+
+    For any Sum type where this value meets the type of the variant indicated by the tag
+    """
+
+    c: Literal["Sum"] = Field("Sum", title="ConstTag")
+    tag: int
+    typ: Type
+    vs: list["Const"]
+
+    class Config:
+        # Needed to avoid random '\n's in the pydantic description
+        json_schema_extra = {
+            "description": (
+                "A Sum variant For any Sum type where this value meets the type "
+                "of the variant indicated by the tag."
+            ),
+            "required": ["parent", "op", "c", "tag", "typ", "vs"],
+        }
+
+
+class Const(RootModel):
+    """A constant operation."""
+
+    root: ExtensionConst | FunctionConst | Tuple | Sum = Field(discriminator="c")
+
+
+# -----------------------------------------------
+# --------------- BasicBlock types ------------------
+# -----------------------------------------------
+
+
+class DataflowBlock(BaseOp):
+    """A CFG basic block node. The signature is that of the internal Dataflow
+    graph."""
+
+    op: Literal["DataflowBlock"] = "DataflowBlock"
+    inputs: TypeRow = Field(default_factory=list)
+    other_outputs: TypeRow = Field(default_factory=list)
+    sum_rows: list[TypeRow] = Field(default_factory=list)
+    extension_delta: ExtensionSet = Field(default_factory=list)
+
+    def insert_port_types(self, in_types: TypeRow, out_types: TypeRow) -> None:
+        num_cases = len(out_types)
+        self.sum_rows = [[] for _ in range(num_cases)]
+
+    def insert_child_dfg_signature(self, inputs: TypeRow, outputs: TypeRow) -> None:
+        self.inputs = inputs
+        pred = outputs[0]
+        assert isinstance(pred, tys.UnitSum | tys.GeneralSum)
+        if isinstance(pred, tys.UnitSum):
+            self.sum_rows = [[] for _ in range(cast(tys.UnitSum, pred).size)]
+        else:
+            self.sum_rows = []
+            for variant in pred.rows:
+                self.sum_rows.append(variant)
+        self.other_outputs = outputs[1:]
+
+    class Config:
+        # Needed to avoid random '\n's in the pydantic description
+        json_schema_extra = {
+            "required": [
+                "parent",
+                "op",
+                "inputs",
+                "other_outputs",
+                "sum_rows",
+                "extension_delta",
+            ],
+            "description": "A CFG basic block node. The signature is that of the internal Dataflow graph.",
+        }
+
+
+class ExitBlock(BaseOp):
+    """The single exit node of the CFG, has no children, stores the types of
+    the CFG node output."""
+
+    op: Literal["ExitBlock"] = "ExitBlock"
+    cfg_outputs: TypeRow
+
+    class Config:
+        # Needed to avoid random '\n's in the pydantic description
+        json_schema_extra = {
+            "description": "The single exit node of the CFG, has no children, stores the types of the CFG node output."
+        }
+
+
+# ---------------------------------------------
+# --------------- DataflowOp ------------------
+# ---------------------------------------------
+
+
+class DataflowOp(BaseOp):
+    pass
+
+
+class Input(DataflowOp):
+    """An input node. The outputs of this node are the inputs to the parent node."""
+
+    op: Literal["Input"] = "Input"
+    types: TypeRow = Field(default_factory=list)
+
+    def insert_port_types(self, in_types: TypeRow, out_types: TypeRow) -> None:
+        assert len(in_types) == 0
+        self.types = list(out_types)
+
+
+class Output(DataflowOp):
+    """An output node. The inputs are the outputs of the function."""
+
+    op: Literal["Output"] = "Output"
+    types: TypeRow = Field(default_factory=list)
+
+    def insert_port_types(self, in_types: TypeRow, out_types: TypeRow) -> None:
+        assert len(out_types) == 0
+        self.types = list(in_types)
+
+
+class Call(DataflowOp):
+    """
+    Call a function directly.
+
+    The first port is connected to the def/declare of the function being called
+    directly, with a `ConstE<Graph>` edge. The signature of the remaining ports matches
+    the function being called.
+    """
+
+    op: Literal["Call"] = "Call"
+    signature: FunctionType = Field(default_factory=FunctionType.empty)
+
+    def insert_port_types(self, in_types: TypeRow, out_types: TypeRow) -> None:
+        # The constE edge comes after the value inputs
+        fun_ty = in_types[-1]
+        assert isinstance(fun_ty, PolyFuncType)
+        poly_func = cast(PolyFuncType, fun_ty)
+        assert len(poly_func.params) == 0
+        self.signature = poly_func.body
+
+    class Config:
+        # Needed to avoid random '\n's in the pydantic description
+        json_schema_extra = {
+            "description": (
+                "Operation to call a function directly. The first port is "
+                "connected to the def/declare of the function being called directly, "
+                "with a `Static<FunctionType>` edge. The signature of the remaining "
+                "ports matches the function being called."
+            )
+        }
+
+
+class CallIndirect(DataflowOp):
+    """Call a function indirectly.
+
+    Like call, but the first input is a standard dataflow graph type."""
+
+    op: Literal["CallIndirect"] = "CallIndirect"
+    signature: FunctionType = Field(default_factory=FunctionType.empty)
+
+    def insert_port_types(self, in_types: TypeRow, out_types: TypeRow) -> None:
+        fun_ty = in_types[0]
+        assert isinstance(fun_ty, PolyFuncType)
+        poly_func = cast(PolyFuncType, fun_ty)
+        assert len(poly_func.params) == 0
+        assert len(poly_func.body.input) == len(in_types) - 1
+        assert len(poly_func.body.output) == len(out_types)
+        self.signature = poly_func.body
+
+
+class LoadConstant(DataflowOp):
+    """An operation that loads a static constant in to the local dataflow graph."""
+
+    op: Literal["LoadConstant"] = "LoadConstant"
+    datatype: Type
+
+
+class LeafOpBase(DataflowOp):
+    """Simple operation that has only value inputs+outputs and (potentially) StateOrder
+    edges."""
+
+    op: Literal["LeafOp"] = "LeafOp"
+
+
+class DFG(DataflowOp):
+    """A simply nested dataflow graph."""
+
+    op: Literal["DFG"] = "DFG"
+    signature: FunctionType = Field(default_factory=FunctionType.empty)
+
+    def insert_child_dfg_signature(self, inputs: TypeRow, outputs: TypeRow) -> None:
+        self.signature = FunctionType(
+            input=list(inputs), output=list(outputs), extension_reqs=ExtensionSet([])
+        )
+
+
+# ------------------------------------------------
+# --------------- ControlFlowOp ------------------
+# ------------------------------------------------
+
+
+class Conditional(DataflowOp):
+    """Conditional operation, defined by child `Case` nodes for each branch."""
+
+    op: Literal["Conditional"] = "Conditional"
+    other_inputs: TypeRow = Field(default_factory=list)  # Remaining input types
+    outputs: TypeRow = Field(default_factory=list)  # Output types
+    sum_rows: list[TypeRow] = Field(description="The possible rows of the Sum input")
+    # Extensions used to produce the outputs
+    extension_delta: ExtensionSet = Field(default_factory=list)
+
+    def insert_port_types(self, in_types: TypeRow, out_types: TypeRow) -> None:
+        # First port is a predicate, i.e. a sum of tuple types. We need to unpack
+        # those into a list of type rows
+        pred = in_types[0]
+        if isinstance(pred, tys.UnitSum):
+            self.sum_rows = [[] for _ in range(cast(tys.UnitSum, pred).size)]
+        else:
+            assert isinstance(pred, tys.GeneralSum)
+            self.sum_rows = []
+            for ty in pred.rows:
+                self.sum_rows.append(ty)
+        self.other_inputs = list(in_types[1:])
+        self.outputs = list(out_types)
+
+
+class Case(BaseOp):
+    """Case ops - nodes valid inside Conditional nodes."""
+
+    op: Literal["Case"] = "Case"
+    # The signature of the contained dataflow graph.
+    signature: FunctionType = Field(default_factory=FunctionType.empty)
+
+    def insert_child_dfg_signature(self, inputs: TypeRow, outputs: TypeRow) -> None:
+        self.signature = tys.FunctionType(
+            input=list(inputs), output=list(outputs), extension_reqs=ExtensionSet([])
+        )
+
+
+class TailLoop(DataflowOp):
+    """Tail-controlled loop."""
+
+    op: Literal["TailLoop"] = "TailLoop"
+    just_inputs: TypeRow = Field(default_factory=list)  # Types that are only input
+    just_outputs: TypeRow = Field(default_factory=list)  # Types that are only output
+    # Types that are appended to both input and output:
+    rest: TypeRow = Field(default_factory=list)
+
+    def insert_port_types(self, in_types: TypeRow, out_types: TypeRow) -> None:
+        assert in_types == out_types
+        # self.just_inputs = list(in_types)
+        # self.just_outputs = list(out_types)
+        self.rest = list(in_types)
+
+
+class CFG(DataflowOp):
+    """A dataflow node which is defined by a child CFG."""
+
+    op: Literal["CFG"] = "CFG"
+    signature: FunctionType = Field(default_factory=FunctionType.empty)
+
+    def insert_port_types(self, inputs: TypeRow, outputs: TypeRow) -> None:
+        self.signature = FunctionType(
+            input=list(inputs), output=list(outputs), extension_reqs=ExtensionSet([])
+        )
+
+
+ControlFlowOp = Conditional | TailLoop | CFG
+
+
+# -----------------------------------------
+# --------------- LeafOp ------------------
+# -----------------------------------------
+
+
+class CustomOp(LeafOpBase):
+    """A user-defined operation that can be downcasted by the extensions that define
+    it."""
+
+    lop: Literal["CustomOp"] = "CustomOp"
+    extension: ExtensionId
+    op_name: str
+    signature: tys.FunctionType = Field(default_factory=tys.FunctionType.empty)
+    description: str = ""
+    args: list[tys.TypeArg] = Field(default_factory=list)
+
+    def insert_port_types(self, in_types: TypeRow, out_types: TypeRow) -> None:
+        self.signature = tys.FunctionType(input=list(in_types), output=list(out_types))
+
+    def display_name(self) -> str:
+        return self.op_name
+
+    class Config:
+        # Needed to avoid random '\n's in the pydantic description
+        json_schema_extra = {
+            "description": (
+                "A user-defined operation that can be downcasted by the extensions that "
+                "define it."
+            )
+        }
+
+
+class Noop(LeafOpBase):
+    """A no-op operation."""
+
+    lop: Literal["Noop"] = "Noop"
+    ty: Type
+
+    def insert_port_types(self, in_types: TypeRow, out_types: TypeRow) -> None:
+        assert len(in_types) == 1
+        assert len(out_types) == 1
+        assert in_types[0] == out_types[0]
+        self.ty = in_types[0]
+
+
+class MakeTuple(LeafOpBase):
+    """An operation that packs all its inputs into a tuple."""
+
+    lop: Literal["MakeTuple"] = "MakeTuple"
+    tys: TypeRow = Field(default_factory=list)
+
+    def insert_port_types(self, in_types: TypeRow, out_types: TypeRow) -> None:
+        # If we have a single order edge as input, this is a unit
+        if in_types == [None]:
+            in_types = []
+        self.tys = list(in_types)
+
+
+class UnpackTuple(LeafOpBase):
+    """An operation that packs all its inputs into a tuple."""
+
+    lop: Literal["UnpackTuple"] = "UnpackTuple"
+    tys: TypeRow = Field(default_factory=list)
+
+    def insert_port_types(self, in_types: TypeRow, out_types: TypeRow) -> None:
+        self.tys = list(out_types)
+
+
+class Tag(LeafOpBase):
+    """An operation that creates a tagged sum value from one of its variants."""
+
+    lop: Literal["Tag"] = "Tag"
+    tag: int  # The variant to create.
+    variants: TypeRow  # The variants of the sum type.
+
+
+class TypeApply(LeafOpBase):
+    """Fixes some TypeParams of a polymorphic type by providing TypeArgs."""
+
+    lop: Literal["TypeApply"] = "TypeApply"
+    ta: "TypeApplication"
+
+
+class TypeApplication(BaseModel):
+    """Records details of an application of a PolyFuncType to some TypeArgs and the
+    result (a less-, but still potentially-, polymorphic type).
+    """
+
+    input: PolyFuncType
+    args: list[tys.TypeTypeArg]
+    output: PolyFuncType
+
+    class Config:
+        # Needed to avoid random '\n's in the pydantic description
+        json_schema_extra = {
+            "description": (
+                "Records details of an application of a PolyFuncType to some TypeArgs "
+                "and the result (a less-, but still potentially-, polymorphic type)."
+            )
+        }
+
+
+class LeafOp(RootModel):
+    """A constant operation."""
+
+    root: CustomOp | Noop | MakeTuple | UnpackTuple | Tag | TypeApply = Field(
+        discriminator="lop"
+    )
+
+
+class OpType(RootModel):
+    """A constant operation."""
+
+    root: (
+        Module
+        | Case
+        | FuncDefn
+        | FuncDecl
+        | Const
+        | DataflowBlock
+        | ExitBlock
+        | Conditional
+        | TailLoop
+        | CFG
+        | Input
+        | Output
+        | Call
+        | CallIndirect
+        | LoadConstant
+        | LeafOp
+        | DFG
+    ) = Field(discriminator="op")
+
+
+# --------------------------------------
+# --------------- OpDef ----------------
+# --------------------------------------
+
+
+class OpDef(BaseOp, populate_by_name=True):
+    """Serializable definition for dynamically loaded operations."""
+
+    name: str  # Unique identifier of the operation.
+    description: str  # Human readable description of the operation.
+    inputs: list[tuple[str | None, Type]]
+    outputs: list[tuple[str | None, Type]]
+    misc: dict[str, Any]  # Miscellaneous data associated with the operation.
+    def_: str | None = Field(
+        ..., alias="def"
+    )  # (YAML?)-encoded definition of the operation.
+    extension_reqs: ExtensionSet  # Resources required to execute this operation.
+
+
+# Now that all classes are defined, we need to update the ForwardRefs in all type
+# annotations. We use some inspect magic to find all classes defined in this file.
+classes = inspect.getmembers(
+    sys.modules[__name__],
+    lambda member: inspect.isclass(member) and member.__module__ == __name__,
+)
+for _, c in classes:
+    if issubclass(c, BaseModel):
+        c.model_rebuild()

hugr-0.1.0a1/src/hugr/serialization/serial_hugr.py

@@ -0,0 +1,36 @@
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+from .ops import NodeID, OpType
+
+Port = tuple[NodeID, int | None]  # (node, offset)
+Edge = tuple[Port, Port]
+
+
+class SerialHugr(BaseModel):
+    """A serializable representation of a Hugr."""
+
+    version: Literal["v1"] = "v1"
+    nodes: list[OpType]
+    edges: list[Edge]
+
+    def to_json(self) -> str:
+        """Return a JSON representation of the Hugr."""
+        return self.model_dump_json()
+
+    @classmethod
+    def load_json(cls, json: dict[Any, Any]) -> "SerialHugr":
+        """Decode a JSON-encoded Hugr."""
+        return cls(**json)
+
+    @classmethod
+    def get_version(cls) -> str:
+        """Return the version of the schema."""
+        return cls(nodes=[], edges=[]).version
+
+    class Config:
+        title = "Hugr"
+        json_schema_extra = {
+            "required": ["version", "nodes", "edges"],
+        }

hugr-0.1.0a1/src/hugr/serialization/tys.py

@@ -0,0 +1,320 @@
+import inspect
+import sys
+from enum import Enum
+from typing import Annotated, Any, Literal, Optional, Union
+
+from pydantic import (
+    BaseModel,
+    Field,
+    RootModel,
+    ValidationError,
+    ValidationInfo,
+    ValidatorFunctionWrapHandler,
+    WrapValidator,
+)
+from pydantic_core import PydanticCustomError
+
+
+def _json_custom_error_validator(
+    value: Any, handler: ValidatorFunctionWrapHandler, _info: ValidationInfo
+) -> Any:
+    """Simplify the error message to avoid a gross error stemming
+    from exhaustive checking of all union options.
+
+    As suggested at
+    https://docs.pydantic.dev/latest/concepts/types/#named-recursive-types
+
+
+    Used to define named recursive alias types.
+    """
+    try:
+        return handler(value)
+    except ValidationError as err:
+        raise PydanticCustomError(
+            "invalid_json",
+            "Input is not valid json",
+        ) from err
+
+
+ExtensionId = str
+
+
+class ExtensionSet(RootModel):
+    """A set of extensions ids."""
+
+    root: Optional[list[ExtensionId]] = Field(default=None)
+
+
+# --------------------------------------------
+# --------------- TypeParam ------------------
+# --------------------------------------------
+
+
+class TypeTypeParam(BaseModel):
+    tp: Literal["Type"] = "Type"
+    b: "TypeBound"
+
+
+class BoundedNatParam(BaseModel):
+    tp: Literal["BoundedNat"] = "BoundedNat"
+    bound: int | None
+
+
+class OpaqueParam(BaseModel):
+    tp: Literal["Opaque"] = "Opaque"
+    ty: "Opaque"
+
+
+class ListParam(BaseModel):
+    tp: Literal["List"] = "List"
+    param: "TypeParam"
+
+
+class TupleParam(BaseModel):
+    tp: Literal["Tuple"] = "Tuple"
+    params: list["TypeParam"]
+
+
+class TypeParam(RootModel):
+    """A type parameter."""
+
+    root: Annotated[
+        TypeTypeParam | BoundedNatParam | OpaqueParam | ListParam | TupleParam,
+        WrapValidator(_json_custom_error_validator),
+    ] = Field(discriminator="tp")
+
+
+# ------------------------------------------
+# --------------- TypeArg ------------------
+# ------------------------------------------
+
+
+class CustomTypeArg(BaseModel):
+    typ: None  # TODO
+    value: str
+
+
+class TypeTypeArg(BaseModel):
+    tya: Literal["Type"] = "Type"
+    ty: "Type"
+
+
+class BoundedNatArg(BaseModel):
+    tya: Literal["BoundedNat"] = "BoundedNat"
+    n: int
+
+
+class OpaqueArg(BaseModel):
+    tya: Literal["Opaque"] = "Opaque"
+    arg: CustomTypeArg
+
+
+class SequenceArg(BaseModel):
+    tya: Literal["Sequence"] = "Sequence"
+    args: list["TypeArg"]
+
+
+class ExtensionsArg(BaseModel):
+    tya: Literal["Extensions"] = "Extensions"
+    es: ExtensionSet
+
+
+class TypeArg(RootModel):
+    """A type argument."""
+
+    root: Annotated[
+        TypeTypeArg | BoundedNatArg | OpaqueArg | SequenceArg | ExtensionsArg,
+        WrapValidator(_json_custom_error_validator),
+    ] = Field(discriminator="tya")
+
+
+# --------------------------------------------
+# --------------- Container ------------------
+# --------------------------------------------
+
+
+class MultiContainer(BaseModel):
+    ty: "Type"
+
+
+class Array(MultiContainer):
+    """Known size array whose elements are of the same type."""
+
+    t: Literal["Array"] = "Array"
+    len: int
+
+
+class UnitSum(BaseModel):
+    """Simple predicate where all variants are empty tuples."""
+
+    t: Literal["Sum"] = "Sum"
+
+    s: Literal["Unit"] = "Unit"
+    size: int
+
+
+class GeneralSum(BaseModel):
+    """General sum type that explicitly stores the types of the variants."""
+
+    t: Literal["Sum"] = "Sum"
+
+    s: Literal["General"] = "General"
+    rows: list["TypeRow"]
+
+
+class SumType(RootModel):
+    root: Union[UnitSum, GeneralSum] = Field(discriminator="s")
+
+
+# ----------------------------------------------
+# --------------- ClassicType ------------------
+# ----------------------------------------------
+
+
+class Variable(BaseModel):
+    """A type variable identified by a de Bruijn index."""
+
+    t: Literal["V"] = "V"
+    i: int
+    b: "TypeBound"
+
+
+class USize(BaseModel):
+    """Unsigned integer size type."""
+
+    t: Literal["I"] = "I"
+
+
+class FunctionType(BaseModel):
+    """A graph encoded as a value. It contains a concrete signature and a set of
+    required resources."""
+
+    input: "TypeRow"  # Value inputs of the function.
+    output: "TypeRow"  # Value outputs of the function.
+    # The extension requirements which are added by the operation
+    extension_reqs: "ExtensionSet" = Field(default_factory=list)
+
+    @classmethod
+    def empty(cls) -> "FunctionType":
+        return FunctionType(input=[], output=[], extension_reqs=ExtensionSet([]))
+
+    class Config:
+        # Needed to avoid random '\n's in the pydantic description
+        json_schema_extra = {
+            "description": (
+                "A graph encoded as a value. It contains a concrete signature and "
+                "a set of required resources."
+            )
+        }
+
+
+class PolyFuncType(BaseModel):
+    """A graph encoded as a value. It contains a concrete signature and a set of
+    required resources."""
+
+    t: Literal["G"] = "G"
+
+    # The declared type parameters, i.e., these must be instantiated with the same
+    # number of TypeArgs before the function can be called. Note that within the body,
+    # variable (DeBruijn) index 0 is element 0 of this array, i.e. the variables are
+    # bound from right to left.
+    params: list[TypeParam]
+
+    # Template for the function. May contain variables up to length of `params`
+    body: FunctionType
+
+    @classmethod
+    def empty(cls) -> "PolyFuncType":
+        return PolyFuncType(params=[], body=FunctionType.empty())
+
+    class Config:
+        # Needed to avoid random '\n's in the pydantic description
+        json_schema_extra = {
+            "description": (
+                "A graph encoded as a value. It contains a concrete signature and "
+                "a set of required resources."
+            )
+        }
+
+
+class TypeBound(Enum):
+    Eq = "E"
+    Copyable = "C"
+    Any = "A"
+
+    @staticmethod
+    def join(*bs: "TypeBound") -> "TypeBound":
+        """Computes the least upper bound for a sequence of bounds."""
+        res = TypeBound.Eq
+        for b in bs:
+            if b == TypeBound.Any:
+                return TypeBound.Any
+            if res == TypeBound.Eq:
+                res = b
+        return res
+
+
+class Opaque(BaseModel):
+    """An opaque operation that can be downcasted by the extensions that define it."""
+
+    t: Literal["Opaque"] = "Opaque"
+    extension: ExtensionId
+    id: str  # Unique identifier of the opaque type.
+    args: list[TypeArg]
+    bound: TypeBound
+
+
+# ----------------------------------------------
+# --------------- LinearType -------------------
+# ----------------------------------------------
+
+
+class Qubit(BaseModel):
+    """A qubit."""
+
+    t: Literal["Q"] = "Q"
+
+
+class Type(RootModel):
+    """A HUGR type."""
+
+    root: Annotated[
+        Qubit | Variable | USize | PolyFuncType | Array | SumType | Opaque,
+        WrapValidator(_json_custom_error_validator),
+    ] = Field(discriminator="t")
+
+
+# -------------------------------------------
+# --------------- TypeRow -------------------
+# -------------------------------------------
+
+TypeRow = list[Type]
+
+
+# -------------------------------------------
+# --------------- Signature -----------------
+# -------------------------------------------
+
+
+class Signature(BaseModel):
+    """Describes the edges required to/from a node.
+
+    This includes both the concept of "signature" in the spec, and also the target
+    (value) of a call (constant).
+    """
+
+    signature: "PolyFuncType"  # The underlying signature
+
+    # The extensions which are associated with all the inputs and carried through
+    input_extensions: ExtensionSet
+
+
+# Now that all classes are defined, we need to update the ForwardRefs in all type
+# annotations. We use some inspect magic to find all classes defined in this file.
+classes = inspect.getmembers(
+    sys.modules[__name__],
+    lambda member: inspect.isclass(member) and member.__module__ == __name__,
+)
+for _, c in classes:
+    if issubclass(c, BaseModel):
+        c.model_rebuild()