Power and Frequency Calibration

Introduced in version 3.8.2

Power and Frequency Calibration describes the relationship between an AWG output and the power actually delivered at the spectrometer output. It lets you pre-distort AWG generated waveform to account for amplifier compression and frequency response. Amplifier compression is given by the table while frequency profile is defined by Lorentzian.

An RF power amplifier is linear only up to a point: as the drive grows the output power eventually saturates (compresses), so the requested and produced powers no longer match. A power calibration is a measured curve of amplifier input vs. output power together with a few scalar parameters describing the AWG drive. SpecMan uses it in two directions:

Leave the boost room to work. An AWG pattern is defined on -1 ≤ A ≤ 1, and the frequency correction multiplies it — nothing renormalizes the result afterwards. The base amplitudes in your program therefore have to be chosen so that the corrected waveform still fits: with maxboost_dB = 6 the correction may scale a sample by 10^6/20 = 1.99, so keep the base pattern inside -0.5 ≤ A ≤ 0.5; the default 12 dB (×3.98) leaves you a quarter of the range. Amplitudes that ignore this are not scaled down for you — the driver clamps the corrected samples as it packs them into DAC codes, so the pulse is clipped precisely where the correction was largest, which is the part of the band it was there to fix. The ceiling that also accounts for the amplifier's own compression is pcal_maxamp_bw(), under Maximum linear AWG level below.

Conversion (on demand) — the Compound Property functions pcal_* convert between AWG amplitude / drive power and delivered output power, in either direction, so power-domain quantities can be computed and displayed.

Power calibrations are defined in the [PowerCalibrations] section of the Device Configuration (CFG), and are shown — with the scalar values editable — in the Spectrometer Configuration dialog.

Introduced in version 3.8.9

Creating one. Select the PCAL node in the Spectrometer Configuration dialog and press Create Default Calibration: SpecMan writes <name>.pcal next to the .cfg from a template carrying both models, and appends the [PowerCalibrations] entry with placeholder scalars. A file of that name that already exists is used as it is and is never overwritten. The entry reaches the .cfg only when the configuration is saved. The console does the same, so a script can too:

.s.spec.pcal.create           ; named after the config: JIVA25-HDAWG1, ...2, ...
.s.spec.pcal.create = 'Amp2'  ; creates Amp2.pcal next to the .cfg

Edit the created .pcal for the real amplifier and the real response, set the scalars on the page, and point an AWG driver at it with its own PowerCalibration=<index> key — a calibration nothing references changes nothing.

The calibration model

Each calibration relates a normalized AWG amplitude a in [0, 1] to the amplifier output power through this chain:

  AWG drive  (dBm) = UnitPower + 20*log10(a)     -- AWG output at amplitude a
  amp input  (dBm) = drive + SystemGain          -- linear-ideal amplifier output
  amp output (dBm) = curve(amp input)            -- measured compression curve

Scalar parameters
Parameter	Meaning
`UnitPower`	AWG output power (dBm) at full-scale sample magnitude (amplitude = 1.0).
`SystemGain`	Gain (dB) from the AWG output to the amplifier output; the linear-ideal full-scale output is `UnitPower + SystemGain`.
`MaxAllowedInput`	Highest permissible AWG drive (dBm). Predistortion warns and clamps if a waveform would exceed it.
`MinPower`, `MaxPower`	Low / high end (dBm) of the calibration's valid output-power range. `MaxPower` is the amplifier ceiling used to clamp predistortion requests.

Introduced in version 3.8.9

The compression curve is described by a model in the referenced .pcal file (JSON). A model is a handful of physical parameters rather than a table of points; a measured table is one of the available model kinds.

{"saturation": {"model":"rapp", "psat_dBm":59.8, "knee":2.5}}

Saturation model kinds
Model	Parameters	Meaning
`rapp`	`psat_dBm` or `p1db_dBm`, `knee`	The standard solid-state amplifier soft limiter, `out = in / (1 + (in/sat)^2p)^1/2p`. `psat_dBm` is the saturated output power and `knee` (p) how sharply the curve turns over — about 1 for a soft amplifier, 3 typical, 10 or more for near-hard clipping. Give `p1db_dBm` (the 1 dB compression point, which datasheets quote) instead of `psat_dBm` if that is what you know. Monotonic by construction and exactly invertible.
`table`	`table`, `units`	A measured curve: `[[in,out], ...]` pairs in dBm. The curve must be monotonic over the range in use; this is checked when the file is loaded.
`expression`	`expr`, `var`	A free-form formula in `x`, using the Compound Property function set. `var` selects whether `x` is a power in dBm (default) or a normalized amplitude. Inverted numerically, so it too must be monotonic.
`off`	—	No correction. The section is kept in the file with its parameters intact, so a correction can be switched off and back on without deleting and retyping it — useful while a calibration is being worked out. `none` and `disabled` are accepted spellings. An off correction is skipped entirely: it costs nothing and applies no clamps, exactly as if the section were absent, but it is reported as off rather than none so a disabled correction is never mistaken for a missing one.

{"saturation": {"model":"off"},
 "frequency":  {"model":"lorentzian", "f0_MHz":15, "fwhm_MHz":10}}

Both sections take off independently, so either correction can be isolated while the other is studied. The same distinction appears in the message log, the Spectrometer Configuration dialog and .s.spec.pcal.N.info.

{"saturation": {"model":"table",
                "units":{"input":"dBm","output":"dBm"},
                "table":[[in0,out0],[in1,out1], ...]}}

A file that contains only a bare top-level table (the pre-3.8.9 layout) is still read as a saturation table model, so existing calibrations keep working unchanged.

MaxPower is normally derived from the model — it is the power delivered at full-scale drive, so it cannot disagree with the curve. A file that states maxPower_dBm explicitly keeps that value.

When no saturation model is loaded every relation degrades to the linear-ideal form UnitPower + SystemGain + 20*log₁₀(a) — calibration becomes a pure passthrough.

Frequency response

Introduced in version 3.8.9

A calibration may also carry a frequency model, the complex response H(f) of the amplifier and resonator. Where the saturation model corrects how hard the waveform is driven, this one corrects where in frequency it sits — the pulse spectrum is multiplied by 1/H(f), so a chirp swept across a resonator comes out with a flat amplitude and an undistorted phase.

{"frequency": {"model":"lorentzian", "f0_MHz":9420, "fwhm_MHz":60,
               "maxboost_dB":12, "sideband":"usb"}}

Frequency model parameters
Parameter	Meaning
`f0_MHz`, `fwhm_MHz` / `q`	Resonance centre and width, both in MHz. Give either the full width at half maximum or the quality factor; the other follows from `fwhm = f0/Q`. Every frequency in a `.pcal` is in MHz, and the field name says so. For a single-pole resonator the centre and width fix the phase as well as the magnitude, so this pair describes the entire complex response.
`maxboost_dB`	Largest correction the predistortion may apply, in ordinary gain decibels (default 12). Away from resonance `1/H` grows without limit, so it has to be capped. The cap is on the waveform amplitude: 12 dB permits an amplitude factor of `10^12/20 = 3.98`, which is a power factor of `10^12/10 = 15.85` — the same 12 dB either way. The cap also decides the usable width: outside the band where `1/H` stays under it the correction is clamped, and a segment whose FFT bins are coarser than that width gets no frequency correction at all.
`sideband`	`usb` (default), `lsb` or `dsb`, describing how the AWG baseband maps onto the absolute frequency axis through the LO.

Introduced in version 3.8.10

Adjusting the cap live. maxboost_dB is the one frequency-model parameter you can change without editing the file and reloading: Max Boost on the Power Calibration page of the Spectrometer Configuration dialog, or .s.spec.pcal.N.maxboost on the console, where .usable reads back the width the cap leaves. Unlike f0 and fwhm it applies to every model kind, not just the Lorentzian. The change takes effect on the next pattern rebuild and is not written back into the .pcal, so reloading the configuration restores the file's value.

The LO. The pattern the AWG generates is at baseband; the frequency model lives on the absolute axis. The LO value on the calibration bridges the two, and it is not read from the synthesizer — set it from the console so an external script can drive it alongside the source frequency:

.s.spec.pcal              ; list the calibrations
.s.spec.pcal.0.info       ; describe calibration 0
.s.spec.pcal.0.lo 9.42e9  ; place the pattern on the absolute axis (console is in Hz)
.s.spec.pcal.0.f0         ; read the resonance
.s.spec.pcal.0.fwhm 5e7   ; retune the width (console is in Hz)
.s.spec.pcal.0.maxboost 6 ; cap the correction at 6 dB (any model kind)
.s.spec.pcal.0.usable     ; read the width that cap leaves (Hz)

Writing any of these forces the AWG patterns to be rebuilt, so the next acquisition uses the new correction. Nothing links LO to the synthesizer automatically: if a script steps the source frequency without stepping LO with it, the correction is applied at the wrong place in the profile. LO = 0 means direct synthesis, where the pattern frequencies are already absolute.

Two limitations follow from the physics rather than the implementation. A real (non-IQ) output has a symmetric spectrum, so only the magnitude of H(f) can be corrected on it — the phase is left in place, and SpecMan says so once in the message log. The same applies to a double-sideband up-conversion, where the baseband lands on both sides of the LO at once.

The other frequency model kinds are table (measured [f_MHz, magnitude, phase_deg] rows, phase optional) and expression (formulas for magnitude and phase in f, which is in MHz). A Resonator Dip measurement is a good source for f0_MHz and the width; note that the dip itself is a reflection curve and not the same thing as the excitation response, so seed the model from it rather than using it directly.

Predistortion

Before an AWG driver packs a generated waveform it passes the sample buffer through the calibration. The frequency correction runs first, on the still-linear waveform, and the saturation predistortion after it — that order matters, because the compression inverse is only valid for the envelope actually presented to the amplifier.

Each sample's magnitude is then predistorted so the intended output power is produced despite compression; the sign (for real channels) or the phase (for IQ pairs) is preserved. If a request would exceed MaxPower, MaxAllowedInput, or the DAC full scale, the value is clamped and a single summary warning is posted to the message log.

Conversion functions

The Compound Property engine exposes four calibration functions. Each takes a calibration index (the 0-based position in the [PowerCalibrations] table) and a value. The drive side is the AWG — amplitude in [0, 1] or drive power in dBm — and the output side is always power in dBm.

pcal_* compound functions
Function	Direction	Returns
`pcal_AWG(i, amp)`	forward	output power (dBm) for AWG amplitude `amp`
`pcal_dBm(i, drive)`	forward	output power (dBm) for AWG drive power `drive` (dBm)
`pcal_inv_AWG(i, P)`	inverse	AWG amplitude in [0, 1] needed for output power `P` (dBm)
`pcal_inv_dBm(i, P)`	inverse	AWG drive power (dBm) needed for output power `P` (dBm)

See Compound Property for how to define a compound property that uses these, and for the exact argument and error rules. The function names are case-sensitive (pcal_dBm, not pcal_dbm).

Maximum linear AWG level

The central use of the calibration is to find the highest AWG amplitude that still stays in the linear (calibrated) region, and to use it as a ceiling on the amplitudes in your Pulse Programming Language program. Driving above this level pushes the amplifier into compression, where the requested and produced powers diverge.

The inverse function gives this limit directly — the amplitude that reaches the top of the valid power range:

[Compound]
MaxAWG            = , r, nohshake, 0.01, 0.01, 2, 0, 1
MaxAWG.definition = pcal_inv_AWG(0, 5)        ; 5 dBm = MaxPower of calibration 0

which, for a typical setup, evaluates to something like 0.67. Read that value from the @System property and use it as the maximum amplitude in your experiment.

Introduced in version 3.8.9

Two functions give these limits directly. pcal_maxamp(i) is the power-domain ceiling — the same number as the pcal_inv_AWG idiom above, without having to name the power. pcal_maxamp_bw(i, bw) is the second ceiling: the highest amplitude that also stays linear across a pulse of bandwidth bw (Hz), since the frequency correction spends part of the same headroom boosting the edges of the band.

[Compound]
MaxAWG            = , r, nohshake, 0.01, 0.01, 3, 0, 1
MaxAWG.definition = min(pcal_maxamp(0), pcal_maxamp_bw(0, 100MHz))

Use the lower of the two as the amplitude ceiling in your experiment. The console reports the power-domain value directly as .s.spec.pcal.0.maxamp.