Docs › Reference › Simulations

Simulations

Every analysis circuitRF runs, what it computes, a short overview of the method, and the full set of settings. Algorithm details are deferred to the design notes / white papers; this chapter is the operational reference.

DC (operating point)

Computes: the steady-state node voltages and branch currents with no signal applied — the bias point. For nonlinear circuits this is the prerequisite to harmonic balance.

Method: modified nodal analysis (MNA); nonlinear devices solved by Newton–Raphson with gmin and source stepping for convergence robustness.

Read currents directly with an IProbe in series, and name a voltage with a VProbe on the wire.

S-Parameters

Computes: the linear, small-signal multiport network parameters over a frequency sweep — the S-matrix at each frequency, with renormalization to the port reference impedances. Ports are defined by Term components (or P1Tone port numbers).

Method: complex MNA solved per frequency point; each port is excited in turn and the scattered waves are extracted and renormalized. Embedded Touchstone (SnP) blocks are interpolated onto the sweep.

A WSProbe anywhere in the circuit adds the wsp matrix and its derived quantities to this run, at the cost of a few extra back-substitutions and no extra factorization. See The WSProbe.

For the ideal System Components this is the analysis that answers almost everything about them: port match, isolation, coupling and directivity, a filter's passband and rejection, a duplexer's arm-to-arm leakage, and an amplifier's small-signal gain and stability.

From the CLI: circuitrf sparam circuit.cnl --freq 1GHz:10GHz:50MHz -o out.s2p.

Harmonic Balance

Computes: the steady-state response of a nonlinear circuit driven by one or more tones (up to six) — the spectrum (DC + harmonics, and mixing products when there is more than one tone) at every node. From it come Pout, gain, efficiency, PAE, compression, and intermodulation.

Method: the circuit is split into a linear sub-network (solved in the frequency domain) and nonlinear devices (evaluated in the time domain and transformed by FFT). A multidimensional Newton solve drives the harmonic-balance residual — frequency-domain KCL — to zero, using a conversion-matrix Jacobian. Power/source continuation ramps the drive to reach convergence deep into compression. Multi-tone analysis uses a diamond-truncated mixing spectrum.

For the ideal System Components this is the analysis for everything an S-parameter run cannot reach — a mixer's conversion gain and its mixing products, an amplifier's compression and IM3, and passive intermodulation on the blocks that carry it. Two tones (multi-tone) are what an intercept measurement needs.

Parametric Sweep

Computes: nothing new on its own — it wraps another analysis and re-runs it across one or more variables (drive power, a bias voltage, frequency, any user variable). Nest sweeps to cover several variables; the innermost analysis is what each point solves.

Loadpull / Sourcepull

Computes: figures of merit (Pout, gain, efficiency, PAE) as the load (or source) reflection coefficient is swept over a grid on the Smith chart — the classic loadpull experiment — ready to draw as contours. Harmonic terminations can be swept too (harmonic loadpull).

Method: a programmable Tuner presents each grid termination; a harmonic-balance solve runs per point (with previous-point continuation for convergence); the FOMs are collected into the DataSet over the Γ-grid. The Data Display fits a surface and extracts contour lines; measured loadpull files (.spl/.lpcwave) plot identically.

The termination grid file (.gam)

The grid of terminations a loadpull visits lives in a small, human-readable text file with a .gam extension — one termination per line. It is kept out of the netlist on purpose: a grid is data (often hundreds of points), and a real tuner system works the same way, reading a "pattern file" of impedance states to visit. A loadpull analysis points its grid at a .gam file; a Loadpull Pursuit can write one for you (its recommended terminations).

Each point is either an impedance (Ω) or a reflection coefficient Γ, in one of three column layouts. An optional header line (starting #) declares the form, the reference impedance, and the layout; if you omit it, circuitRF assumes impedance and infers the layout from the first data line. The parser is deliberately forgiving — blank lines and ; or # comment lines are skipped.

A Γ grid in magnitude/angle form (rings on the Smith chart):

# gamma Z0=50 mag_ang
; concentric rings of load reflection coefficient
0.00    0
0.20    0
0.20   90
0.40    0
0.40   90
0.40  180
0.60    0
0.80   30

# impedance Z0=50 re+j*imag
freq=1.8GHz
80+j*10
60-j*5
freq=2.2GHz
85+j*5
70+j*0

Using one. In the Loadpull editor, set the grid field to your .gam file (paths are resolved relative to the netlist). Getting one. A Loadpull Pursuit with an OutputGrid path writes its recommended terminations as a .gam — always in impedance … re+j*imag form, with a generated-by header and a # WARNING: line if any near-non-convergent points were dropped. That output reads straight back into a standard loadpull, including the multi-frequency layout for a frequency-swept pursuit.

Loadpull Pursuit

Computes: the load (or source) terminations that optimize a figure of merit — found automatically by a query-minimizing search rather than by gridding the whole Smith chart. It reports two optima at constant compression — MXP (maximum output power) and MXE (maximum efficiency) — recommends a conjugate-match source impedance for each, and can run a focused high-fidelity loadpull around them, all from one analysis.

Why use it: it automates the real-world PA loadpull procedure — find the optimum, then loadpull a focused grid around it with a sensible source match — into a single unattended run. Point it at a DUT whose optimal terminations are unknown, run, and come back to a complete loadpull dataset already concentrated at the right terminations. It is repeatable (great for characterizing many devices with one netlist), avoids wasted query points far from the optima, and avoids non-convergent terminations.

It complements, it doesn't replace, a standard loadpull. Pursuit finds the useful terminations and the region of interest; a standard loadpull then shows the performance tradeoffs across that region. Pursuit shares all Loadpull settings except the Γ grid (it generates terminations rather than reading them), plus the keys below.

How a pursuit run works

1. Search — a steepest-ascent search in the VSWR plane finds MXP, then MXE (seeded from MXP, so the second search is cheap). Each "query" is one drive-to-compression harmonic-balance run; queries are cached so MXE reuses MXP's data.
2. Recommend — builds a focused-around-the-optima set of recommended terminations (dense near MXP/MXE, sparse further out) and a conjugate-match source impedance for each optimum.
3. Loadpull — optionally runs a standard loadpull over those recommended terminations, using a recommended source match, producing the high-fidelity contour data.

Search method

• SteepestAscent (default) — fits the gradient and ascends along a fixed direction, shrinking the step on rejection; a final polynomial refinement pins the optimum. Fast and adequate for the near-1-D real-axis optima typical of PA loadpull.

• IteratedQuadratic — a trust-region search that re-fits the local curvature at every step, so it follows a curved 2-D ridge instead of committing to one direction. Reuses the same query cache, so its query count stays comparable.

Pursuit settings

Full design + algorithm: docs/design/loadpull_pursuit.md (in the repo).

Multi-Tone Harmonic Balance (2 to 6 tones)

Computes: the steady-state spectrum of a nonlinear circuit driven by several carriers at once — every harmonic and every intermodulation (mixing) product. Two tones is the standard test for linearity: third-order intermodulation (IM3), intercept points, spectral regrowth, and the asymmetry between the lower and upper IM products. Three or more tones is the natural setting for mixers (RF, LO and their products) and for multi-carrier work. Two tones is enough for an ideal mixer on its own — one for the RF, one for the LO — and the converted power reads off the IF port at the mixing product you want.

Multi-tone is not a separate analysis — it is Harmonic Balance with more than one tone. Everything from the single-tone chapter (the linear/nonlinear split, the Newton solve, drive continuation, all the convergence knobs) still applies. This chapter covers only what is different.

Up to six tones are supported. Everything below is written for two because that is the common case, but it holds at any tone count: read "(k₁, k₂)" as the full list "(k₁, …, k_T)". The one thing that changes with tone count is how far you can push Max mix order — see How many tones, at what order.

Setting it up

In the Harmonic Balance analysis editor, switch the Single / Multi-tone toggle to Multi-tone. Three things change:

• The single Tone (f₀) field is replaced by a tone list, starting with Tone 1 and Tone 2. + Tone adds another (up to six); the × on a row removes it, down to a minimum of two.

• Max harmonics is replaced by Max mix order — the truncation that bounds the two-dimensional mixing spectrum (see below).

• Every tone accepts an expression, so a common pattern is Tone 1 = RFfreq − Spacing/2, Tone 2 = RFfreq + Spacing/2 with RFfreq and Spacing as variables you can sweep.

• Beside Max mix order the editor shows how many mixing products the current tone count and order retain, and warns when that is over the limit — so you can see the cost of an order before you run it.

The mixing grid and mixing order

With two fundamentals, a spectral line is no longer indexed by a single harmonic number. Each line is a pair of integers (k₁, k₂) sitting at the physical frequency

f = k₁·f₁ + k₂·f₂

and its mixing order is m = |k₁| + |k₂|. The carriers are (1, 0) and (0, 1) at order 1; a third-order intermod such as 2f₁−f₂ is (2, −1) at order 3. Solving for every possible (k₁, k₂) is infinite, so circuitRF keeps a finite set bounded by Max mix order:

retain (k₁, k₂)  ⟺  |k₁| + |k₂| ≤ MaxMixOrder

That inequality is a diamond (a rotated square) in the (k₁, k₂) plane — hence "diamond truncation." A diamond rather than a full rectangular box because the high–high corner products (e.g. 5f₁+5f₂) carry no meaningful energy in a real intermod test, while every low-order product that does matter is inside the diamond. MaxMixOrder is the two-tone analog of single-tone MaxHarm: order 5 retains products down to IM5. The number of products grows quadratically with the order (≈ 2·order² lines), so a two-tone run is much larger than a single-tone run at the same order — order 5 yields dozens of mixing products versus a handful of harmonics.

With T tones the same rule reads retain (k₁,&nbsp;…,&nbsp;k<sub>T</sub>) ⟺ |k₁| + … + |k<sub>T</sub>| ≤ MaxMixOrder, and the diamond becomes a T-dimensional one. There is still a single order knob — no per-tone limits.

How many tones, at what order

The retained product count is what actually costs you, and it grows steeply with tone count — much faster than the quadratic growth two tones would suggest. The default MaxMixOrder = 5 is sized for two tones; lower it as you add tones:

Practical starting points: order 5 at 2–3 tones, order 4 at 4 tones, order 3 at 5–6 tones. On a single-FET PA, six tones at order 3 solves in a few seconds.

Measuring intermodulation (IMD2 / IMD3)

A measurement reads a mixing product out of the result by its (k₁, k₂) tag — at three tones the tag simply has three entries, e.g. HB1.V("Vout", "(1,1,-1)") for the triple-beat product f₁+f₂−f₃. The classic figures of merit are the intermodulation ratios in dBc — an IM product relative to its carrier:

IMD2 = dB( HB1.V("Vout", "(1,-1)") ) - dB( HB1.V("Vout", "(1,0)") )   dB
IMD3 = dB( HB1.V("Vout", "(2,-1)") ) - dB( HB1.V("Vout", "(1,0)") )   dB

Replace HB1 with your analysis name and "Vout" with your output node. IMD2 uses the baseband product (1,−1) = f₁−f₂; IMD3 uses the lower third-order product (2,−1) = 2f₁−f₂ (use (−1,2), referenced to the (0,1) carrier, for the upper IM3). To get the curve vs Pin, sweep the drive power (a parametric sweep over the variable your source Pavl references) — the same expression then returns IMD vs Pin instead of a single value.

Source impedance and harmonic terminations

With dozens of products spread across the spectrum, each one needs a source termination. circuitRF assigns it by frequency, not by mixing order. It defines a band-center fundamental — for two tones the average f_c = (f₁ + f₂) / 2 — and places each product in the harmonic band nearest its frequency:

band n = round( |f| / f_c ) → Z[n] if declared, else the shared Z

So band 0 (|f| < f_c/2) is the baseband and uses Z[0]; band 1 (around f_c) holds both carriers and all the close-in IM3/IM5 products and uses Z[1] (or the default Z); band 2 (around 2·f_c) holds the second-harmonic products and uses Z[2]; and so on. The decision is purely the product's frequency: as a high-order product such as (3, −1) drifts down past the band-1/band-2 boundary it switches from Z[2] to Z[1] automatically — no order threshold is hard-coded. This is the same harmonic-termination model as P1Tone, and a PnTone presents its shared Z and per-band Z[k] to the whole multi-tone spectrum this way.

What's different from single-tone

• IM3 asymmetry. The lower IM3 (2f₁−f₂) and upper IM3 (2f₂−f₁) generally have different levels in dBc, not just a phase difference — a direct consequence of the device's nonlinear I–V/Q–V behaviour and its loading. The full diamond resolves both, so the asymmetry is a real output of the run, not an artifact.

• A fully coupled solve. The two-tone result is not two single-tone solutions superimposed. The carriers, harmonics, IM products, and baseband are all unknowns in one Newton solve with a single conversion-matrix Jacobian — so the IM levels capture the true bidirectional coupling between the carriers and the baseband.

• A bigger spectrum, a bigger cost. Because the product count grows quadratically with MaxMixOrder, raise it only as far as you need: 5 captures IM5 (usually enough); higher captures IM7+ at noticeably more cost.

• Commensurate tones. f₁ and f₂ must be commensurate (a rational ratio) so every mixing product lands exactly on the grid and the waveform is exactly periodic — closely-spaced tones like 1.99 / 2.01 GHz satisfy this naturally.

Full design + algorithm: docs/design/harmonic-balance.md and the harmonic-termination model in docs/design/p1tone-harmonic-terminations.md (in the repo).

Running an analysis from the command line

Everything above is driven from the GUI's Run button, and everything above also runs headless. The command-line driver takes a .cnl netlist — hand-authored, or extracted from a schematic — and runs one analysis:

circuitrf sparam <file.cnl> [--freq start:stop:step] [-o out.sNp]
circuitrf dc     <file.cnl>
circuitrf hb     <file.cnl>       harmonic balance; runs the sweep if one wraps it
circuitrf lp     <file.cnl>       loadpull over the directive's Gamma grid
circuitrf lpp    <file.cnl>       loadpull pursuit: searches for MXP / MXE
circuitrf em     <file.cem>       electromagnetic extraction of the layout it names
circuitrf elab   <file.cnl>       dump the elaborated netlist

From a source checkout, put dotnet run --project src/Cli -- where circuitrf appears.

The full reference for every verb, its options, its output and its exit codes is The Command Line — including a worked EM run from an empty folder. This section covers only the part that is about analyses rather than about the driver.

Harmonic balance from the command line

dotnet run --project src/Cli -- hb hero2.cnl -o out.mat

That runs the netlist's harmonic-balance analysis — single- or multi-tone; the same verb does both — prints the spectra as tables, and writes out.mat.

dotnet run --project src/Cli -- hb hero5.cnl --set Pavl_dbm=0 -o hero5.txt

Loadpull and pursuit from the command line

dotnet run --project src/Cli -- lp  hero3.cnl  --pin -20:1:15 -o hero3.spl
dotnet run --project src/Cli -- lpp hero3B.cnl --out-grid found.gam -o hero3B.npy

lp prints one row per Γ grid point — where it was, how it stopped, and its figures of merit at the last converged, non-tickle drive step — rather than the raw [gridPoint × driveStep] cubes. lpp prints its MXP and MXE optima first, then the follow-on grid. Both take the HB options above, plus --pin, --compression, and one grid option each: --grid for lp, --out-grid for lpp. lp also exports .spl and .lpcwave, the loadpull interchange formats the Data Display reads back. Full detail.

Electromagnetic extraction from the command line

dotnet run --project src/Cli -- em Amp.cem

em takes a .cem EM setup and needs no other arguments — the layout and the technology resolve by walking up to their own workspaces, exactly as they do in the GUI. It writes the Touchstone and the diagnostics .npy where the Simulate button writes them, so a schematic's SnP reference survives a headless re-run. Full detail, with a worked example.

Measurements, and why headless is the regression harness

The measure lines on the TestBench are evaluated exactly as the GUI evaluates them, and a measurement that fails to evaluate is reported on stderr and the run continues. A .cnl that works headless works when opened, which is what makes the command line usable as a regression harness: the two paths share the elaborator, the engines and the measurement evaluator.

See also: the netlist format (how analyses are written) · Components · Plot types · Measurements · Results & data export · The command line.