AutoSQUID 0.1.3__py3-none-any.whl

AutoSQUID/__init__.py

@@ -0,0 +1,47 @@
+"""AutoSQUID — shared library for the SQUID measurement-cycle + auto-S-tune notebooks.
+
+Edit values in the notebook (build a Config); call these functions with that cfg. Modules:
+  util        generic helpers (clamp)
+  config      Config dataclass (all knobs + derived paths/register)
+  scc         pure SCC framing (assemble_command, pfl_register, dac_data)
+  analysis    pure detection + I/O (surge/jump, temp label, PCS102 read/write, ledger, resume)
+  serial_io   SCC writes (reset, s_lock/s_tune, set_* DACs)        [pyserial]
+  daq         NI reads + channel detect + chunked acquisition       [nidaqmx]
+  temperature MXC read via the injected `cfg.temp_reader` + background logger   [no instrument import]
+  measurement run_cycle state machine (the interval loop lives in the notebook)
+  tuning      auto_s_tune (live-center the locked output near 0 by stepping S-flux; secant search)
+  plotting    plot_run / plot_psd (raw trace + temperature; one-sided Welch PSD, read from disk) [matplotlib/pandas]
+
+The DAQ + serial backends (`nidaqmx`, `pyserial`) are imported at module top (the package assumes the
+STAR Cryo + NI rig), so `import AutoSQUID` needs those two. The MXC thermometer backend is **not** imported —
+set `cfg.temp_reader` (a `fn(channel)->T in K`) in the notebook, so the temperature source is lab-swappable.
+The pure modules (`scc`, `analysis`, `config`) have no hardware deps and import anywhere for unit tests.
+"""
+__version__ = "0.1.3"
+
+from .config import Config
+from .util import clamp
+from .scc import assemble_command, pfl_register, dac_data
+from .analysis import (is_surge_spec, chunk_jump, format_temp_label,
+                       save_pcs102, save_temp_csv, read_daq_file,
+                       log_experiment, log_action, scan_indices, LEDGER_COLS)
+from .serial_io import (reset, fire_reset, s_lock, s_tune,
+                        set_squid_flux, set_array_flux, set_squid_bias, set_array_bias)
+from .daq import daq_read, daq_mean, live_mean, classify, detect_ai_channel, acquire_finite_chunked
+from .temperature import read_temp, TempLogger
+from .measurement import run_cycle, reset_and_verify, resolve_temp_label
+from .tuning import auto_s_tune
+from .plotting import plot_run, clean_trace_names, plot_overlay, plot_psd
+
+__all__ = [
+    "__version__",
+    "Config",
+    "assemble_command", "pfl_register", "dac_data", "clamp",
+    "is_surge_spec", "chunk_jump", "format_temp_label",
+    "save_pcs102", "save_temp_csv", "read_daq_file", "log_experiment", "log_action", "scan_indices", "LEDGER_COLS",
+    "reset", "fire_reset", "s_lock", "s_tune", "set_squid_flux", "set_array_flux", "set_squid_bias", "set_array_bias",
+    "daq_read", "daq_mean", "live_mean", "classify", "detect_ai_channel", "acquire_finite_chunked",
+    "read_temp", "TempLogger",
+    "run_cycle", "reset_and_verify", "resolve_temp_label",
+    "auto_s_tune", "plot_run", "clean_trace_names", "plot_overlay", "plot_psd",
+]

AutoSQUID/analysis.py

@@ -0,0 +1,153 @@
+"""Pure analysis + I/O for SQUID traces: surge/jump detection, temperature labels, PCS102 read/write,
+the experiment ledger + action log, and resume bookkeeping.
+
+No instrument hardware — numpy + pandas + stdlib only (the detection/label functions need only numpy).
+"""
+import os
+import re
+import datetime
+import numpy as np
+import pandas as pd
+
+
+def is_surge_spec(v,
+                  win=2000,
+                  n_baseline_chunks=1, jump_sigma=6.0, rail_v=9.5, first_chunk_v=0.1,
+                  min_std=5e-5, stuck_frac=0.1, stuck_max_frac=0.02):
+    """Post-hoc surge detector: rail catch, already-surged first-chunk pre-check, a stuck/flat catch (a
+    healthy noise trace fluctuates; a frozen one's per-chunk std collapses), and baseline-deviation
+    |mu_chunk - mu0|/sigma0 > jump_sigma. Returns (bad, reason)."""
+    v = np.asarray(v, dtype=float)
+    if np.max(np.abs(v)) > rail_v:
+        return True, f"railed (|V|max={np.max(np.abs(v)):.2f} > {rail_v})"
+    nc = max(len(v) // win, 1)
+    chunks = np.array_split(v, nc)
+    mu = np.array([c.mean() for c in chunks])
+    sd = np.array([c.std() for c in chunks])
+    if abs(mu[0]) > first_chunk_v:
+        return True, f"first-chunk mean {mu[0]:+.3f} V > {first_chunk_v} V (already surged?)"
+    live = float(sd.max())                                  # liveliest chunk's std = the trace's noise level
+    if live < min_std:                                      # no chunk shows real noise -> flat/dead throughout
+        return True, f"flat/dead trace (max chunk std {live:.2e} V < {min_std})"
+    stuck = sd < stuck_frac * live                          # chunks whose noise collapsed vs the live level
+    if stuck.mean() > stuck_max_frac:                       # frozen/stuck over more than stuck_max_frac of the run
+        return True, f"stuck/frozen: {100 * stuck.mean():.0f}% of chunks have std < {stuck_frac:g}x the live level"
+    k = min(n_baseline_chunks, nc)
+    mu0 = mu[:k].mean()
+    sigma0 = max(sd[:k].mean(), 1e-7)
+    dev = np.abs(mu - mu0) / sigma0
+    if dev.max() > jump_sigma:
+        return True, f"baseline deviation {dev.max():.1f} sigma0 at chunk {int(dev.argmax())}/{nc}"
+    return False, "ok"
+
+
+def chunk_jump(seg_mean, seg_absmax, mu0, jump_v=1.0, rail_v=9.5, baseline_v=0.1):
+    """Per-chunk live check; returns (kind, reason) or None. In the baseline window (mu0 is None) any
+    excursion is 'bad_baseline' (reset didn't hold); afterward it's 'rail' or 'jump'."""
+    if mu0 is None:
+        if seg_absmax > rail_v:
+            return ("bad_baseline", f"railed at start (|V|max={seg_absmax:.2f}); reset did not hold")
+        if abs(seg_mean) > baseline_v:
+            return ("bad_baseline", f"high baseline {seg_mean:+.3f} V (>{baseline_v} V); reset did not hold")
+        return None
+    if seg_absmax > rail_v:
+        return ("rail", f"railed (|V|max={seg_absmax:.2f} > {rail_v})")
+    if abs(seg_mean - mu0) > jump_v:
+        return ("jump", f"{jump_v:g} V jump (|d-mu|={abs(seg_mean - mu0):.3f} V)")
+    return None
+
+
+def format_temp_label(T_K):
+    """Filename label: <100 mK -> nearest 1 mK; 100 mK-1 K -> nearest 10 mK; >=1 K -> nearest 0.1 K ('p' decimal)."""
+    mK = T_K * 1000.0
+    if T_K < 1.0:
+        step = 1 if mK < 100 else 10
+        return f"{int(round(mK / step)) * step}mK"
+    s = f"{round(T_K, 1):.1f}".rstrip('0').rstrip('.')
+    return s.replace('.', 'p') + "K"
+
+
+def save_pcs102(path, v, scan_interval_s, channels=1):
+    """Write a 1-D voltage array to PCS102 DAQ .txt format (tab-separated, 1-based POINT index; matches data/)."""
+    n = len(v); now = datetime.datetime.now()
+    header = ("PCS102\n"
+              f"DATE={now:%m-%d-%Y}\n"
+              f"TIME={now:%H:%M:%S}\n"
+              f"CHANNELS={channels}\n"
+              f"DATAPOINTS={n}\n"
+              f"SCANINTVAL={scan_interval_s:.2e}\n"
+              + " " * 9 + "\n" + "TEXT:  \n" + " " * 9 + "\n"
+              + " " * 3 + "POINT" + " " * 9 + "CHAN_01(V)" + " " * 6 + "\n" + " " * 3 + "\n")
+    with open(path, "w") as f:
+        f.write(header)
+        np.savetxt(f, np.column_stack([np.arange(1, n + 1), v]), fmt="%8d\t % .6f\t")
+
+
+def save_temp_csv(path, samples):
+    """Write the temperature log (list of (t_rel_s, T_K)) to a 2-column CSV."""
+    with open(path, "w") as f:
+        f.write("time_s,T_K\n")
+        for t_rel, T in samples:
+            f.write(f"{t_rel:.3f},{T:.6f}\n")
+
+
+def read_daq_file(path, filename):
+    """Read a PCS102 DAQ .txt into (header_info, df) — from data-analysis/Calculations during measurement."""
+    truepath = os.path.join(path, filename)
+    with open(truepath, 'r') as file:
+        lines = file.readlines()
+    header_info = {}
+    for line in lines[:6]:
+        if '=' in line:
+            key, value = line.strip().split('=')
+            if key in ("DATE", "TIME"):           header_info[key] = value
+            elif key in ("CHANNELS", "DATAPOINTS"): header_info[key] = int(value)
+            elif key == "SCANINTVAL":             header_info[key] = float(value)
+            else:                                 header_info[key] = value
+        else:
+            header_info[line.strip()] = None
+    text_index = next(i for i, line in enumerate(lines) if "TEXT:" in line)
+    column_names = lines[text_index + 2].strip().split()
+    df = pd.read_csv(truepath, sep=r'\s+', skiprows=text_index + 3, header=None, names=column_names)
+    df.set_index("POINT", inplace=True)
+    return header_info, df
+
+
+LEDGER_COLS = ["timestamp", "scan_interval_us", "n_target", "n_acquired", "n_clean", "attempt",
+               "outcome", "jump_index", "jump_time_s", "n_resets", "mean_V", "std_V",
+               "T_start_K", "T_end_K", "filename"]
+
+
+def log_experiment(path, row):
+    """Append one attempt as a tab-separated row to the experiment ledger (writes header if new)."""
+    new = not os.path.exists(path)
+    with open(path, "a") as f:
+        if new:
+            f.write("\t".join(LEDGER_COLS) + "\n")
+        f.write("\t".join(str(row.get(c, "")) for c in LEDGER_COLS) + "\n")
+
+
+def log_action(path, action, detail=""):
+    "Append a timestamped action line (reset / reset_fail / bad_baseline / temperature / measurement attempt) to the action log — actions + attempted names only, NEVER measurement results."
+    new = not os.path.exists(path)
+    with open(path, "a") as f:
+        if new:
+            f.write("timestamp\taction\tdetail\n")
+        f.write(f"{datetime.datetime.now().isoformat(timespec='seconds')}\t{action}\t{detail}\n")
+
+
+def scan_indices(outdir, core):
+    """Scan DAQ_[<date>_]{core}_{k}[_OUTCOME].txt on disk for this (interval,temp,npts) `core`, IGNORING the
+    date token, so traces measured on any day in the folder all count; return (n_clean, next_idx): clean-trace
+    count and the next free order index (max existing index + 1, over clean AND failed) so a resume never
+    overwrites and the index stays continuous regardless of the day measured."""
+    n_clean = 0; max_idx = 0
+    pat = re.compile(rf"DAQ_(?:[^_]+_)?{re.escape(core)}_(\d+)(_[A-Z]+)?\.txt")   # optional date token, any day
+    for p in outdir.glob("DAQ_*.txt"):
+        m = pat.fullmatch(p.name)
+        if not m:
+            continue
+        max_idx = max(max_idx, int(m.group(1)))
+        if m.group(2) is None:
+            n_clean += 1
+    return n_clean, max_idx + 1

AutoSQUID/config.py

@@ -0,0 +1,99 @@
+"""Config: every knob for the SQUID measurement-cycle / auto-S-tune stack, in one dataclass.
+
+The notebook constructs a Config (that is where you EDIT values); the library functions all take it as
+their first argument. Derived values (scan-interval list, filename tag, output dir, PFL register) are
+computed properties, so there is no stale state to keep in sync.
+"""
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, List, Optional, Union
+from datetime import datetime
+import os
+
+from .scc import pfl_register
+
+
+@dataclass
+class Config:
+    # ---- acquisition ----
+    scan_interval_s: Union[float, List[float]] = field(default_factory=lambda: [100e-6])  # one cycle per entry
+    n_points: int = 10_000_000          # length of the consecutive run
+    temp_label: str = "auto"            # "auto" -> read+round the current MXC temperature; or a literal e.g. "14mK"
+    n_trials: int = 2                   # target number of CLEAN traces per scan interval
+
+    # ---- live jump check ----
+    chunk: int = 100_000                # points per read = jump-check cadence (does NOT break the consecutive run)
+    jump_v: float = 0.5                 # flag a baseline-mean slip >= this (V)
+    rail_v: float = 9.5                 # true-rail catch (V); range-agnostic
+    baseline_chunks: int = 1            # first chunk(s) set the baseline mean mu0
+
+    # ---- temperature logging ----
+    temp_every_s: float = 30.0          # MXC sample period (background thread)
+    temp_channel: int = 6               # thermometer channel passed to temp_reader
+    temp_reader: Optional[Callable[[int], float]] = None   # LAB-SPECIFIC: set in the notebook to fn(channel)->T in K
+                                        # (e.g. cfg.temp_reader = lambda ch: read_latest_temp(ch)[1]); NOT imported by the package
+
+    # ---- control (SCC serial) ----
+    port: str = "COM3"                  # control COM port (PCS102DA may stay open on another port to hold S-lock)
+    channel: int = 1                    # SCC address = locked PFL channel
+    reset_opcode: int = 0x50
+    baud: int = 9600
+    register_override: Optional[int] = None   # None -> standard SQUID-locked register (0x408)
+
+    # ---- verify / DAQ / output ----
+    verify_n: int = 1000                # post-reset verify read
+    verify_fs: int = 10_000
+    scan_n: int = 4000                  # per-channel liveliness probe
+    scan_fs: int = 50_000
+    baseline_v: float = 0.10            # |mean| below this = cleared / locked baseline
+    vrange: float = 1.0                 # NI AI range (V); +/-1 V matches the previous measurements
+    max_attempts: int = 4               # max total acquisitions per interval (clean + failed) before moving on
+    force_device: Optional[str] = None  # e.g. 'Dev1' to skip device auto-pick
+    force_ai: Optional[str] = None      # e.g. 'Dev1/ai0' to skip channel auto-pick
+    daq_ai: str = ""            # NI analog-in carrying the SQUID output (set by detect_ai_channel)
+    data_root: str = ""   # data root; outdir = data_root / user / date (set per install)
+    user: str = ""               # data folder owner
+    date: str = ""                      # date subfolder ("" = the USER folder itself)
+
+    # ---- derived ----
+    @property
+    def scan_intervals(self) -> List[float]:
+        "Scan interval(s) normalized to a list (accepts a scalar)."
+        s = self.scan_interval_s
+        return [s] if isinstance(s, (int, float)) else list(s)
+
+    @property
+    def npts_tag(self) -> str:
+        "Filename point-count tag, e.g. 10_000_000 -> '10Mpts'."
+        n = self.n_points
+        return f"{n // 1_000_000}Mpts" if n % 1_000_000 == 0 else f"{n}pts"
+
+    @property
+    def base_path(self) -> str:
+        "Per-user data folder: data_root / user."
+        return os.path.join(self.data_root, self.user)
+
+    @property
+    def outdir(self) -> Path:
+        "Folder where traces, temp CSVs, and the ledger are written/read (base_path + date)."
+        return Path(os.path.join(self.base_path, self.date))
+
+    @property
+    def register(self) -> int:
+        "The PFL feedback register to use (override, else standard SQUID-locked 0x408)."
+        return self.register_override if self.register_override is not None else pfl_register(stage1_locked=True)
+
+    def core_name(self, scan_interval_s: float) -> str:
+        "Date-agnostic identifying core, e.g. '100us_14mK_10Mpts' — matches this (interval, temp, npts) trace on ANY date."
+        return f"{int(round(scan_interval_s * 1e6))}us_{self.temp_label}_{self.npts_tag}"
+
+    def base_name(self, scan_interval_s: float) -> str:
+        "WRITE stem for a new trace, e.g. 'DAQ_Jun01_100us_14mK_10Mpts' (date prefix + core; order index/outcome appended later). Existing traces are MATCHED by core_name, which ignores the date."
+        return f"DAQ_{datetime.now().strftime('%b%d')}_{self.core_name(scan_interval_s)}"
+
+
+def require_fields(cfg, names, context):
+    "Raise if any of `names` is unset (None or '') on cfg — call at the top of a function that needs them."
+    missing = [n for n in names if getattr(cfg, n) is None or getattr(cfg, n) == ""]
+    if missing:
+        raise RuntimeError(f"{context}: set cfg.{', cfg.'.join(missing)} before running")

AutoSQUID/daq.py

@@ -0,0 +1,110 @@
+"""NI DAQ reads: finite reads, channel auto-detect, and the consecutive chunked acquisition with the
+live jump/surge check. Hardware: nidaqmx. Every read is a FINITE task (start -> read N -> close); the
+chunked acquisition drains one finite N-sample task gap-free (so chunking never breaks the run).
+"""
+import warnings
+
+import numpy as np
+import nidaqmx
+from nidaqmx.constants import AcquisitionType, TerminalConfiguration
+from nidaqmx.stream_readers import AnalogSingleChannelReader
+
+from .analysis import chunk_jump
+
+
+def daq_task(cfg, channel, fs, n):
+    "Create + configure a FINITE single-channel AI task on `channel` at fs Hz for n samples (caller closes)."
+    t = nidaqmx.Task()
+    t.ai_channels.add_ai_voltage_chan(channel, min_val=-cfg.vrange, max_val=cfg.vrange,
+                                      terminal_config=TerminalConfiguration.RSE)
+    t.timing.cfg_samp_clk_timing(fs, sample_mode=AcquisitionType.FINITE, samps_per_chan=n)
+    return t
+
+
+def daq_read(cfg, channel, n, fs):
+    "Finite read of n samples at fs Hz from one AI channel; returns a 1-D array (V)."
+    with daq_task(cfg, channel, fs, n) as t:
+        return np.asarray(t.read(number_of_samples_per_channel=n, timeout=n / fs + 5.0))
+
+
+def daq_mean(cfg, channel=None, n=2000, fs=10_000):
+    "Mean voltage of a short read of the locked SQUID output (V) — the auto-S-tune DC read."
+    return float(np.mean(daq_read(cfg, channel or cfg.daq_ai, n, fs)))
+
+
+def live_mean(cfg, channel=None, seconds=1.0, fs=10_000):
+    """A short 'live view' of the locked output (what the eye watches while centering): one finite read of
+    `seconds`, returned as dict(mean, std, min, max)."""
+    v = daq_read(cfg, channel or cfg.daq_ai, int(round(seconds * fs)), fs)
+    return {"mean": float(v.mean()), "std": float(v.std()),
+            "min": float(v.min()), "max": float(v.max())}
+
+
+def classify(v):
+    "Label an AI-channel probe as live / dead-flat / railed."
+    mx, sd, mu = np.max(np.abs(v)), v.std(), v.mean()
+    if mx > 9.9 or abs(mu) > 9.5: return "RAILED"
+    if sd < 5e-5:                 return "dead/flat"
+    return "live"
+
+
+def detect_ai_channel(cfg):
+    "List NI devices, pick the PCIe-6320, probe each AI channel, and return (device_name, daq_ai). Honors cfg.force_*."
+    sysl = nidaqmx.system.System.local()
+    devices = list(sysl.devices)
+    assert devices, "No NI-DAQmx devices found. Is the PCIe-6320 installed and is this the bench PC?"
+    dev = (sysl.devices[cfg.force_device] if cfg.force_device
+           else next((d for d in devices if "6320" in (d.product_type or "")), devices[0]))
+    chans = [c.name for c in dev.ai_physical_chans]
+    if cfg.force_ai:
+        return dev, cfg.force_ai
+    live = []
+    for ch in chans:
+        try:
+            if classify(daq_read(cfg, ch, cfg.scan_n, cfg.scan_fs)) == "live":
+                live.append(ch)
+        except Exception:
+            pass
+    if not live:
+        raise RuntimeError(f"no live AI channel on {dev.name} (probed {len(chans)}): check the SQUID lock / "
+                           "wiring, or pin the channel with cfg.force_ai.")
+    daq_ai = next((ch for ch in live if ch.endswith("ai0")), live[0])
+    return dev, daq_ai
+
+
+def acquire_finite_chunked(cfg, channel, n, fs):
+    """ONE consecutive FINITE read of n samples, drained in cfg.chunk-point reads with the live chunk_jump
+    check (the sample clock is gap-free, so chunking does NOT break the run). Returns
+    (v[:got], got, flag|None) where flag=dict(kind,index,time_s,reason), kind in {jump,rail,bad_baseline}."""
+
+    # The FIFO buffer only holds a few thousand samples, so read_many_sample is not going to interrupt the run.
+    # Check out the following on buffers:
+    # https://knowledge.ni.com/KnowledgeArticleDetails?id=kA00Z000000PAraSAG&l=en-US
+    # https://www.ni.com/docs/en-US/bundle/pcie-6320-specs/resource/374459d.pdf
+
+    buf = np.empty(n, dtype=np.float64)
+    got = 0; mu0 = None; base = []
+    with daq_task(cfg, channel, fs, n) as t:
+        reader = AnalogSingleChannelReader(t.in_stream)
+        t.start()
+        while got < n:
+            m = min(cfg.chunk, n - got)
+            reader.read_many_sample(buf[got:got + m], number_of_samples_per_channel=m, timeout=m / fs + 10.0)
+            seg = buf[got:got + m]
+            res = chunk_jump(float(seg.mean()), float(np.max(np.abs(seg))), mu0, cfg.jump_v, cfg.rail_v, cfg.baseline_v)
+            if mu0 is None:
+                base.append(float(seg.mean()))
+                if len(base) >= cfg.baseline_chunks:
+                    mu0 = float(np.mean(base))
+            got += m
+            if res:
+                kind, reason = res
+                with warnings.catch_warnings():
+                    warnings.filterwarnings("ignore", message=".*200010.*")
+                    t.stop()
+                return buf[:got].copy(), got, {
+                    "kind": kind,
+                    "index": got,
+                    "time_s": got / fs,
+                    "reason": reason}
+    return buf[:got].copy(), got, None

AutoSQUID/measurement.py

@@ -0,0 +1,139 @@
+"""The measurement-cycle state machine: run_cycle (one scan interval). The interval loop lives in the
+notebook (§2); resolve_temp_label sets the auto temperature label before the loop runs.
+
+Collects cfg.n_trials CLEAN traces per interval within cfg.max_attempts real acquisitions; each acquisition
+is order-indexed (clean -> {base}_{i}.txt, failed -> {base}_{i}_{JUMP|SURGE|RAIL|BADBASE}.txt); resumes from
+existing files (never overwrites); a bad-baseline / non-clearing reset is systemic and stops the sweep.
+"""
+import time
+import datetime
+import serial
+
+from .analysis import (is_surge_spec, save_pcs102, save_temp_csv, log_experiment, log_action,
+                        scan_indices, format_temp_label)
+from .config import require_fields
+from .serial_io import fire_reset
+from .daq import acquire_finite_chunked, daq_read
+from .temperature import TempLogger, read_temp
+
+
+def reset_and_verify(cfg, tries=5, settle_s=0.3):
+    "Fire reset + verify the locked baseline up to `tries` times; True once |mean| < cfg.baseline_v."
+    with serial.Serial(cfg.port, cfg.baud, bytesize=8, parity="N", stopbits=1, timeout=1) as ser:
+        for k in range(1, tries + 1):
+            fire_reset(ser, cfg)
+            time.sleep(settle_s)
+            m = daq_read(cfg, cfg.daq_ai, cfg.verify_n, cfg.verify_fs).mean()
+            cleared = abs(m) < cfg.baseline_v
+            print(f"    Reset try {k}: mean={m:+.4f} V -> {'CLEARED' if cleared else 'still off-zero'}")
+            if cleared:
+                return True
+    return False
+
+def resolve_temp_label(cfg):
+    "If cfg.temp_label == 'auto', read + validate the MXC temperature and set the rounded label on cfg."
+    if cfg.temp_label == "auto":
+        T = read_temp(cfg)
+        if T is None or not (0 < T < 1000):
+            raise RuntimeError(f"bad MXC temperature read: {T} (logger down / wrong channel?)")
+        cfg.temp_label = format_temp_label(T)
+    return cfg.temp_label
+
+def run_cycle(cfg, scan_interval_s):
+    """One scan interval: collect cfg.n_trials CLEAN traces within cfg.max_attempts real acquisitions.
+    Returns 'reset_fail' (a non-clearing/bad-baseline reset -> stop the sweep) or 'ok'."""
+    require_fields(cfg, ["data_root", "user"], "run_cycle")
+    if cfg.temp_label == "auto":
+        require_fields(cfg, ["temp_reader"], "run_cycle with temp_label='auto'")
+    require_fields(cfg, ["daq_ai"], "run_cycle")
+    fs = 1.0 / scan_interval_s
+    tau_us = int(round(scan_interval_s * 1e6))
+    base = cfg.base_name(scan_interval_s)            # WRITE stem (carries today's date)
+    core = cfg.core_name(scan_interval_s)            # date-agnostic core for matching existing traces
+    cfg.outdir.mkdir(parents=True, exist_ok=True)    # ensure the output folder exists before any reset/write
+    ledger = cfg.outdir / "experiment_log.txt"
+    actionlog = cfg.outdir / "action_log.txt"
+    est = cfg.n_points * scan_interval_s
+    n_resets = 0
+
+    def _log(outcome, **kw):
+        "Append a ledger row, filling the per-interval constants; caller passes the varying fields."
+        log_experiment(ledger, dict(timestamp=datetime.datetime.now().isoformat(timespec="seconds"),
+                       scan_interval_us=tau_us, n_target=cfg.n_points, n_resets=n_resets, outcome=outcome, **kw))
+
+    def _action(action, detail=""):
+        "Append a line to the action log (actions + attempted names; never measurement results)."
+        log_action(actionlog, action, detail)
+
+    def _reset(tag, n_clean):
+        "reset_and_verify (counts toward n_resets); log RESET/RESET_FAIL with the upcoming index. Returns ok."
+        nonlocal n_resets
+        ok = reset_and_verify(cfg); n_resets += 1
+        _action("RESET" if ok else "RESET_FAIL", f"attempt {tag}")
+        if not ok:
+            _log("RESET_FAIL", n_clean=n_clean, attempt=tag, filename="")
+        return ok
+
+    n_clean, i = scan_indices(cfg.outdir, core)      # count + next index over ALL dates of this core
+    if n_clean >= cfg.n_trials:
+        print(f"\n=== {base} · already has {n_clean}/{cfg.n_trials} clean; skipping ==="); return "ok"
+    if n_clean or i > 1:
+        print(f"\n=== {base} · resuming: {n_clean}/{cfg.n_trials} clean on disk; next index {i} ===")
+    if not _reset(i, n_clean):
+        print("    Reset did not clear (systemic); STOPPING."); return "reset_fail"
+
+    n_attempts = 0
+    while n_clean < cfg.n_trials and n_attempts < cfg.max_attempts:
+        print(f"\n=== {base} · index {i} · {n_attempts}/{cfg.max_attempts} used · {n_clean}/{cfg.n_trials} clean · "
+              f"{cfg.n_points} pts @ {fs:.0f} Hz (~{est:.0f} s) ===")
+        _t0 = datetime.datetime.now()
+        print(f"    start {_t0:%H:%M:%S} · expected done ~{_t0 + datetime.timedelta(seconds=est):%H:%M:%S}  (~{est:.0f} s)")
+        try:
+            T_now = read_temp(cfg)                             # MXC temperature just before this attempt
+            _action("TEMP", f"{T_now:.4f} K" if T_now is not None else "read failed (None)")
+        except Exception as e:
+            _action("TEMP", f"read failed ({e})")
+        _action("MEASURE", f"{base}_{i}")                     # attempted name + index (no result)
+        tl = TempLogger(cfg); tl.start(); t0 = time.time()
+        try:
+            v, got, flag = acquire_finite_chunked(cfg, cfg.daq_ai, cfg.n_points, fs)
+        finally:
+            tl.stop(); tl.join(timeout=cfg.temp_every_s + 5)
+
+        kind = flag["kind"] if flag else None        # classify -> (outcome, file tag, reason); tag is ONE token
+        if   kind == "bad_baseline": outcome, tag, reason = "BAD_BASELINE", "BADBASE", flag["reason"]
+        elif kind == "rail":         outcome, tag, reason = "RAIL", "RAIL", flag["reason"]
+        elif kind == "jump":         outcome, tag, reason = "JUMP", "JUMP", flag["reason"]
+        else:
+            surged, sreason = is_surge_spec(v, rail_v=cfg.rail_v, first_chunk_v=cfg.baseline_v)
+            outcome, tag, reason = ("SURGE", "SURGE", sreason) if surged else ("CLEAN", "", "ok")
+
+        if outcome != "BAD_BASELINE": n_attempts += 1
+        if outcome == "CLEAN":        n_clean += 1
+        stem = f"{base}_{i}" + (f"_{tag}" if tag else "")
+        save_pcs102(cfg.outdir / f"{stem}.txt", v, scan_interval_s)
+        save_temp_csv(cfg.outdir / (stem.replace("DAQ", "TEMP", 1) + ".csv"), tl.samples)   # TEMP_<core>_<i>.csv
+        Ts = [s[1] for s in tl.samples] or [float("nan")]
+        _log(outcome, n_acquired=got, n_clean=n_clean, attempt=i, filename=f"{stem}.txt",
+             jump_index=flag["index"] if flag else -1, jump_time_s=f"{flag['time_s']:.3f}" if flag else "",
+             mean_V=f"{v.mean():.6f}", std_V=f"{v.std():.6f}", T_start_K=f"{Ts[0]:.6f}", T_end_K=f"{Ts[-1]:.6f}")
+        print(f"    {outcome} ({reason}) · idx {i} · N={got} · {time.time()-t0:.0f}s · "
+              f"mean={v.mean():+.4f} std={v.std():.4f} V · T {Ts[0]:.4f}->{Ts[-1]:.4f} K · {n_clean}/{cfg.n_trials} clean")
+        i += 1
+
+        if outcome == "BAD_BASELINE":
+            _action("BAD_BASELINE", reason)
+            print("    Bad baseline -> reset is not holding (systemic); STOPPING."); return "reset_fail"
+        if outcome == "CLEAN":
+            continue
+        if n_clean < cfg.n_trials and n_attempts < cfg.max_attempts and not _reset(i, n_clean):
+            print("    Reset did not clear (systemic); STOPPING."); return "reset_fail"
+
+    if n_clean >= cfg.n_trials:
+        print(f"    DONE: {n_clean}/{cfg.n_trials} clean traces in {n_attempts} acquisition(s) this run.")
+    else:
+        _log("BUDGET_EXHAUSTED", n_clean=n_clean, attempt="", jump_index=-1, jump_time_s="", filename="")
+        print(f"    BUDGET EXHAUSTED: {n_clean}/{cfg.n_trials} clean after {cfg.max_attempts} acquisitions; moving on.")
+    return "ok"
+
+