Validate a target and inspect a reference compile¶
Take a two-atom program with local detuning through validation, discretization and public reference compilation. Identify the information each step adds, then introduce an invalid amplitude and an off-grid value. Complete local detuning and local Rabi control first. This example compiles locally; it does not execute a quantum evolution or submit to hardware.
Validation asks whether a declared program fits a target's capabilities and ranges. Discretization projects supported values onto the target grid. Reference compilation produces inspectable operations, logical schedule segments and source mappings. None of these steps by itself constitutes a hardware submission.
Use an explicit target snapshot¶
"""Inspect an offline reference compile for a typed local control.
Public reference compile projects native operations, schedule candidates,
source paths, and resources against explicit mock Target/Calibration snapshots.
It does not emit a private hardware payload or perform production allocation.
"""
from __future__ import annotations
import json
from cascaqit import (
AHSProgram,
AtomRegister,
MockNeutralAtomTarget,
SitePattern,
Waveform,
)
from cascaqit.compiler import CompilerPipeline
def main() -> None:
"""Compile one local-detuning program and inspect user-visible projections."""
target = MockNeutralAtomTarget.local_ahs_v0_1()
program = (
AHSProgram(
AtomRegister.line(count=2, spacing=5.0),
program_id="lesson.experimentalist.reference_compile",
)
.drive(
rabi=Waveform.constant(0.6, duration=0.2),
detuning=Waveform.constant(0.0, duration=0.2),
phase=0.0,
)
.local_detuning(
waveform=Waveform.constant(0.4, duration=0.2),
pattern=SitePattern.from_mapping({"q0": 1.0, "q1": 0.25}),
)
.measure()
)
validated = program.validate(target, shots=16)
discretized, _ = validated.discretize(target)
snapshot = target.to_snapshot(
snapshot_id="snapshot.lesson.experimentalist",
source="offline_lesson",
status="available",
effective_at="2026-07-20T00:00:00Z",
)
compiled = CompilerPipeline().compile(
discretized.program_ir,
target_snapshot=snapshot,
)
contract = compiled.metadata["compiler_pipeline_contract"]
payload = {
"track": "quantum_experimentalist",
"level": "expert",
"lesson": "reference_compile",
"facts": {
"native_operations": [
item["operation_type"] for item in compiled.native_operation_set
],
"schedule_segments": [
item["segment_id"] for item in compiled.compiled_schedule["segments"]
],
"local_source_paths": sorted(
key for key in compiled.source_map if "local_detuning" in key
),
"compiled_hash_present": len(compiled.stable_hash()) == 64,
"hardware_payload_emitted": contract["hardware_payload_emitted"],
"compiled_ir_only": True,
},
"boundaries": {
"hardware_execution": False,
"cloud_execution": False,
"network_accessed": False,
"credentials_loaded": False,
},
}
print(json.dumps(payload, sort_keys=True))
if __name__ == "__main__":
main()
python3 examples/user/tracks/quantum_experimentalist/05_expert_reference_compile_en.py
The local-capable mock target permits the patterned detuning. to_snapshot() records the target description supplied to the compiler. The literal date and offline_lesson source identify this teaching snapshot; they are not evidence that a device was calibrated at that time.
{
"boundaries": {
"cloud_execution": false,
"credentials_loaded": false,
"hardware_execution": false,
"network_accessed": false
},
"facts": {
"compiled_hash_present": true,
"compiled_ir_only": true,
"hardware_payload_emitted": false,
"local_source_paths": [
"channel.local_detuning",
"op.local_detuning.0"
],
"native_operations": [
"global_rydberg_drive",
"local_detuning"
],
"schedule_segments": [
"segment.global_rydberg_drive.0",
"segment.local_detuning.0"
]
},
"lesson": "reference_compile",
"level": "expert",
"track": "quantum_experimentalist"
}
The output contains a global Rydberg drive and a local-detuning operation, with corresponding schedule segments. The local source paths let a reader trace a compiled item back to the local control. compiled_hash_present identifies the compiled record, while hardware_payload_emitted = false and compiled_ir_only = true describe its scope. A list of segments is not proof that production control channels have been allocated.
Keep three checks separate¶
| Stage | Inspect | What it does not establish |
|---|---|---|
| Validation | Diagnostic severity, code and object path | Numerical convergence or experimental accuracy |
| Discretization | Adjusted field paths, new values and report diagnostics | That the original unmodified program was run with those new values |
| Reference compile | Operation types, schedule entries, mappings and source references | A private device payload or successful hardware execution |
Always stop and inspect errors before advancing. The example uses values already accepted by the target; it does not need to repair them.
Introduce and repair three problems¶
- Set the global Rabi amplitude to
100 rad/us. Callvalidate()and inspect its errors before trying to compile. Restore0.6after locating the invalid field. - Set local detuning to
0.4004 rad/us. Comparediscretize(target, policy="nearest")withpolicy="strict". Inspect both the returned waveform and the report diagnostics. - Replace
MockNeutralAtomTarget.local_ahs_v0_1()with the conservativev0_1()target. Explain why a program that works on the local-capable target can still be rejected here.
Check your reasoning
The large amplitude produces WAVEFORM_VALUE_OUT_OF_RANGE at the Rabi value. For the current grid, nearest projection changes 0.4004 to 0.4; strict keeps the input value and reports DISCRETIZATION_STRICT_GRID_MISMATCH. A returned object therefore does not imply that the strict result is acceptable. The conservative target reports LOCAL_DETUNING_CAPABILITY_UNSUPPORTED. Switching to a capable mock target describes another supported local model, not a way to enable real hardware by changing a flag.
Keep the source program and target snapshot with the compiled object when saving this exercise. A content identifier alone cannot reconstruct a missing target description. Continue with Rabi oscillations and interactions for a numerical study, or read validation and discretization for the general rules.
Concept reference: target capabilities.