Tutorial: Convergence Study

A convergence study answers a simple question: does the reported metric stabilize as the Yee cell size decreases? Use it before making quantitative claims from a new geometry, mesh, or objective.

1. Choose one scalar metric

Pick a metric that matches the claim you want to make:

Claim type	Example metric
resonance	first Harminv frequency in a target band
S-parameter	abs(S[receiver, driven, f_idx]) at a documented frequency
field amplitude	peak or RMS probe value after source decay
far field	directivity or normalized pattern value from a documented NTFF setup

Do not mix several changing metrics in one convergence decision. Run separate studies if needed.

2. Build a simulation factory

The factory should accept dx and return the same physical problem at that cell size.

from rfx import Simulation, Box, GaussianPulse


def make_case(dx: float) -> Simulation:
    # Keep the absorber about 12 mm thick as dx changes.
    cpml_layers = max(4, round(0.012 / dx))
    sim = Simulation(
        freq_max=4e9,
        domain=(0.08, 0.06, 0.04),
        boundary="cpml",
        cpml_layers=cpml_layers,
        dx=dx,
    )
    sim.add_material("insert", eps_r=4.0, sigma=0.01)
    sim.add(Box((0.032, 0.024, 0.018), (0.048, 0.036, 0.022)), material="insert")
    sim.add_source((0.024, 0.030, 0.020), "ez", waveform=GaussianPulse(f0=2.4e9, bandwidth=0.8))
    sim.add_probe((0.056, 0.030, 0.020), "ez")
    return sim

3. Run the study

import numpy as np
from rfx import convergence_study


def peak_probe_metric(result) -> float:
    return float(np.max(np.abs(np.asarray(result.time_series[:, 0]))))

study = convergence_study(
    sim_factory=make_case,
    dx_values=[2.0e-3, 1.5e-3, 1.2e-3],
    metric_fn=peak_probe_metric,
    run_kwargs={"num_periods": 20},
)

print(study.summary())

Use a short trial run first, then rerun the final study with the time window required by your observable. Keep physical absorber thickness, geometry, source, probe, and run duration fixed as closely as grid quantization permits. The example uses a peak-probe metric because it is always defined; a resonance metric must handle an empty find_resonances(...) result explicitly.

4. Interpret the result

A useful convergence report should include:

• the tested dx values,
• the scalar metric at each resolution,
• the Richardson-extrapolated value and observed order,
• the relative error of the finest point,
• the exact command or notebook cell used to reproduce the study.

If the finest two points do not move monotonically or the observed order is implausible, treat the result as inconclusive and inspect the setup before tightening tolerances.

5. Archive the evidence

A convergence plot or table is evidence for that exact observable, not for every feature in the simulation. Keep it with the support status, git SHA, run command, and any external reference used for the final claim.

For broader validation context, see Cross-Validation and Accuracy and the Benchmark Table.