Validate an Analog program and inspect reference compilation¶
To inspect an Analog program with the compiler, validate it against a target, discretize it, then compile it. The result contains public reference information about controls, source locations and estimated resources. This workflow does not submit a hardware job.
- Call
program.validate(target, shots=...)to check geometry, waveforms, units and target constraints. - Call
discretize(target)on the validated program. Keep the returned program and change report, and inspect how times and control values were moved onto the target grid. - Capture the target specifications with
target.to_snapshot(...), then pass the discretized program toCompilerPipeline.compile(...). - Read diagnostics, pass records and
source_map. Save the original program, discretized program and target snapshot so you can explain control changes later.
Repeat the same compilation¶
"""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()
python examples/user/tracks/compiler_engineer/05_expert_reference_compile_provenance_en.py
{
"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"
}
Expect compilation_scope to be public_reference, with same_cache_key and same_compiled_hash both true. target_hash_matches compares target specifications; it does not compare hashes of the entire snapshot object.
The example still reports cache_status: miss and filesystem_cache_used: false. Generating the same key does not establish that a saved cache entry was found or reused. The snapshot timestamp is example metadata, not evidence of device calibration.
Review modified controls and failures¶
Start with the waveform, site or parameter identified by the diagnostic, then inspect the discretization report. Before removing a control to satisfy a target constraint, check whether the change preserves the physical conditions your experiment needs. Recheck the observables you care about after discretization.
Both hardware_payload_emitted and production_scheduling_performed are false here. Public target specifications describe constraints; they do not supply a production device, private calibration or a live submission path. For local experiments, use AHSProgram with LocalBackend.
See the validation and discretization lesson and reference compilation lesson for worked checks. Problem compilation addresses a separate task: generating native programs from an optimization problem.