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.

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

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

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:
    # Every face of the cavity and of the insert lands on a cell boundary at
    # all three cell sizes below, so the rasterized structure is the same
    # physical problem at each resolution.
    sim = Simulation(
        freq_max=4e9,
        domain=(0.08, 0.064, 0.04),
        boundary="pec",
        dx=dx,
    )
    sim.add_material("insert", eps_r=4.0, sigma=0.01)
    sim.add(Box((0.032, 0.024, 0.016), (0.048, 0.040, 0.024)), material="insert")
    sim.add_source((0.024, 0.032, 0.008), "ez", waveform=GaussianPulse(f0=2.4e9, bandwidth=0.8),
                   amplitude_kind="current")
    sim.add_probe((0.056, 0.032, 0.008), "ez")
    return sim

from rfx import convergence_study


def first_resonance(result) -> float:
    modes = result.find_resonances(freq_range=(2e9, 4e9))
    if not modes:
        raise RuntimeError("no mode in the band — lengthen the run or widen freq_range")
    return float(min(mode.freq for mode in modes))

study = convergence_study(
    sim_factory=make_case,
    dx_values=[2.0e-3, 1.6e-3, 1.0e-3],
    metric_fn=first_resonance,
    run_kwargs={"num_periods": 40},
)

study.summary()

That study prints:

Mesh Convergence Summary
==================================================
   dx (mm)          Metric    Rel. Error
--------------------------------------------------
    2.0000     2.92824e+09       0.0227%
    1.6000     2.92846e+09       0.0150%
    1.0000     2.92872e+09       0.0063%
--------------------------------------------------
Extrapolated value : 2.9289e+09
Convergence order  : 1.85

Use a short trial run first, then rerun the final study with the time window required by your observable. Keep geometry, source, absorber thickness where the model has one, probe, and run duration fixed as closely as grid quantization permits. The example selects the lowest mode in a fixed band, so the same mode is tracked at every resolution, and it handles an empty find_resonances(...) result explicitly rather than indexing into it.

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.

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.