selene-formats 0.1.1__tar.gz

selene_formats-0.1.1/.gitignore

@@ -0,0 +1,50 @@
+# Generated by Cargo
+# will have compiled files and executables
+debug/
+target/
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+
+.DS_Store
+3rdparty/
+.buildsecrets/
+*.whl
+*.pyc
+*.o
+*.so
+*.dll
+*.dll.lib
+*.dll.a
+
+venv/
+.venv/
+.vscode/
+.direnv/
+.devenv/
+.hugrenv/
+.devenv.flake.nix
+.pre-commit-config.yaml
+result
+
+.envrc
+
+__pycache__/
+*.egg-info/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+/devenv.local.nix
+_dist/
+
+wheelhouse/
+node_modules/
+.pnpm-store/
+selene-formats/typescript/dist/
+!.cargo
+scratch/
+
+.idea

selene_formats-0.1.1/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.1.1](https://github.com/Quantinuum/selene/compare/selene-formats-v0.1.0...selene-formats-v0.1.1) (2026-10-16)
+
+
+### Features
+
+* add streaming trace format, use it in place of instruction logs ([#235](https://github.com/Quantinuum/selene/issues/235)) ([6f18bda](https://github.com/Quantinuum/selene/commit/6f18bda40783c72c988b0764f3e9578045d29130))
+* Add versioned, cross-language Selene API models ([#212](https://github.com/Quantinuum/selene/issues/212)) ([df33c56](https://github.com/Quantinuum/selene/commit/df33c566cb5e81428c7983e15fe2b1db177c9deb))

selene_formats-0.1.1/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.5
+Name: selene-formats
+Version: 0.1.1
+Summary: Selene formats for Python
+Project-URL: repository, https://github.com/quantinuum/selene
+Author: Quantinuum
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Requires-Dist: msgpack<2,>=1.1
+Requires-Dist: pydantic~=2.12
+Description-Content-Type: text/markdown
+
+# selene-formats for Python
+
+Python models for the versioned, serializable Selene trace protocol. See the
+protocol documentation and JSON Schema in the repository's `selene-formats/`
+directory.
+
+```python
+from selene_formats.trace import (
+    SCHEMA_VERSION,
+    Trace,
+    TraceData,
+    Traces,
+    parse_trace_json,
+)
+
+trace = Trace(schema_version=SCHEMA_VERSION, events=[])
+traces = Traces(schema_version=SCHEMA_VERSION, traces=[TraceData(events=[])])
+upgraded = parse_trace_json(versionless_trace_json)
+legacy_json = trace.as_legacy().model_dump_json(indent=2)
+```
+
+`as_legacy()` returns a `LegacyTrace` sharing the current event models and
+validation rules. Its `model_dump()` and `model_dump_json()` omit
+`schema_version` and keep opaque tags numeric. `LegacyTrace` also accepts
+versionless input and defaults its internal version to `0.1.0`. Filtering and
+timing helpers retain legacy serialization. Collections have no legacy format.
+
+For trace streams, use the MessagePack API rather than the JSON document parser:
+
+```python
+from selene_formats.trace_stream import iter_trace_stream, write_trace_stream
+
+write_trace_stream("trace.msgpack.gz", trace.events)
+for event in iter_trace_stream("trace.msgpack.gz"):
+    print(event)
+```
+
+Use `iter_trace_stream_records` to include instruction metadata. Reads are lazy
+and uncached, so keep the source file available until iteration finishes. See
+the [stream format](../README.md#trace-streams) for framing and error handling.

selene_formats-0.1.1/README.md

@@ -0,0 +1,92 @@
+# Selene Formats
+
+`selene-formats` contains the schemas, documentation, examples, and language
+models for Selene's public serialized traces. It has no dependency on the
+emulator.
+
+Selene's `extractor.shots[index].get_trace()` output uses the versionless legacy format and
+`selene_core.trace` models, which use the Python binding's `LegacyTrace` wrapper.
+The language bindings use protocol 0.1.0 and provide adapters for reading and
+serializing legacy traces with the current validation rules.
+
+## APIs
+
+| API | Version | Schema | Semantics |
+| --- | --- | --- | --- |
+| Trace documents (`Trace` and `Traces`) | 0.1.0 | [`schemas/trace/0.1.0.schema.json`](schemas/trace/0.1.0.schema.json) | [`docs/trace/0.1.0.md`](docs/trace/0.1.0.md) |
+| Trace (legacy input) | versionless | [`schemas/trace/legacy.schema.json`](schemas/trace/legacy.schema.json) | [`docs/trace/legacy.md`](docs/trace/legacy.md) |
+
+Schemas are also published at their canonical `$id` URLs:
+
+* [Trace documents 0.1.0](https://quantinuum.github.io/selene/schemas/trace/0.1.0.schema.json)
+* [Trace (legacy input)](https://quantinuum.github.io/selene/schemas/trace/legacy.schema.json)
+
+Protocol-wide versioning is described in [`docs/versioning.md`](docs/versioning.md).
+
+## Bindings
+
+* Python: [`python/`](python) publishes the `selene-formats` distribution and is
+  imported as `selene_formats`.
+* Rust: [`rust/`](rust) publishes the `selene-formats` crate.
+* TypeScript: [`typescript/`](typescript) publishes the `@quantinuum/selene-formats`
+  package.
+
+The binding release process is described in [`docs/publishing.md`](docs/publishing.md).
+
+## Trace streams
+
+`trace_stream` in the Python and Rust APIs implements gzipped MessagePack trace
+streams. This is separate from the complete JSON `Trace` document format, in that
+it is designed to be read and written in a sequential manner.
+
+After gzip decompression, the stream consists of consecutive MessagePack objects:
+
+1. A map with `format: "selene.trace.msgpack"`, `format_version: 1`, and
+   `schema_version: "0.1.0"`.
+2. Zero or more record maps.
+3. A single MessagePack nil (`0xc0`) marking successful completion.
+
+Nothing may follow the end marker in the decompressed stream. Readers
+reject missing markers, incomplete records, unsupported headers and bad gzip
+trailers. Exhaust the iterator to check the whole stream; an error cannot retract
+events already yielded.
+
+Event records have the existing `source` and `event` fields. Custom payload tags
+use native uint64 values and payload data uses MessagePack binary values, instead
+of hex strings or base64 as used in the JSON format.
+
+An event may also contain `instruction: "FutureRead"` or
+`instruction: "MeasureLeakedRequest"`. Batch boundaries are separate maps of the
+form `{"batch_start": {"start_time": 0, "end_time": 0}}`. These are instruction
+metadata, not additional trace events. Event-only readers omit boundaries and
+annotations, so materialising a trace doesn't add gates or change snapshots.
+
+Barriers and classical delays use records with `source`, `uint_instruction`,
+`value` and `qubits` fields. `uint_instruction` is `GlobalBarrier`, `LocalBarrier`
+or `ClassicalDelay`, and `value` is a native uint64. Instruction readers preserve
+the full range. Public-event readers and `get_trace()` reject operands above
+`2^53 - 1` with an explicit error because the JSON schema cannot represent them.
+Smaller operands convert to the same gate events as before.
+
+Native opaque payload encoding belongs to the stream writer's wrappers. Using
+serde directly on the public Rust models keeps their ordinary representation,
+including hexadecimal tag strings and base64 data, even with a binary serializer.
+
+Rust's `TraceStreamWriter` buffers records between caller-selected checkpoints.
+Call `finish()` and check its result before publishing the destination. A failed
+append poisons the writer; it cannot subsequently produce a completed stream.
+`TraceStreamRecordReader` returns records with metadata, while `TraceStreamReader`
+returns public events. The Rust reader adapts native payload fields in memory
+before applying the existing model validation; it does not encode or parse JSON
+text. The Python reader uses `TypeAdapter.validate_python` directly.
+
+Python's `write_trace_stream` accepts an iterable and creates a new file without
+overwriting one. `iter_trace_stream_records` and `iter_trace_stream` read lazily
+without caching. Writers use gzip's fast compression setting. Callers own file
+lifetime and removal of failed output; readers never copy or delete artifacts.
+Interactive stacks also leave their run directories in place when closed or
+garbage-collected. Once you're finished reading traces and state dumps, call
+`stack.delete_run_directory()` to close the stack and remove its files. If the
+stack has already been collected, remove the directory yourself using the path
+you saved from `stack.configuration_path.parent`.
+The conventional suffix is `.msgpack.gz`.

selene_formats-0.1.1/docs/publishing.md

@@ -0,0 +1,18 @@
+# Publishing bindings
+
+Release Please manages the Python, Rust, and TypeScript bindings as one
+`selene-formats` component. A release PR updates every distribution to the
+same version. Merging it creates this tag:
+
+- `selene-formats-v<version>`
+
+The formats packages workflow tests and packages all three bindings before it
+publishes all three distributions. Releases are coordinated but not atomic.
+
+The binding packages share one version, which remains independent from a trace
+document's `schema_version`.
+
+Selene's wheel tests install the Python formats package directly from
+`selene-formats/`, alongside `selene-core/`. This lets us test model changes
+before publishing a new formats release. `just build-ci` uses the same
+installation steps locally through cibuildwheel. Run it inside devenv.

selene_formats-0.1.1/docs/trace/0.1.0.md

@@ -0,0 +1,63 @@
+# Trace protocol 0.1.0
+
+Schema: [`../../schemas/trace/0.1.0.schema.json`](../../schemas/trace/0.1.0.schema.json)
+
+## Documents
+
+The schema accepts two top-level document shapes:
+
+* `Trace` represents one emulation shot and contains an `events` array.
+* `Traces` represents a collection and contains a `traces` array of
+  unversioned `TraceData` objects.
+
+Both top-level shapes carry `schema_version`. `TraceData` contains the same
+`events` field as a standalone `Trace`, but does not repeat the collection's
+version. To extract a member as a standalone `Trace`, attach the enclosing
+`schema_version`. A collection may be empty, and its traces retain their given
+order.
+
+## Event ordering and sources
+
+`events` is ordered by observation during one emulation shot. An event's
+`source` identifies the stage that emitted it:
+
+* `UserProgram`: `index` is that source's zero-based event index.
+* `Runtime`: `start_time` and `end_time` are nanoseconds in the runtime's shot
+  timeline.
+* `ErrorModel`: `index` is that source's zero-based event index.
+* `Simulator`: `index` is that source's zero-based event index, and
+  `duration_ns` is the wall-clock duration spent in the simulator call.
+
+Indices are meaningful within a source only. Consumers must preserve event
+order and must not assume that sources have equal event counts.
+
+Indices, qubit IDs, timestamps, and durations are non-negative JSON integers no
+larger than `9007199254740991`, so they can be represented exactly by a
+JavaScript `number`. Opaque-payload tags retain the full unsigned 64-bit range
+and are encoded as canonical hexadecimal strings: a lowercase `0x` prefix
+followed by one to sixteen uppercase hexadecimal digits, with no leading zeroes
+except for `"0x0"`. For example, `"0x11A12517"` is a valid tag, and the maximum
+is `"0xFFFFFFFFFFFFFFFF"`. Gate parameters and values in
+`KeyValuePairPayload` may be signed.
+
+## Encoding
+
+`OpaquePayload.data` is base64url-encoded in JSON. Padding may be omitted;
+unused bits in the final Base64 character must be zero. `KeyValuePairPayload` is for
+interoperable, structured custom metadata; consumers that do not understand an
+application-specific key should preserve it when they re-emit the trace.
+
+Gate `params` are JSON booleans or numbers. Integer-valued numbers in gate
+parameters and `KeyValuePairPayload` values (including arrays) must be between
+`-9007199254740991` and `9007199254740991`, inclusive. This also applies to
+integer-valued floating-point notation such as `1e20`, which is rejected.
+Fractional numbers remain supported. Gate parameter interpretation is determined
+by `gate_name`.
+
+## Version 0.1.0
+
+Version 0.1.0 adds the required `schema_version` field and the `Traces`
+collection document. Every `kind` discriminator is required in a serialized
+trace. Versionless singular traces using the previous numeric opaque-payload
+tag are described by the [`legacy` schema](legacy.md) and can be upgraded by
+the language packages.

selene_formats-0.1.1/docs/trace/legacy.md

@@ -0,0 +1,27 @@
+# Legacy trace format
+
+Schema: [`../../schemas/trace/legacy.schema.json`](../../schemas/trace/legacy.schema.json)
+
+Selene currently emits trace documents without a `schema_version` through
+`CircuitExtractor` and `selene_core.trace`. These documents use JSON integers
+for indices, qubit IDs, timestamps, durations, and `OpaquePayload.tag`.
+
+A missing `schema_version` identifies this format. Producers using the
+`selene-formats` packages emit the versioned format by default and also support
+legacy serialization for singular traces. Their adapters validate legacy input
+and upgrade it to the current in-memory model. Legacy output omits
+`schema_version` and serializes opaque tags as JSON integers; current validation
+bounds still apply. Collections have no legacy format.
+
+`OpaquePayload.data` accepts the standard or URL-safe Base64 alphabet, with
+optional padding. Unused bits in the final Base64 character must be zero.
+
+The supported legacy schema applies the current JavaScript-safe bounds to
+integer-valued gate parameters and key-value payload values, including arrays:
+`-9007199254740991` through `9007199254740991`. Fractional numbers remain
+supported. Historical traces with values outside those bounds cannot be
+upgraded by these adapters.
+
+Legacy opaque tags may exceed JavaScript's safe integer range. TypeScript
+consumers must pass the original JSON text to `parseTraceJson` to preserve such
+tags; parsing them first with `JSON.parse` loses information irreversibly.

selene_formats-0.1.1/docs/versioning.md

@@ -0,0 +1,9 @@
+# Versioning
+
+Public schemas use semantic versioning. A document's `schema_version` identifies
+its schema contract, not a Selene release. Schema files use their full version
+in their filenames.
+
+The only exception is the versionless legacy trace format. A trace with no
+`schema_version` is interpreted as that legacy format and may be upgraded by
+the model packages. New schemas and producers must always include a version.

selene_formats-0.1.1/examples/trace/all-event-types.json

@@ -0,0 +1,40 @@
+{
+  "schema_version": "0.1.0",
+  "events": [
+    {
+      "source": { "kind": "UserProgram", "index": 0 },
+      "event": {
+        "kind": "Gate",
+        "qubits": [0, 1],
+        "gate_name": "RZZ",
+        "params": [0.25, true],
+        "predicates": [{ "predicate": "ready", "result": true }]
+      }
+    },
+    {
+      "source": { "kind": "Runtime", "start_time": 20, "end_time": 50 },
+      "event": { "kind": "Measurement", "qubit": 0 }
+    },
+    {
+      "source": { "kind": "ErrorModel", "index": 0 },
+      "event": { "kind": "Reset", "qubit": 1 }
+    },
+    {
+      "source": { "kind": "Simulator", "index": 0, "duration_ns": 123 },
+      "event": {
+        "kind": "Custom",
+        "payload": { "kind": "OpaquePayload", "tag": "0x7", "data": "c2VsZW5l" }
+      }
+    },
+    {
+      "source": { "kind": "UserProgram", "index": 1 },
+      "event": {
+        "kind": "Custom",
+        "payload": {
+          "kind": "KeyValuePairPayload",
+          "data": { "name": "analysis", "attempt": 2, "accepted": true }
+        }
+      }
+    }
+  ]
+}

selene_formats-0.1.1/examples/trace/legacy.json

@@ -0,0 +1,25 @@
+{
+  "events": [
+    {
+      "source": { "kind": "UserProgram", "index": 0 },
+      "event": {
+        "kind": "Gate",
+        "qubits": [0],
+        "gate_name": "RXY",
+        "params": [0.5, 0],
+        "predicates": []
+      }
+    },
+    {
+      "source": { "kind": "Simulator", "index": 0, "duration_ns": 1 },
+      "event": {
+        "kind": "Custom",
+        "payload": {
+          "kind": "OpaquePayload",
+          "tag": 11616494188317837126,
+          "data": "dHJhY2U="
+        }
+      }
+    }
+  ]
+}

selene_formats-0.1.1/examples/trace/minimal.json

@@ -0,0 +1,18 @@
+{
+  "schema_version": "0.1.0",
+  "events": [
+    {
+      "source": {
+        "kind": "UserProgram",
+        "index": 0
+      },
+      "event": {
+        "kind": "Gate",
+        "qubits": [0],
+        "gate_name": "RXY",
+        "params": [0.5, 0],
+        "predicates": []
+      }
+    }
+  ]
+}

selene_formats-0.1.1/examples/trace/traces.json

@@ -0,0 +1,22 @@
+{
+  "schema_version": "0.1.0",
+  "traces": [
+    {
+      "events": []
+    },
+    {
+      "events": [
+        {
+          "source": {
+            "kind": "UserProgram",
+            "index": 0
+          },
+          "event": {
+            "kind": "Measurement",
+            "qubit": 0
+          }
+        }
+      ]
+    }
+  ]
+}

selene_formats-0.1.1/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "selene-formats"
+version = "0.1.1"
+description = "Selene formats for Python"
+readme = "python/README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+dependencies = ["pydantic~=2.12", "msgpack>=1.1,<2"]
+authors = [
+  { name = "Quantinuum" },
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+[project.urls]
+repository = "https://github.com/quantinuum/selene"
+
+[dependency-groups]
+test = ["jsonschema>=4.23", "pytest>=8.3"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["python/selene_formats"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"schemas/trace/0.1.0.schema.json" = "selene_formats/schemas/trace/0.1.0.schema.json"
+"schemas/trace/legacy.schema.json" = "selene_formats/schemas/trace/legacy.schema.json"
+
+[tool.hatch.build.targets.sdist.force-include]
+"schemas/trace/0.1.0.schema.json" = "schemas/trace/0.1.0.schema.json"
+"schemas/trace/legacy.schema.json" = "schemas/trace/legacy.schema.json"

selene_formats-0.1.1/python/README.md

@@ -0,0 +1,40 @@
+# selene-formats for Python
+
+Python models for the versioned, serializable Selene trace protocol. See the
+protocol documentation and JSON Schema in the repository's `selene-formats/`
+directory.
+
+```python
+from selene_formats.trace import (
+    SCHEMA_VERSION,
+    Trace,
+    TraceData,
+    Traces,
+    parse_trace_json,
+)
+
+trace = Trace(schema_version=SCHEMA_VERSION, events=[])
+traces = Traces(schema_version=SCHEMA_VERSION, traces=[TraceData(events=[])])
+upgraded = parse_trace_json(versionless_trace_json)
+legacy_json = trace.as_legacy().model_dump_json(indent=2)
+```
+
+`as_legacy()` returns a `LegacyTrace` sharing the current event models and
+validation rules. Its `model_dump()` and `model_dump_json()` omit
+`schema_version` and keep opaque tags numeric. `LegacyTrace` also accepts
+versionless input and defaults its internal version to `0.1.0`. Filtering and
+timing helpers retain legacy serialization. Collections have no legacy format.
+
+For trace streams, use the MessagePack API rather than the JSON document parser:
+
+```python
+from selene_formats.trace_stream import iter_trace_stream, write_trace_stream
+
+write_trace_stream("trace.msgpack.gz", trace.events)
+for event in iter_trace_stream("trace.msgpack.gz"):
+    print(event)
+```
+
+Use `iter_trace_stream_records` to include instruction metadata. Reads are lazy
+and uncached, so keep the source file available until iteration finishes. See
+the [stream format](../README.md#trace-streams) for framing and error handling.

selene_formats-0.1.1/python/selene_formats/__init__.py

@@ -0,0 +1,11 @@
+"""Selene formats for Python."""
+
+from . import trace, trace_stream
+from .schema import get_legacy_trace_schema, get_trace_schema
+
+__all__ = [
+    "get_legacy_trace_schema",
+    "get_trace_schema",
+    "trace",
+    "trace_stream",
+]

selene_formats-0.1.1/python/selene_formats/schema.py

@@ -0,0 +1,32 @@
+"""Access to the JSON Schema for the installed trace-model version."""
+
+import json
+from importlib.resources import files
+
+try:
+    from importlib.resources.abc import Traversable  # Python 3.11+
+except ImportError:
+    from importlib.abc import Traversable  # Python 3.10
+from pathlib import Path
+from typing import Any
+
+
+def _get_trace_schema_file(filename: str) -> Traversable:
+    schema_file = files("selene_formats").joinpath(f"schemas/trace/{filename}")
+    if not schema_file.is_file():
+        # The canonical schema lives outside the Python package in a source
+        # checkout and is force-included when building a distribution.
+        schema_file = Path(__file__).parents[2] / "schemas" / "trace" / filename
+    return schema_file
+
+
+def get_trace_schema() -> dict[str, Any]:
+    """Return a new dictionary containing the current trace JSON Schema."""
+    schema_file = _get_trace_schema_file("0.1.0.schema.json")
+    return json.loads(schema_file.read_text())
+
+
+def get_legacy_trace_schema() -> dict[str, Any]:
+    """Return a new dictionary containing the versionless legacy trace schema."""
+    schema_file = _get_trace_schema_file("legacy.schema.json")
+    return json.loads(schema_file.read_text())