Local Rabi Control¶
Run the offline example:
python3 examples/user/analog_local_rabi.py
Each AHSProgram.local_rabi() call appends one addressed Rabi amplitude, one shared phase, and one site-addressing object. Repeated calls are coherent Hamiltonian terms in declaration order; their complex amplitudes add before state evolution:
import math
from cascaqit import AHSProgram, AtomRegister, SitePattern, Waveform
program = AHSProgram(AtomRegister.line(count=2, spacing=5.0))
omega = program.parameter("omega", default=math.pi)
phi = program.parameter("phi", unit="rad", default=0.0)
weight = program.parameter(
"weight", unit=None, lower_bound=0.0, upper_bound=1.0, default=1.0
)
program.drive(
rabi=Waveform.constant(0.0, duration=1.0),
detuning=Waveform.constant(0.0, duration=1.0),
phase=0.0,
).local_rabi(
rabi=Waveform.constant(omega, duration=1.0),
phase=phi,
pattern=SitePattern.from_mapping({"q1": 1.0 - weight, "q0": weight}),
).measure()
result = program.bind({}).run(shots=64, seed=23, time_steps=400)
For this one-microsecond pulse, omega = pi and weight = 1 flip only q0; the expected dominant outcome is 10. A weight may be numeric or use a canonical dimensionless parameter/expression. Mapping input can use any key order, but it must cover every filled site exactly once. bind() checks the [0, 1] domain and non-zero-pattern invariant before the IR stores numeric weights in register order.
For binary addressing, SiteMask.constant(("q0",), duration=1.0) expresses the same (1.0, 0.0) pattern without register-sized zeros. SiteMask.piecewise() accepts frame start times and can include an all-off frame. The Builder rejects unknown or vacant ids and expands every frame before validation, compilation, visualization, or simulation. The runnable analog_local_rabi.py example compares a parameterized SitePattern with a constant mask; time_dependent_site_addressing.py exercises the dynamic form.
Use cascaqit.analog.SitePhasePattern when addressed sites need independent phase offsets. Numeric offsets or radian Parameter/Expression values bind into the same active-site order as the amplitude pattern. Validation checks the local Target capability and phase range before and after discretization; reference compilation, state-vector, subspace, density, trajectory, Hybrid execution, Result evidence, and the standard report consume the same typed IR. See Experiment Control And Register Lifecycle for a runnable parameterized example.
The simulator evaluates the transverse term
together with the global drive, detuning, interaction, and optional local-detuning terms. The same term runs through the scalable ideal, exact density, and trajectory Hybrid engines without resetting state at block boundaries.
Validation, discretization, pulse timeline visualization, resource estimates, and offline CompilerPipeline lowering include the local amplitude, phase, pattern, channel binding, source map, and additive schedule. The explicit local target reports rydberg.rabi.local; the conservative target rejects the term before execution. Pulser projection rejects it explicitly.
The current subset supports ordered coherent local-Rabi terms, a shared numeric or waveform phase per term, numeric or parameterized static weights in [0, 1], constant or piecewise binary masks, and numeric or parameterized per-site phase offsets. Dynamic masks and phase patterns are consumed by ideal, subspace, density, trajectory, and Hybrid execution. Continuous mask interpolation, parameterized frame topology, decorator/Pulser lowering, production channel allocation, hardware payloads, cloud execution, and network submission remain unsupported.