01 What the control system has to do
An experiment is a sequence of switches, ramps and triggers. The control system turns a description of that sequence into voltages at the right instant, every shot, and records what happened.
Time comes from a clock, not the PC
A Python script on a desktop cannot promise when a line of code runs: the operating system can pause it for milliseconds. So the PC only describes the sequence; a dedicated timing device (an FPGA, a pulse generator or a DAQ card with its own sample clock) plays it out. Everything below follows from this split.
Thousands of identical shots
Most measurements average many shots or scan one parameter while everything else stays fixed. A useful system lets you change one number (a detuning, a hold time) between shots and guarantees that nothing else moved.
Every shot leaves a record
Months later someone will ask what the imaging detuning was on a given run. The parameters, the code version and the data should be stored together, shot by shot, automatically.
02 Anatomy: from a Python script to photons
The same layout appears in almost every lab, whatever the brand: a PC that writes and schedules sequences, a real-time core that owns the clock, output and input cards, and the lab hardware those cards drive.
Real-time links in the page accent colour; dashed = signals coming back. Slow instruments never sit in the real-time path: they are set between shots, so their latency does not matter.
On the PC: the experiment description, parameter scans, the queue of experiments, plots, the data files, and drivers for slow instruments.
On the real-time core: the timeline itself, plus any decision that must be made within microseconds (count photons, then decide whether to fire the next pulse).
Anything that crosses back to the PC during a shot is slow and unpredictable (milliseconds). ARTIQ's manual makes the point concretely: after a call back to the host, the next real-time event must be pushed into the future again or it raises an underflow. Keep timing-critical logic on the core.
03 The signals you will wire
Five kinds of signal cover nearly everything. The examples are real hardware specifications, from the Sinara (ARTIQ) datasheets and the NI PCIe-6363 manual, so you can see the order of magnitude a modern system offers.
| Signal | What it drives | Typical numbers (example hardware) | What bites people |
|---|---|---|---|
| TTL (digital) | AOM RF switches, shutters, camera and scope triggers, coil switches, gating counters | Sinara 8-channel BNC/SMA cards: minimum pulse 3 ns (typ. 5 ns), ~350 ps peak jitter, galvanically isolated in banks of four, 50 Ω or high-Z per channel. ARTIQ places edges on a 1 ns grid. | Logic levels (5 V vs 3.3 V), driving a 50 Ω load, unterminated cables ringing, a TTL line that is a ground loop. |
| DDS / RF | AOM and EOM frequency, phase and amplitude; Raman and microwave tones (with a synthesizer) | Urukul (AD9910): 4 channels, 1 GS/s, output <1 to >400 MHz, 0.25 Hz frequency steps, 14-bit amplitude, 0–31.5 dB attenuator, RF switch with 70 dB isolation. Mirny: 53 MHz–4 GHz synthesizer. | Phase continuity when you change frequency; images and spurs; forgetting that a frequency change takes time to program. |
| DAC (analog out) | Coil-driver setpoints, laser and tweezer power (via AOM amplitude), piezo offsets, servo setpoints | Zotino: 32 × 16-bit, ±10 V, 1 MS/s shared, 75 kHz bandwidth. Fastino: 32 × 16-bit, up to 2.55 MS/s per channel with current gateware. NI PCIe-6363: 4 × 16-bit, 2.86 MS/s (one channel) to 1.25 MS/s (all four). | 16 bits over 20 V is 305 µV per step; the output filter (here 75 kHz) rounds fast steps; the driver downstream is usually slower than the DAC. |
| ADC (analog in) | Photodiode powers, error signals, monitor voltages, intensity servo inputs | Sampler: 8 × 16-bit, 1.5 MS/s simultaneous, programmable gain from ±10 V to ±10 mV. NI PCIe-6363: 32 inputs, 16-bit, 2 MS/s single-channel (1 MS/s aggregate). | Aliasing (filter before you sample), ground offsets, input range set too wide so the signal uses a few bits. |
| AWG (fast arbitrary RF) | Multi-tone AOD drive for tweezer arrays and rearrangement, shaped Raman or Rydberg pulses | Phaser: 4 × 16-bit DAC channels at 1.25 GS/s with IQ upconversion (0.3–4.8 GHz LO). Standalone AWG cards are common for tweezer rearrangement. | Memory and streaming bandwidth, phase relationships between tones, intermodulation in the RF amplifier. |
A counter on a TTL input turns single-photon detector clicks into a number inside the shot. The Sinara TTL datasheet quotes a gateware edge counter of up to 125 million events per second. That is how "is there an atom in this tweezer?" becomes a decision in microseconds instead of a camera frame later.
Cameras are triggered by TTL and usually report back an "exposure active" output. Wire that output to a scope or an input at least once: the real exposure window is rarely exactly where the trigger edge suggests. Frame grabbers (Sinara's Grabber reads CameraLink) can extract regions of interest in real time.
04 Timing: resolution, jitter, latency and hardware delays
The control system can place an edge to the nanosecond. The hardware it drives cannot respond that fast, and each device lags by a different amount. Good sequences are written for what the atoms see, not for what the TTL line does.
One shot, channel by channel
A tweezer-loading shot. Solid lines are what the control system outputs; dashed lines are what the hardware actually does. Click a channel name for what it is and what goes wrong. Each phase has its own time scale.
Delay values are illustrative (shutter: a few ms of delay plus sub-ms jitter; coils: an L/R decay of about a millisecond; AOM: tens to hundreds of ns, invisible at this scale). Measure your own: the numbers depend on the shutter, the coil inductance and the driver.
Code on the core moves a timeline cursor, now_mu, forward with delay(); outputs are timestamped with the cursor and queued in FIFOs; the hardware fires each event when the wall clock reaches its timestamp. The machine unit is normally 1 ns; the coarse RTIO clock is commonly 125 MHz, so events are processed in 8 ns cycles with 1 ns fine placement.
The gap between cursor and wall clock is the slack. If code falls behind and submits an event whose time has passed, ARTIQ raises RTIOUnderflow. Two events on the same channel at the same coarse time collide and are dropped.
The labscript suite compiles the whole shot in Python, then plays it from a pseudoclock: a pulse generator (a SpinCore PulseBlaster, or the Raspberry-Pi-Pico-based PrawnBlaster) that ticks only when something must change. DAQ cards and DDS boards update on those ticks. Each shot is stored as an HDF5 file holding the globals and the compiled instructions.
The resolution is set by the pulse generator's clock (labscript encodes 20 ns for a PulseBlaster-USB, 4 ns for the ESR-PRO-500), and a few clock cycles are the minimum interval between instructions.
05 Engineering pulses and ramps
A light pulse is not just "on for T". Its shape sets its spectrum, and the spectrum decides which transitions it drives. Square pulses are easy to program and spectrally dirty; shaped pulses cost a little length and buy a lot of cleanliness.
Pulse shape and its spectrum
Top: the intensity envelope in time. Bottom: its power spectrum in dB against detuning, in units of 1/T and in kHz for the chosen length. The marker shows a neighbouring transition (for example a motional sideband at the trap frequency) and how much the pulse drives it.
Computed in the page with a numerical Fourier transform of the envelope (the AOM rise is a Gaussian smoothing of the edges). All shapes have the same total length T, so smooth shapes have a wider central lobe but far lower side lobes: about −13 dB for a square pulse, about −58 dB for Blackman.
- Raman and sideband pulses next to a carrier.
- Rydberg pulses, where leakage drives unwanted states (see the gate error budget).
- Fast switching of trap light, where a hard edge heats the atom.
- DDS amplitude profiles or on-chip RAM (the AD9910 in Urukul has a waveform RAM for this).
- A DAC driving a voltage-controlled attenuator or the AOM driver's amplitude input.
- An AWG that synthesises the shaped RF directly.
- Linear ramps for detunings and fields.
- Exponential or piecewise ramps for evaporation.
- Smooth (minimum-jerk or sin²) profiles for moving tweezers, so atoms are not heated by sudden acceleration.
- Enough points: a DAC at 1 MS/s gives 1000 steps per millisecond.
06 How fine, how fast: a signal budget
Before choosing hardware or writing a sequence, check that each channel can resolve what the physics needs. Change any input; every result updates.
DAC
DDS
AOM
Cabling
Formulas: DAC step = range / 2bits; DDS step = fclk / 2N; AOM optical rise time τ ≈ 0.65 d/V and modulation bandwidth ≈ 0.35/τ (Isomet application note AN2600; acoustic velocities from the same note); coax delay ≈ 5 ns/m for a velocity factor of 0.66.
07 Which system? ARTIQ, labscript, NI and the rest
You will usually inherit a system rather than choose one. Knowing the families helps you read a new lab's code and judge what it can and cannot do.
An FPGA that runs your Python
Started in 2013 by NIST's Ion Storage Group with M-Labs; open source (LGPLv3+ software, CERN-OHL hardware). Experiments are Python classes; methods marked @kernel are compiled and run on the FPGA core (Kasli: Artix-7, 12 slots for Sinara cards), the rest runs on the PC. Distributed RTIO (DRTIO) links several crates over fibre. A 2023 review of open quantum hardware counted almost a thousand experiments using ARTIQ/Sinara.
Best at: nanosecond timing, real-time decisions (count, then act), large channel counts. Costs you: learning the timeline model and its errors.
Compile the whole shot, then play it
From Monash (Starkey et al., Rev. Sci. Instrum. 84, 085111, 2013). You write the shot in Python; runmanager fills in parameters and builds one HDF5 file per shot; BLACS runs the hardware; lyse analyses shots as they arrive; runviewer plots the compiled instructions. It drives off-the-shelf hardware: PulseBlaster and PrawnBlaster pseudoclocks, NI-DAQmx cards, NovaTech DDS, many cameras.
Best at: mixing commercial hardware, a clean record of every shot. Costs you: no decisions inside a shot.
Buffered, hardware-timed cards
Multifunction cards such as the PCIe-6363 (4 analog outputs, 32 inputs, 48 digital lines with 32 hardware-timed up to 10 MHz, a 100 MHz timebase) are a common first system, programmed in LabVIEW or from Python with the official nidaqmx package. Several cards share a clock and a start trigger to act as one.
Best at: availability and drivers. Costs you: slower digital timing, and sequencing logic you must build yourself.
When the RF is the experiment
Boards built on Xilinx RFSoC (the open QICK project reached over 40 labs within two years) and commercial controllers from Quantum Machines, Zurich Instruments, Keysight and others generate GHz waveforms directly with fast feedback. They are common in superconducting-qubit labs and increasingly used for Rydberg and Raman control. Pulser (from Pasqal) describes neutral-atom pulse sequences at a higher level.
Best at: wideband shaped RF. Costs you: price or closed software.
08 Running the experiment from Python
Whatever the hardware, the pattern is the same: name the channels once, describe one shot in terms of physical parameters, scan those parameters from outside, and save everything. The sketches below show that pattern in four common stacks; device names come from your lab's configuration.
from artiq.experiment import * class LoadAndImage(EnvExperiment): def build(self): self.setattr_device("core") self.setattr_device("ttl_cooling") # names are defined in device_db.py self.setattr_device("ttl_camera") self.setattr_device("urukul0_ch0") # imaging AOM (DDS + RF switch) self.setattr_device("zotino0") # DAC: MOT coil-driver setpoint self.setattr_argument("t_load", NumberValue(200*ms, unit="ms")) self.setattr_argument("detuning", NumberValue(-10*MHz, unit="MHz")) @kernel def run(self): self.core.reset() self.urukul0_ch0.cpld.init() self.urukul0_ch0.init() self.zotino0.init() delay(1*ms) # build up slack before the first event self.zotino0.set_dac([2.5], [0]) # coils on self.ttl_cooling.on() delay(self.t_load) # load the MOT self.ttl_cooling.off() self.zotino0.set_dac([0.0], [0]) # coils off delay(2*ms) # wait for the field to decay (measured!) self.urukul0_ch0.set(80*MHz + self.detuning, amplitude=0.8) with parallel: # camera and light open together self.ttl_camera.pulse(30*us) self.urukul0_ch0.sw.pulse(20*us)
# Count fluorescence photons for 200 us; continue only if an atom is there. @kernel def run(self): self.core.reset() delay(1*ms) self.ttl_probe.on() n = self.ttl_spcm.count(self.ttl_spcm.gate_rising(200*us)) # gate, then read the count self.ttl_probe.off() delay(10*us) # reading put the cursor in the past: restore slack if n > self.threshold: self.ttl_rydberg.pulse(1*us) # the decision was made on the FPGA, in microseconds else: self.ttl_flag.pulse(1*us) # e.g. mark the shot as empty
# One shot. Devices come from the lab's connection table; # t_load and detuning are runmanager globals, so scans need no code changes. from labscript import start, stop, add_time_marker start() t = 0 add_time_marker(t, "Load MOT") cooling_aom.go_high(t) # DigitalOut mot_coils.constant(t, 2.5) # AnalogOut (V into the coil driver) t += t_load mot_coils.ramp(t, duration=20e-3, initial=2.5, final=0.0, samplerate=1e4) cooling_aom.go_low(t) t += 20e-3 + 2e-3 add_time_marker(t, "Image") camera.expose(t, "atoms", trigger_duration=30e-6) imaging_aom.go_high(t) imaging_aom.go_low(t + 20e-6) t += 1e-3 stop(t) # compiled into this shot's HDF5 file, with the globals
# A hardware-timed 10 ms analog ramp that waits for a trigger from the master clock. import numpy as np, nidaqmx from nidaqmx.constants import AcquisitionType, Edge ramp = np.linspace(0.0, 5.0, 1000) # 1000 samples with nidaqmx.Task() as ao: ao.ao_channels.add_ao_voltage_chan("Dev1/ao0") ao.timing.cfg_samp_clk_timing(100_000, # 100 kS/s → 10 ms sample_mode=AcquisitionType.FINITE, samps_per_chan=len(ramp)) ao.triggers.start_trigger.cfg_dig_edge_start_trig("/Dev1/PFI0", Edge.RISING) ao.write(ramp, auto_start=False) # load the buffer first ao.start() # armed; the card's clock does the timing ao.wait_until_done(timeout=5.0)
# Instruments outside the real-time path: set them between shots, record what you set. import pyvisa rm = pyvisa.ResourceManager() synth = rm.open_resource("TCPIP0::192.168.1.20::INSTR") print(synth.query("*IDN?")) # always log what you are talking to synth.write("FREQ 6.834682611 GHz") # e.g. the Rb-87 ground hyperfine splitting synth.write("POW -10 dBm") settings = {"mw_freq_GHz": 6.834682611, "mw_pow_dBm": -10} # → save into the shot file
Sketches, not drop-in code: check the API version of your ARTIQ, labscript or nidaqmx release. The ARTIQ calls follow the ARTIQ manual (experiment classes, @kernel, setattr_argument, gate_rising/count); the labscript calls follow its device API; the NI example uses nidaqmx's hardware-timed sample clock and start trigger.
Expose physical parameters as arguments or globals and scan them from the dashboard or runmanager. Randomise or interleave the scan order so a slow drift (a laser, the room temperature) does not masquerade as a signal.
Both ARTIQ and labscript write HDF5. Store the parameters, the code version, the raw data and the analysis results of each shot together. ARTIQ's master keeps an HDF5 record of every experiment it runs.
Log slow signals (laser powers, wavemeter readings, lab temperature, vacuum pressure) continuously, with timestamps, into a database the analysis can query. When a dataset looks odd, the first question is what else changed.
09 Working as a team: git and GitHub
An apparatus outlives every student who works on it. Its code is written by many people, often at 2 a.m., and has to keep working. Version control is not optional.
- One repository for the experiment: device configuration, sequences, drivers, analysis. Data stays out of it.
- Commit small changes with messages that say why ("compensate 3.1 ms shutter delay, measured 2026-11-02").
- Never leave uncommitted edits on the lab computer overnight; the next person cannot tell what changed.
- Write the commit hash into every data file, so any result can be traced to the exact code that produced it.
- A protected main branch that always runs; new features on branches; changes merged by pull request after someone else reads them.
- Issues for broken hardware and planned work, so knowledge does not live in one person's head.
- Pin the software environment (ARTIQ uses Nix; conda or pip lock files elsewhere) so an update cannot silently change the machine.
- A few automated tests that compile every sequence, run on each push.
# a typical day git switch main && git pull # start from what everyone agreed on git switch -c imaging-detuning-scan # your change gets its own branch # ... edit, run a test shot ... git add sequences/imaging.py git commit -m "Scan imaging detuning; add 3.1 ms shutter lead (measured)" git push -u origin imaging-detuning-scan # open a pull request; a labmate reviews it # in the experiment, record the code version with the data rev = subprocess.check_output(["git", "rev-parse", "HEAD"]).decode().strip()
Repository layout that works: device_db.py or connection_table.py (hardware), sequences/ (shots), lib/ (shared building blocks such as "image atoms"), drivers/, analysis/, tests/, and a README that tells a new student how to run one shot. For the wider habits, see Wilson et al., "Good enough practices in scientific computing" (PLoS Comput. Biol. 2017).
10 Checklist before you trust a new sequence
- Look at it. Put the key TTLs and analog lines on a four-channel scope, triggered by the start of the shot, and compare with what you meant.
- Measure the delays of every shutter, AOM and coil with a photodiode or pick-up coil, and compensate them in one place in the code.
- Check the slack or the compile output. Underflows, collisions and "instruction too short" warnings are bugs, not noise.
- Make it safe when it stops. If a sequence crashes, lasers, coils and RF should end in a safe state; coils must not stay at full current.
- Record everything: parameters, code hash, slow-instrument settings and environmental logs, per shot.
- Change one thing at a time and keep a short lab-notebook line for each change; your future self is the main reader.