Skip to content

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

OperationRequired optionsChanged field / extra result
sweep(parameters, options)startHz, endHz, stepHzfrequencyHz / frequencies
pulseSweep(parameters, options)startCycles, endCycles, stepCyclespulse1Cycles / 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.

js
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.

ResultContents
pointslength, signed amplitude, quadrature, magnitude, record
referencehz, phaseRad, phaseDegrees, referenceIndex, coherence
measuredCandidates from the measured peak and zero crossing, or null
fit / magnitudeFitSigned / magnitude sine fit, or null if not computable
warningsArray 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 Asin⁡ ⁣(πℓ2p90)+BA\sin\!\left(\frac{\pi\ell}{2p_{90}}\right)+B, 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.

Graph examples · Archive loading · API index