Local Detuning¶
Run the complete offline example first:
python3 examples/user/analog_local_detuning.py
Each AHSProgram.local_detuning() call appends one diagonal Hamiltonian term. Repeated calls are retained in declaration order and add during state evolution.
Local detuning combines a time-dependent detuning waveform with either static site weights or a binary addressing schedule:
from cascaqit import AHSProgram, AtomRegister, MockNeutralAtomTarget
from cascaqit import SitePattern, Waveform
target = MockNeutralAtomTarget.local_ahs_v0_1()
program = AHSProgram(AtomRegister.line(count=2, spacing=5.0))
local_delta = program.parameter("local_delta", default=0.8004)
local_weight = program.parameter(
"local_weight", unit=None, lower_bound=0.0, upper_bound=1.0, default=0.25
)
program.drive(
rabi=Waveform.constant(1.2, duration=0.6),
detuning=Waveform.constant(0.1, duration=0.6),
phase=0.0,
).local_detuning(
waveform=Waveform.constant(local_delta, duration=0.6),
pattern=SitePattern.from_mapping({"q1": local_weight, "q0": 1.0}),
).measure()
bound = program.bind({})
validated = bound.validate(target, shots=32)
discretized, report = validated.discretize(target, policy="nearest")
result = bound.run(shots=32, seed=13, time_steps=800)
SitePattern must cover every filled register site exactly once. Each weight may be a number, a canonical dimensionless Parameter declared with unit=None, or a dimensionless Expression. Mapping input may use any key order, but the bound site_ids and numeric weights are projected into register order. Missing, extra, or duplicate sites remain validation errors.
Use SiteMask when the control is binary and sparse:
from cascaqit import SiteMask
mask = SiteMask.constant(("q0",), duration=0.6)
program.local_detuning(
waveform=Waveform.constant(0.4, duration=0.6),
pattern=mask,
)
SiteMask.constant() keeps the same selected sites for the complete control duration. The Builder expands it into register-ordered binary SiteAddressingIR; unknown or vacant ids are rejected.
Use SiteMask.piecewise() when the selected sites change during the pulse:
mask = SiteMask.piecewise(
duration=0.6,
frames=((0.0, ("q0",)), (0.3, ("q1",))),
)
Each frame starts at its declared time and remains active until the next frame. An empty frame turns the local term off temporarily. Duration, frame times, and site ids are numeric rather than parameterized, and interpolation is fixed to step.
Parameters may appear in the local waveform and site pattern and must be fully bound before validation. Bound weights must remain in [0, 1], and each pattern must contain at least one non-zero weight. Use MockNeutralAtomTarget.local_ahs_v0_1() for validation and discretization. The local target reports every adjusted field path, so callers can distinguish the bound parameter value from the discretized waveform value. AHSProgram.run() and LocalAhsSimulator() automatically select this local-capable target when a typed local-detuning term is present; an explicitly supplied conservative target is never replaced.
The local simulator evaluates
with the weights aligned to filled-site register order. The term can also run inside the bounded Local Hybrid shared-state path.
Public Reference Compile¶
Run python3 examples/user/analog_local_reference_compile.py for the complete build, bind, validate, discretize, compile, and local-run path. To compile directly, pass the discretized ProgramIR together with an explicit local target snapshot and matching local mock calibration to CompilerPipeline.compile().
The resulting ReferenceCompiledProgramIR contains one indexed op.local_detuning.N per term, additive logical segments, a patterned local channel reference, source mappings, and resource counts. This is a deterministic offline public contract. It does not create an ExecutionPackage, allocate a production channel, emit a private or hardware payload, call a backend, or access cloud/network/credentials. The conservative MockNeutralAtomTarget.v0_1() remains blocked.
This capability is experimental. The current release supports ordered additive local-detuning terms, numeric or parameterized static weights, and constant or piecewise binary masks. Dynamic masks are consumed by the ideal, density, trajectory, and Hybrid engines and are shown in the standard experiment report. Continuous mask interpolation, parameterized frame topology, production scheduling, decorator or Pulser lowering, hardware execution, cloud execution, and network submission remain unsupported. See Local Rabi Control for the transverse local term and run python3 examples/user/time_dependent_site_addressing.py for the 3x3 Hybrid example.