Skip to content

HW Verify Issue 68 Operations Refactor Tune

Jump to bottom
Benjamin Reese edited this page Aug 14, 2026 · 2 revisions

HW Verify — Issue #68 / PR #78: Operations refactor — analog-bench tune

Item: Issue #68 (Refactor Jupyter notebook utilities into warm_tdm_api.operations), delivered by PR #78 (supersedes PR #61). Board status: In Progress; the one internal gate before merge is analog-bench validation — a real tune on SQUIDs through the new API. Track: Software · Priority: P0.

← back to Hardware Verification

What we are verifying

PR #78 reshapes the notebook utilities into a documented operations package: the old global Client singleton is replaced by a per-Group Session; tuning, setup, acquisition, and analysis are methods on it; several helpers graduated onto Group. It is thoroughly validated in emulate, but emulate cannot run the servo or clock the DAC FSM against live timing. The remaining gate is a full-stack run on real hardware: connect → setup → tune (SA offset → SA tune → SQ1 tune) → take data → analyze → safe-state, all through the new API, and confirm it produces a converging tune and correct data — i.e. no regression vs. the old notebook workflow.

This is the end-to-end regression test for the whole refactor. Several of the other Bucket-A items (dead masks #60, stop_and_zero #86, cable resistance, PS-sync, LED toggle) are exercised incidentally here; this page is the "does the new operator arc work on hardware at all" check.

You will need

  • A cryostat with live SQUIDs (a real, tunable front-end) — this is the one item that genuinely needs SQUIDs, not just a load board.
  • The wtj-refactor branch (PR #78's head).
  • The worked template software/jupyter/operations_template.py open alongside — it is the canonical version of this workflow.

Procedure

Follow the operator arc. Each step below mirrors operations_template.py.

0. Connect

import warm_tdm_api.operations as ops
sess  = ops.connect(host="localhost", port=9099)
r     = sess.root
group = sess.group
ops.status()             # sanity: board counts, run mode, tune-enabled cols
ops.print_hardware()     # RECORD build stamps + git hashes

A. Enabled set (anchor)

group.ColTuneEnable.set([True] * 8)          # your active columns
group.RowMap1x32()                           # row map for your array
group.RowIndexOrderList.set([0, 1, 2, 3])    # logical rows to read out

Optional analog setup for your cryostat:

ops.set_cryo_resistance(Rcryo_Ohm=250.0)
ops.set_ps_synch(1)                          # then ops.check_ps_synch()

B. Tune point

import numpy as np
ncol = len(group.ColTuneEnable.get())
group.Sq1FbForceCurrent.set([0.0] * ncol)
group.Sq1BiasForceCurrent.set([0.0] * ncol)
group.SaFbForceCurrent.set([0.0] * ncol)

ops.sa_offset()                                          # null SA bias offset
sa_out  = ops.sa_tune(SaBiasLowOffset=0.0, SaBiasHighOffset=1.0, SaBiasNumSteps=5)
# (set row-select FAS currents for your array here)
sq1_out = ops.sq1_tune(Sq1BiasNumSteps=20, ServoPrecision=0.0015)

Confirm each stage converges — the process finishes (not timeout) and the SA/SQ1 V/φ curves look physical. This is the core pass condition.

C. Run settings + acquire

ops.setup_mux(num_pts=512, sample_end_offset=100, sample_num=250, enable_pid=True)
data_file = ops.take_data(acq_time_sec=10.0)
print("wrote", data_file)

Analyze

res = ops.plot_stream_data("c*r*", stream_data_id=data_file)
# ops.analyze_pair("c0r0", "c0r1", stream_data_id=data_file, do_fit=True)

Confirm the readout stream decodes, the sample rate + SQ1FB→pA calibration come from the file's embedded config (not hardcoded), and the noise/ASD looks sane.

Safe state

ops.stop_and_zero()

Pass criteria

  • connect / status / print_hardware work against the live tree.
  • SA offset, SA tune, and SQ1 tune each converge on real SQUIDs (no timeout; curves physical) — comparable to the prior notebook workflow.
  • setup_mux + take_data produce a valid .dat; plot_stream_data decodes it with config-derived calibration.
  • stop_and_zero returns the system to a safe state (ties in with Issue #86).
  • No regression vs. the old workflow for the same array/config.

Record

  • Firmware build stamps + git hashes, software commit (wtj-refactor), conda env:
  • Cryostat / array under test:
  • Convergence result per tune stage (+ representative curves):
  • Data file + analysis plots:
  • Overall: ready to merge PR #78? (yes/no + notes)

References

  • Issue #68; PR #78 (validation section lists exactly what emulate covered vs. what needs the bench)
  • software/jupyter/operations_template.py — the canonical worked workflow
  • docs/design/muxed-run-bringup.md — the A/B/C configuration-layer model
  • software/python/warm_tdm_api/operations/ — session.py, analysis.py, channels.py

Clone this wiki locally