Frequency and pulse scan API
Import from nmrlink. Use NMRController.sweep / pulseSweep for hardware operations; independent synchronous functions reanalyze saved records.
On this page
frequencySteps and pulseSteps
frequencySteps(startHz, endHz, stepHz) and pulseSteps(startCycles, endCycles, stepCycles) return ascending integer grids. Start must not exceed end; step must be positive; at most 201 points. Frequencies range from 1 to 2147483647 Hz; cycles from 1 to 32767. The grid never exceeds end or appends an off-grid endpoint. Invalid plans throw RangeError.
controller.sweep and controller.pulseSweep
| Operation | Required options | Changed field / extra result |
|---|---|---|
| sweep(parameters, options) | startHz, endHz, stepHz | frequencyHz / frequencies |
| pulseSweep(parameters, options) | startCycles, endCycles, stepCycles | pulse1Cycles / lengths |
Shared options are analysis=, signal (AbortSignal), and onPoint(point, completed, total). Scans run Single measurements sequentially and reject other connection, disconnection or measurement operations for the entire scan. All planned settings and analysis options are checked before the first command.
const abort = new AbortController();
const completedPoints = [];
const outcome = await controller.sweep(parameters, {
startHz: 398000, endHz: 406000, stepHz: 1000,
analysis: { startMs: 1, endMs: 5, minHz: -3000, maxHz: 3000 },
signal: abort.signal,
onPoint: point => { completedPoints.push(point); },
});
// A separate stop button calls abort.abort(); the current measurement completes first.On success, value contains points, stopped, analysis, parameters and frequencies / lengths. Cancellation returns completed points. Communication, analysis or onPoint failure interrupts the scan with ok:false. Retain already notified points in the UI. onResult is not called for scans.
Low-level runFrequencySweep(device, parameters, options) / runPulseSweep(...) return the same value directly through a promise and reject on failure. The caller manages device-wide exclusivity.
evaluateFrequency and evaluatePulse
evaluateFrequency(record, analysis=) returns frequencyHz, amplitude, peakHz and record; evaluatePulse returns length, amplitude, peakHz and record. At this stage amplitude is a nonnegative FFT peak.
Analysis defaults: startMs=1, endMs=5, tailPoints=100, window=hann, minHz=-3000, maxHz=3000. Both peak-band endpoints are included. An invalid band or a band containing no FFT bins throws.
analyzePulseCalibration(records, options)
records is an array of measurement records. Defaults: analysis=, referenceIndex=null (automatic), phaseDegrees=0. Keep source, Single mode, sample interval and all settings except first-pulse length identical. An integer referenceIndex selects the phase-reference record; phaseDegrees adds a common correction to every point.
| Result | Contents |
|---|---|
| points | length, signed amplitude, quadrature, magnitude, record |
| reference | hz, phaseRad, phaseDegrees, referenceIndex, coherence |
| measured | Candidates from the measured peak and zero crossing, or null |
| fit / magnitudeFit | Signed / magnitude sine fit, or null if not computable |
| warnings | Array of phase, extrapolation and fit warnings |
Uses one common frequency and phase to retain sign reversals rather than aligning each point independently. Inconsistent records, invalid references or no usable reference signal throw. Missing peaks/crossings and incoherent phase produce warnings while fitting is still attempted.
signedPulseCandidates and fitPulseCalibration
signedPulseCandidates(points) requires at least five distinct lengths with signed amplitude. It uses a positive peak and positive-to-negative zero crossing to return p90, p180 and related fields; unmet conditions throw.
fitPulseCalibration(points, options=) attempts a fit from at least three distinct positive lengths, returning p90, p180, A, B, r2, rmse, from, to, n and model. The model is , where ℓ is length. magnitude:true fits the absolute sine; still supply the values in amplitude. Zero signals, invalid values and failed optimization throw.
warnings contains English strings; warningDetails contains code, message and details in the same order. Use warningDetails codes for UI translation.