AHSProgram¶
from cascaqit import AHSProgram
AHSProgram ¶
AHSProgram(
register: AtomRegister,
*,
program_id: str = "program",
interaction: VanDerWaalsInteraction | None = None,
)
Declare an analog quantum program from an atom register, control waveforms and measurements. register supplies geometry and logical order; interaction can specify a van der Waals interaction explicitly. run() computes locally and returns ResultIR.
Use us for time, rad/us for Rabi frequency and detuning, rad for phase, and um for coordinates. Call drive() and, for standalone execution, measure(). Bind symbolic parameters before execution. Drive, local-control and measurement methods mutate this builder and return it; bind() returns an independent program.
See Waveform design and Local Rabi controls for complete examples. Use LocalBackend for noise, execution planning or job records.
Controls and measurement¶
Set the global rabi, detuning and phase. Calling it again replaces the previous global drive. The first two arguments must be Waveform objects; phase may be numeric, a declared parameter, an expression or a phase waveform. Waveform parameters must belong to this program and have matching units. Wrong types raise TypeError; ownership or unit mismatches produce validation errors.
Append a local detuning term. waveform defines its time dependence; pattern supplies SitePattern weights or a binary SiteMask. Repeated calls retain additive terms in declaration order. Export maps addressing to filled target sites: dense weights must cover those sites, and a dynamic mask must have the same duration as its control.
local_rabi ¶
local_rabi(
*,
rabi: Waveform,
phase: AnalogPhaseValue,
pattern: SiteAddressing,
phase_pattern: SitePhasePattern | None = None,
) -> AHSProgram
Append an addressed Rabi drive with amplitude rabi, shared phase and weights or mask in pattern. The optional phase_pattern, a cascaqit.analog.SitePhasePattern, supplies site-specific phase offsets. Drives add coherently; amplitudes are not independent probabilities. Execution still depends on the target's supported channels and constraints.
Append a terminal measurement and return this program. The default basis is ground_rydberg: result bits 0/1 represent ground/Rydberg states. Choose a recognizable measurement_id. Declaring a measurement does not start simulation.
Parameters and export¶
parameter ¶
parameter(
name: str,
*,
unit: str | None = "rad/us",
lower_bound: float | None = None,
upper_bound: float | None = None,
default: float | None = None,
) -> Parameter
Declare a float parameter owned by this program and return Parameter. unit defaults to rad/us; use rad for phase and None for dimensionless weights. Bounds and the optional default constrain binding. Duplicate names or invalid declarations raise ProgramValidationError.
Return parameter declarations in declaration order as a tuple, suitable for inspection, interfaces or scans.
Report whether all control values have been resolved to numbers. This checks parameter state; True does not establish that drive, measurement or target requirements are satisfied.
Bind values by name and return an independent AHSProgram. Referenced parameters omitted from the mapping use their declared defaults; those without defaults are required. Unknown names, missing values, nonfinite numbers and bound violations raise ProgramValidationError. Call bind({}) explicitly even when all referenced parameters have defaults.
Return a numeric ProgramIR. Missing global drive, missing standalone terminal measurement or unresolved typed parameters raise ProgramValidationError. Export does not perform target validation, discretization or simulation.
Return bind(values).to_ir(), a ProgramIR. Use bind() when you want to keep working with the builder.
Validation and execution¶
Validate the numeric program against target and shots. Return ValidatedAHSProgram, which stores the program and diagnostics; inspect diagnostics for errors before proceeding. Receiving this wrapper does not establish successful validation. Export failures such as missing declarations can also raise errors. After checking diagnostics, discretize(target) returns a pair containing the discretized program and its report. This return type differs from the diagnostic tuple returned by digital Circuit.validate().
run ¶
run(
*,
shots: int = 1000,
seed: int | None = None,
target: TargetSpec | None = None,
time_steps: int = 400,
return_probabilities: bool = True,
optimization_level: int = 0,
) -> ResultIR
Execute locally and return ResultIR. shots controls terminal sampling, seed controls random sampling, and time_steps controls the integration discretization. More shots do not reduce integration error. return_probabilities=True requests state probabilities. target supplies the specification checked during local simulation; for local controls, pass a supporting target such as MockNeutralAtomTarget.local_ahs_v0_1().
optimization_level supports 0 and 1; level 1 applies semantics-preserving program simplification. Invalid programs, targets or configurations fail execution. Successful construction alone does not establish executability. Check step convergence separately and distinguish state probabilities from finite-shot counts when reporting research results.