feat: Add customisable kv-pair metadata to gate definitions

hatch_build.py

@@ -492,6 +492,7 @@ def build_base_qis(self):
         cmake_build_dir.mkdir(parents=True, exist_ok=True)
         dist_dir = base_qis_dir / "python/selene_base_qis_plugin/_dist"
         dist_dir.mkdir(parents=True, exist_ok=True)
+        selene_core_include_dir = Path(self.root) / "selene-core/c/include"
         selene_sim_dist_dir = Path(self.root) / "selene-sim/python/selene_sim/_dist"
         local_dist_lib_dir = dist_dir / "lib"
         local_selene_dist_lib_dir = selene_sim_dist_dir / "lib"
@@ -509,6 +510,7 @@ def build_base_qis(self):
             f"-DCMAKE_INSTALL_PREFIX={dist_dir}",
             *self.install_rpath_arg([local_rpath, installed_rpath]),
             "-DCMAKE_BUILD_TYPE=Release",
+            f"-DSELENE_CORE_INCLUDE_DIR={selene_core_include_dir}",
             f"-DCMAKE_PREFIX_PATH={selene_sim_dist_dir}",
             f"{cmake_source_dir}",
         ]

selene-core/c/include/selene/gatewire.h

@@ -9,6 +9,18 @@
 #include <stddef.h>
 #include <stdint.h>
 
+#define GW_METADATA_VALUE_KIND_BOOL 1
+
+#define GW_METADATA_VALUE_KIND_I64 2
+
+#define GW_METADATA_VALUE_KIND_U64 3
+
+#define GW_METADATA_VALUE_KIND_F64 4
+
+#define GW_METADATA_VALUE_KIND_STRING 5
+
+#define GW_METADATA_VALUE_KIND_BYTES 6
+
 #define GW_OPERAND_KIND_QUBIT 1
 
 #define GW_OPERAND_KIND_F64 2
@@ -81,11 +93,30 @@ typedef struct {
   size_t bytes_len;
 } GwGateValue;
 
+typedef union {
+  uint8_t bool_value;
+  int64_t i64_value;
+  uint64_t u64_value;
+  double f64_value;
+} GwMetadataValueData;
+
+typedef struct {
+  size_t abi_size;
+  const char *key_ptr;
+  size_t key_len;
+  uint32_t value_kind;
+  GwMetadataValueData data;
+  const uint8_t *bytes_ptr;
+  size_t bytes_len;
+} GwGateMetadata;
+
 typedef struct {
   size_t abi_size;
   GwSemanticId semantic_id;
   const GwGateValue *values_ptr;
   size_t values_len;
+  const GwGateMetadata *metadata_ptr;
+  size_t metadata_len;
 } GwGateInstanceView;
 
 typedef struct {
@@ -181,6 +212,15 @@ GwStatus gw_decoded_gate_value_count(const GwDecodedGate *gate, size_t *out);
 
 GwStatus gw_decoded_gate_value_at(const GwDecodedGate *gate, size_t index, GwGateValue *out);
 
+GwStatus gw_decoded_gate_metadata_count(const GwDecodedGate *gate, size_t *out);
+
+GwStatus gw_decoded_gate_metadata_at(const GwDecodedGate *gate, size_t index, GwGateMetadata *out);
+
+GwStatus gw_decoded_gate_metadata_find(const GwDecodedGate *gate,
+                                       const char *key_ptr,
+                                       size_t key_len,
+                                       GwGateMetadata *out);
+
 GwStatus gw_decoded_gate_qubit_operand_count(const GwDecodedGate *gate, size_t *out);
 
 GwStatus gw_decoded_gate_qubit_operand_at(const GwDecodedGate *gate,

selene-core/cbindgen/core_types.toml

@@ -38,6 +38,12 @@ exclude = [
   "GW_OPERAND_KIND_I64",
   "GW_OPERAND_KIND_U8",
   "GW_OPERAND_KIND_BOOL",
+  "GW_METADATA_VALUE_KIND_BOOL",
+  "GW_METADATA_VALUE_KIND_I64",
+  "GW_METADATA_VALUE_KIND_U64",
+  "GW_METADATA_VALUE_KIND_F64",
+  "GW_METADATA_VALUE_KIND_STRING",
+  "GW_METADATA_VALUE_KIND_BYTES",
   "GwSemanticId",
   "GwGateSet",
   "GwOperandDeclView",
@@ -46,6 +52,8 @@ exclude = [
   "GwOperandDeclInfo",
   "GwGateValueData",
   "GwGateValue",
+  "GwMetadataValueData",
+  "GwGateMetadata",
   "GwGateInstanceView",
   "GwDecodedGate",
   "gw_status_message",
@@ -77,6 +85,9 @@ exclude = [
   "gw_decoded_gate_semantic_id",
   "gw_decoded_gate_value_count",
   "gw_decoded_gate_value_at",
+  "gw_decoded_gate_metadata_count",
+  "gw_decoded_gate_metadata_at",
+  "gw_decoded_gate_metadata_find",
   "gw_gateset_validate_decoded",
 ]
 item_types = ["functions", "structs", "opaque", "enums", "typedefs"]

selene-core/cbindgen/error_model.toml

@@ -49,6 +49,12 @@ exclude = [
   "GW_OPERAND_KIND_I64",
   "GW_OPERAND_KIND_U8",
   "GW_OPERAND_KIND_BOOL",
+  "GW_METADATA_VALUE_KIND_BOOL",
+  "GW_METADATA_VALUE_KIND_I64",
+  "GW_METADATA_VALUE_KIND_U64",
+  "GW_METADATA_VALUE_KIND_F64",
+  "GW_METADATA_VALUE_KIND_STRING",
+  "GW_METADATA_VALUE_KIND_BYTES",
   "GwSemanticId",
   "GwGateSet",
   "GwOperandDeclView",
@@ -57,6 +63,8 @@ exclude = [
   "GwOperandDeclInfo",
   "GwGateValueData",
   "GwGateValue",
+  "GwMetadataValueData",
+  "GwGateMetadata",
   "GwGateInstanceView",
   "GwDecodedGate",
   "gw_status_message",
@@ -88,6 +96,9 @@ exclude = [
   "gw_decoded_gate_semantic_id",
   "gw_decoded_gate_value_count",
   "gw_decoded_gate_value_at",
+  "gw_decoded_gate_metadata_count",
+  "gw_decoded_gate_metadata_at",
+  "gw_decoded_gate_metadata_find",
   "gw_gateset_validate_decoded",
 ]
 item_types = ["functions", "structs", "opaque", "enums", "typedefs"]

selene-core/cbindgen/runtime.toml

@@ -45,6 +45,12 @@ exclude = [
   "GW_OPERAND_KIND_I64",
   "GW_OPERAND_KIND_U8",
   "GW_OPERAND_KIND_BOOL",
+  "GW_METADATA_VALUE_KIND_BOOL",
+  "GW_METADATA_VALUE_KIND_I64",
+  "GW_METADATA_VALUE_KIND_U64",
+  "GW_METADATA_VALUE_KIND_F64",
+  "GW_METADATA_VALUE_KIND_STRING",
+  "GW_METADATA_VALUE_KIND_BYTES",
   "GwSemanticId",
   "GwGateSet",
   "GwOperandDeclView",
@@ -53,6 +59,8 @@ exclude = [
   "GwOperandDeclInfo",
   "GwGateValueData",
   "GwGateValue",
+  "GwMetadataValueData",
+  "GwGateMetadata",
   "GwGateInstanceView",
   "GwDecodedGate",
   "gw_status_message",
@@ -84,6 +92,9 @@ exclude = [
   "gw_decoded_gate_semantic_id",
   "gw_decoded_gate_value_count",
   "gw_decoded_gate_value_at",
+  "gw_decoded_gate_metadata_count",
+  "gw_decoded_gate_metadata_at",
+  "gw_decoded_gate_metadata_find",
   "gw_gateset_validate_decoded",
 ]
 item_types = ["functions", "structs", "opaque", "enums", "typedefs"]

selene-core/cbindgen/simulator.toml

@@ -42,6 +42,12 @@ exclude = [
   "GW_OPERAND_KIND_I64",
   "GW_OPERAND_KIND_U8",
   "GW_OPERAND_KIND_BOOL",
+  "GW_METADATA_VALUE_KIND_BOOL",
+  "GW_METADATA_VALUE_KIND_I64",
+  "GW_METADATA_VALUE_KIND_U64",
+  "GW_METADATA_VALUE_KIND_F64",
+  "GW_METADATA_VALUE_KIND_STRING",
+  "GW_METADATA_VALUE_KIND_BYTES",
   "GwSemanticId",
   "GwGateSet",
   "GwOperandDeclView",
@@ -50,6 +56,8 @@ exclude = [
   "GwOperandDeclInfo",
   "GwGateValueData",
   "GwGateValue",
+  "GwMetadataValueData",
+  "GwGateMetadata",
   "GwGateInstanceView",
   "GwDecodedGate",
   "gw_status_message",
@@ -81,6 +89,9 @@ exclude = [
   "gw_decoded_gate_semantic_id",
   "gw_decoded_gate_value_count",
   "gw_decoded_gate_value_at",
+  "gw_decoded_gate_metadata_count",
+  "gw_decoded_gate_metadata_at",
+  "gw_decoded_gate_metadata_find",
   "gw_gateset_validate_decoded",
 ]
 item_types = ["functions", "structs", "opaque", "enums", "typedefs"]

selene-core/pyproject.toml

@@ -7,6 +7,7 @@ readme = "python/selene_core/README.md"
 dependencies = [
   "blake3>=1.0.0",
   "cffi>=1.17.1",
+  "filebytes>=0.10.2",
   "hugr>=0.13.0",
   # required for inspecting object files to find defined and declared symbols
   "lief>=0.16.5",
@@ -17,7 +18,9 @@ dependencies = [
   "networkx>=2.6,<4",
   "pydantic>=2.12.5",
   "pydot>=4.0.0",
+  "pyelftools>=0.33",
   "pyyaml~=6.0",
+  "symbolic>=13.8.0",
   "typing_extensions>=4",
   "ziglang~=0.13",
 ]
@@ -44,7 +47,7 @@ path = "hatch_build.py"
 
 [tool.uv]
 cache-keys = [
-  { file = "python/selene_core/trace.py" },
+  { file = "python/selene_core/**/*.py" },
   { file = "c/include/selene/*.h" },
   { file = "Cargo.toml" },
 ]

selene-core/python/selene_core/__init__.py

@@ -12,6 +12,7 @@
     DEFAULT_BUILD_PLANNER,
 )
 from .headers import get_include_directory
+from .debug_info import QisCallSiteSymbolizer, symbolize_qis_call_sites
 from .gatewire import (
     BOOL,
     F64,
@@ -22,9 +23,12 @@
     BoundGate,
     Gate,
     GateDefinition,
+    GateMetadata,
     GateValue,
     Gateset,
     HeliosGateSet,
+    MetadataValue,
+    MetadataValueKind,
     OperandDefinition,
     OperandKind,
     PhasedX,
@@ -54,6 +58,8 @@
     "BuildCtx",
     "DEFAULT_BUILD_PLANNER",
     "get_include_directory",
+    "QisCallSiteSymbolizer",
+    "symbolize_qis_call_sites",
     "BOOL",
     "F64",
     "I64",
@@ -63,9 +69,12 @@
     "BoundGate",
     "Gate",
     "GateDefinition",
+    "GateMetadata",
     "GateValue",
     "Gateset",
     "HeliosGateSet",
+    "MetadataValue",
+    "MetadataValueKind",
     "OperandDefinition",
     "OperandKind",
     "PhasedX",

selene-core/python/selene_core/build_utils/builtins/helios.py

@@ -7,7 +7,7 @@
     Artifact,
     Step,
 )
-from ..utils import invoke_zig
+from ..utils import debug_objects_for_executable, invoke_zig
 from ..symbols import get_symbols_from_object, get_symbols_from_llvm, SymbolTable
 from ..planner import BuildPlanner
 
@@ -335,7 +335,12 @@ def apply(cls, build_ctx: BuildCtx, input_artifact: Artifact) -> Artifact:
         return Artifact(
             out_path,
             SeleneExecutableKind,
-            metadata={"library_search_dirs": library_search_dirs},
+            metadata={
+                "library_search_dirs": library_search_dirs,
+                "debug_objects": debug_objects_for_executable(
+                    input_artifact.resource, out_path
+                ),
+            },
         )
 
 

selene-core/python/selene_core/build_utils/builtins/selene.py

@@ -18,7 +18,7 @@
 
 from ..planner import BuildPlanner
 from ..types import ArtifactKind, Step, BuildCtx, Artifact
-from ..utils import invoke_zig
+from ..utils import debug_objects_for_executable, invoke_zig
 from ..symbols import get_symbols_from_object
 
 
@@ -149,7 +149,12 @@ def apply(cls, build_ctx: BuildCtx, input_artifact: Artifact) -> Artifact:
         )
         return cls._make_artifact(
             out_path,
-            metadata={"library_search_dirs": library_search_dirs},
+            metadata={
+                "library_search_dirs": library_search_dirs,
+                "debug_objects": debug_objects_for_executable(
+                    input_artifact.resource, out_path
+                ),
+            },
         )
 
 

selene-core/python/selene_core/build_utils/builtins/sol.py

@@ -7,7 +7,7 @@
     Artifact,
     Step,
 )
-from ..utils import invoke_zig
+from ..utils import debug_objects_for_executable, invoke_zig
 from ..symbols import get_symbols_from_object, get_symbols_from_llvm, SymbolTable
 from ..planner import BuildPlanner
 
@@ -331,7 +331,12 @@ def apply(cls, build_ctx: BuildCtx, input_artifact: Artifact) -> Artifact:
         return Artifact(
             out_path,
             SeleneExecutableKind,
-            metadata={"library_search_dirs": library_search_dirs},
+            metadata={
+                "library_search_dirs": library_search_dirs,
+                "debug_objects": debug_objects_for_executable(
+                    input_artifact.resource, out_path
+                ),
+            },
         )
 
 

selene-core/python/selene_core/build_utils/utils.py

@@ -84,3 +84,18 @@ def invoke_zig(
         raise RuntimeError(
             f"zig command failed:\n  Command: {' '.join(argv)}\n  Error: {stderr.decode()}"
         )
+
+
+def debug_objects_for_executable(input_object: Path, executable: Path) -> list[Path]:
+    """
+    Return debug-information artifacts associated with a linked executable.
+
+    The input object usually remains useful debug provenance on platforms where
+    the final linked image keeps only a debug map. Some linkers also emit
+    sidecar debug files next to the executable, such as PDBs on Windows.
+    """
+    debug_objects = [input_object]
+    pdb_path = executable.with_suffix(".pdb")
+    if pdb_path.is_file():
+        debug_objects.append(pdb_path)
+    return debug_objects