qat.experimental.system_data.materialisers.purr.materialise module

PuRR-to-canonical materialisation orchestration for the experimental boundary.

This module keeps the public materialisation entrypoint and coordinates adaptation, ingress validation, and canonical assembly via domain-specific builders.

Stage architecture

PuRR materialisation is intentionally staged so source-boundary concerns remain separate from compiler-owned enrichment and canonical assembly:

  1. Source version compatibility check.

  2. Source payload adaptation into boundary-normalised plain data.

  3. Source ingress DTO validation and graph consistency validation.

  4. Compiler-owned enrichment required for canonical assembly.

  5. Canonical system data construction from validated/enriched ingress DTO.

This separation allows validation responsibility to move upstream over time without changing canonical assembly responsibilities.

class PurrMaterialiserV010(*, target_data=None, supported_acquire_modes=None, native_waveform_shapes=None, operation_builder_type=<class 'qat.experimental.system_data.materialisers.operations.defaults.DefaultOperationBuilder'>, extra_operations=())

Bases: object

Template-method materialiser for PuRR v0.1.0 source payloads.

Subclass and override prepare_ingress(), build_qubits(), build_channels(), build_couplings(), or assemble() to customise specific pipeline stages without duplicating the full flow.

materialise() orchestrates the standard validation and assembly stages. Subclasses are intended to customise the flow through the hooks documented above.

assemble(*, dto, source_version)

Assemble canonical system data from the enriched ingress DTO.

Calls build_qubits(), build_channels(), and build_couplings(). Override to substitute a different output model or to add top-level fields (e.g. an extended hardware model).

Parameters:

  • dto (PurrIngressV010) – Enriched, fully-validated ingress DTO.

  • source_version (str) – Source contract version, written to metadata.

Return type:

CanonicalSystemData

Returns:

Assembled canonical system data.

build_channels(*, dto)

Build logical channel data from the enriched ingress DTO.

Parameters:

dto (PurrIngressV010) – Enriched, fully-validated ingress DTO.

Return type:

tuple[ChannelData, ...]

Returns:

Tuple of channel data for canonical assembly.

build_couplings(*, dto)

Build qubit coupling data from the enriched ingress DTO.

Parameters:

dto (PurrIngressV010) – Enriched, fully-validated ingress DTO.

Return type:

tuple[QubitCouplingData, ...]

Returns:

Tuple of coupling data for canonical assembly.

build_operation_builder(*, qubit_payload, reset_methods, default_reset_method, ddrop_delay_ps)

Build the operation builder for a single qubit.

Override to supply a hardware-specific builder or to inject extra constructor arguments for a particular qubit.

Parameters:

  • qubit_payload (dict[str, Any]) – Raw PuRR quantum-device payload for the qubit.

  • reset_methods (tuple[ResetData, ...]) – Reset method objects from canonical assembly.

  • default_reset_method (str | None) – Default reset method identifier.

  • ddrop_delay_ps (int | None) – DDrop reset delay in picoseconds, or None.

Return type:

AbstractOperationBuilder

Returns:

A configured, ready-to-use operation builder instance.

build_qubits(*, dto, reset_methods, default_reset_method)

Build per-qubit data from the enriched ingress DTO.

Parameters:

  • dto (PurrIngressV010) – Enriched, fully-validated ingress DTO.

  • reset_methods (tuple[ResetData, ...]) – Pre-built reset method objects from assemble().

  • default_reset_method (str | None) – Default reset method identifier.

Return type:

tuple[QubitData, ...]

Returns:

Tuple of qubit data for canonical assembly.

materialise(*, adapted_payload, source_version, strict_version_check=True)

Run the full PuRR materialisation pipeline.

Orchestrates all pipeline stages. Boundary validation is non-bypassable; subclass customisation is via prepare_ingress(), build_qubits(), build_channels(), build_couplings(), and assemble().

Parameters:

  • adapted_payload (dict[str, Any]) – Pre-adapted (boundary-normalised) PuRR payload. Callers are responsible for running the source-specific adapter before invoking this method; passing a raw jsonpickle payload will fail at ingress DTO validation with a confusing error.

  • source_version (str) – Source contract version.

  • strict_version_check (bool) – When True (default), raises UnsupportedSourceVersionError if source_version is not in _SUPPORTED_PURR_SOURCE_VERSIONS. Set to False to attempt materialisation with an unrecognised version; DTO validation may still fail if the payload shape is incompatible.

Return type:

CanonicalSystemData

Returns:

Materialised canonical system data.

Raises:
prepare_ingress(*, adapted_payload, source_ingress_dto)

Enrich the adapted payload before canonical assembly.

Called after boundary validation; the returned dict is re-validated before assembly. Override to inject hardware-specific fields alongside or instead of the standard compiler enrichment.

Parameters:

  • adapted_payload (dict[str, Any]) – Boundary-normalised payload from the adapter.

  • source_ingress_dto (PurrIngressV010) – Validated ingress DTO from the adapted payload.

Return type:

dict[str, Any]

Returns:

Enriched payload dict ready for the second model_validate pass.