Inspect a reference compilation and its cache identity¶
Compile a discretized Analog program against a fixed public target snapshot. Inspect the pass records, source mapping and cache identity, then compile the same inputs again. Complete validation and discretization and use the installed environment.
Predict identical compilation content for identical inputs. Also predict that neither compile sends a pulse to hardware or obtains private calibration. This compiler produces public reference information for inspection and integration.
Follow the input into the compiled record¶
"""Audit pass, source-map, cache, and boundary provenance in reference compile.
The public compiler returns deterministic reference IR. Expert review checks
pass records, source paths, target/calibration hashes, cache identity, and the
explicit statement that no private payload or production scheduling was made.
"""
from __future__ import annotations
import json
from cascaqit import AHSProgram, AtomRegister, MockNeutralAtomTarget, Waveform
from cascaqit.compiler import CompilerPipeline
def main() -> None:
"""Compile one global Analog program and inspect provenance fields."""
target = MockNeutralAtomTarget.v0_1()
program = (
AHSProgram(
AtomRegister.line(count=1, spacing=5.0),
program_id="lesson.compiler.reference",
)
.drive(
rabi=Waveform.linear(0.0, 0.8, duration=0.2),
detuning=Waveform.constant(-0.2, duration=0.2),
phase=0.0,
)
.measure()
)
validated = program.validate(target, shots=16)
discretized, _ = validated.discretize(target)
snapshot = target.to_snapshot(
snapshot_id="snapshot.lesson.compiler",
source="offline_lesson",
status="available",
effective_at="2026-07-20T00:00:00Z",
)
compiled = CompilerPipeline().compile(
discretized.program_ir,
target_snapshot=snapshot,
)
repeated = CompilerPipeline().compile(
discretized.program_ir, target_snapshot=snapshot
)
cache_report = compiled.metadata["compile_cache_report"]
contract = compiled.metadata["compiler_pipeline_contract"]
pass_pipeline = compiled.metadata["compiler_pass_pipeline"]
payload = {
"track": "compiler_engineer",
"level": "expert",
"lesson": "reference_compile_provenance",
"facts": {
"pass_names": [item["pass_name"] for item in pass_pipeline["records"]],
"source_map_keys": sorted(compiled.source_map),
"same_cache_key": repeated.compile_cache_key == compiled.compile_cache_key,
"same_compiled_hash": repeated.stable_hash() == compiled.stable_hash(),
"target_hash_matches": compiled.target_snapshot_hash
== snapshot.target_snapshot_hash,
"cache_status": cache_report["status"],
"filesystem_cache_used": cache_report["filesystem_cache_used"],
"cache_key_present": len(compiled.compile_cache_key) == 64,
"target_hash_present": bool(compiled.target_snapshot_hash),
"compilation_scope": compiled.compilation_scope,
"private_calibration_present": "calibration_snapshot_hash"
in compiled.to_dict(),
"hardware_payload_emitted": contract["hardware_payload_emitted"],
"production_scheduling_performed": compiled.channel_schedule[
"production_channel_allocation_performed"
],
},
"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/compiler_engineer/05_expert_reference_compile_provenance_en.py
The target snapshot records which public specification was used. Its fixed effective_at in this lesson is example metadata, not proof that a device was calibrated at that time. CompilerPipeline.compile(...) receives the discretized program and snapshot, then returns a public_reference artifact.
{
"boundaries": {
"cloud_execution": false,
"credentials_loaded": false,
"hardware_execution": false,
"network_accessed": false
},
"facts": {
"cache_key_present": true,
"cache_status": "miss",
"compilation_scope": "public_reference",
"filesystem_cache_used": false,
"hardware_payload_emitted": false,
"pass_names": [
"validation",
"discretization",
"target_binding",
"analog_lowering",
"control_binding",
"source_map",
"resource_estimate",
"backend_readiness"
],
"private_calibration_present": false,
"production_scheduling_performed": false,
"same_cache_key": true,
"same_compiled_hash": true,
"source_map_keys": [
"channel.global",
"control_system",
"measurements",
"op.global_rydberg_drive"
],
"target_hash_matches": true,
"target_hash_present": true
},
"lesson": "reference_compile_provenance",
"level": "expert",
"track": "compiler_engineer"
}
Read the pass records in their execution order: validation, discretization, target binding, Analog lowering, control binding, source map, resource estimate and Backend readiness. A pass name describes its role in the public pipeline. In particular, Backend readiness here does not perform private calibration or authorize hardware submission.
The source map connects compiled elements such as the global drive and measurement to source information. Inspect it when a compiled item or diagnostic is surprising. Keep the original and discretized programs too: a source map does not reconstruct all author intent or decide whether a control change is acceptable.
target_hash_matches compares the compiled target reference with snapshot.target_snapshot_hash. That field identifies the contained target specification. It is not the same as hashing the entire snapshot wrapper, which also has its own identity and metadata. Compare the same kind of hash at each boundary.
A cache key is not a cache hit¶
Both same_cache_key and same_compiled_hash should be true. The cache key depends on the program inputs, target specification, compiler version/options and parameter/bit-order conventions. Repeating those inputs gives the same identity.
The reported cache status is still miss, and filesystem_cache_used is false. This example constructs cache metadata without supplying a stored entry; it does not write a disk cache or skip work on the second call. Deterministic output, a valid cache lookup and actual reuse are separate observations.
The boundary fields should report no private calibration, no hardware payload and no production channel allocation. Those values are consistent with the public reference scope. Do not rename the output a device-ready program merely because it contains channels, pass records or a target hash.
Check a deliberate change¶
- Change the ramp endpoint from
0.8to0.9 rad/us, preserving the rest of the input. Compare the cache key with the original run. - Compile unchanged input twice and inspect the cache report, not only the key. What would constitute evidence of a stored entry actually being reused?
- A report includes a
backend_readinesspass. List the additional evidence you would need before claiming hardware execution.
The changed waveform produces a different program and cache identity. A repeated key alone does not prove a cache hit; a consumer must inspect the actual lookup/match result and reuse behavior. Hardware execution would require a supported live submission path and a real execution result, along with the device-specific checks required by that path. This public reference pipeline supplies none of those live facts.
See reference compilation for the user-facing Analog path and current limitations for execution boundaries. Keep these distinctions when building compiler tools or displaying compilation progress to researchers.