Simulation

Simulation holds one model: the domain and mesh, boundaries, materials, geometry, sources, ports and observables. You build it with add_* calls, check it with preflight(), and solve it with run() or, for gradients, forward(). This page lists the constructor and those entry points. The mental model behind them is in Core Concepts.

Simulation(freq_max, domain, *, boundary="cpml", cpml_layers=16,
           cpml_kappa_max=1.0, dx=None, mode="3d",
           dz_profile=None, dx_profile=None, dy_profile=None, dt=None,
           dt_min_cell=None, precision="float32", solver="yee",
           adi_cfl_factor=2.0, stencil_order=2, interface_eps="sampled")

import numpy as np
from rfx import Box, GaussianPulse, Simulation

sim = Simulation(
    freq_max=5e9,                # highest frequency of interest (Hz)
    domain=(0.04, 0.03, 0.03),   # x, y, z size (m)
    dx=2e-3,                     # cubic cell size (m)
    boundary="cpml",
    cpml_layers=6,
)

Put PEC faces in a BoundarySpec. Neither is a finite ground plane: for that, draw a sheet with add_thin_conductor().

Every add_* method returns the simulation, so calls can be chained.

sim.add_material("slab", eps_r=3.0, sigma=0.01)
sim.add(Box((0.018, 0.0, 0.0), (0.024, 0.03, 0.03)), material="slab")
sim.add_source((0.010, 0.015, 0.015), "ez",
               waveform=GaussianPulse(f0=3e9, bandwidth=0.8),
               amplitude_kind="current")
sim.add_probe((0.030, 0.015, 0.015), "ez")

report = sim.preflight()
print(report.ok, len(report.errors), len(report.warnings))
report.raise_for_failure()     # raises only on errors
sim.fidelity_report()

PreflightReport is a list of coded issues. Read .ok, .errors, .warnings, .infos or .by_code(code). Don’t test it with if report:: that raises TypeError, because an advisory-only report is non-empty but fine. strict=True raises on errors instead of returning them.

run() is the general entry point. It returns a Result; see Results & Observables.

run(*, n_steps=None, num_periods=20.0, until_decay=None,
    decay_check_interval=50, decay_min_steps=100, decay_max_steps=50000,
    decay_energy_consecutive=2, ..., checkpoint=False,
    compute_s_params=None, s_param_freqs=None, s_param_n_steps=None,
    snapshot=None, subpixel_smoothing=False, conformal_pec=None,
    conformal_min_weight=0.1, devices=None, exchange_interval=1,
    skip_preflight=False, report_every=None, report_label="",
    ringdown=None) -> Result

result = sim.run(n_steps=300)
print(result.time_series.shape, f"settling {result.settling_db:.1f} dB")

Run length. Give exactly one of:

until_decay works on absorbing boundaries, on uniform and graded meshes. It watches the total energy in the interior, so it is a sound stop for spectra, flux and S-parameters. In a closed PEC box the energy does not decay. There the uniform solver falls back to a single field sample, which is reliable only for lossy or radiating ring-down, and a graded mesh runs the fixed n_steps with a warning. Use a fixed n_steps in closed structures and in convergence studies.

Other arguments you will use:

A run argument that the selected solver path does not implement raises before the first step, for example snapshots on a graded mesh or until_decay with the ADI solver. Nothing is silently dropped.

Warnings after the run. run() warns when a probe recorded no field, when a Gaussian-pulse probe record had not rung down (end of record above −40 dB of peak), and when time_series or lumped/wire s_params contain NaN/Inf or an |S| above 1.1. These checks cover only those arrays. For DFT planes, flux and NTFF data, check np.isfinite(...) yourself. No warning does not mean the run converged.

from rfx.ringdown import RingdownSpec, then run(..., ringdown=RingdownSpec()). For a wire-port run (add_port(..., extent=...)) whose record ended too early, rfx fits the slowly decaying poles in the last part of the record and adds the missing tail of each spectrum in closed form. The completed matrix is result.ringdown.s_params, on the same frequencies as result.s_params, and result.ringdown.report holds the fitted poles and the checks. report.ok is decided by the error witness (completing from [T/4, T] versus [T/2, T]). The two-window difference W2 is reported, not judged. None of the witnesses is an error bound. The source must be off in the fit window. It covers wire ports (one port on a uniform mesh, or a graded mesh) with a fixed n_steps. Other ports, TFSF, until_decay and devices= are refused with the reason. s_params is None when the report says no completion was produced.

forward() runs the same physics with only the outputs a loss function needs, so it can sit inside jax.grad, jax.value_and_grad or jax.jit. It returns a ForwardResult with time_series, s_params/freqs (lumped/wire S11 vectors when port_s11_freqs= is set), ntff_data, dft_planes, grid and dt.

forward(*, eps_override=None, sigma_override=None, mu_r_override=None,
        design_box=None, design_eps_override=None,
        design_sigma_override=None, design_occupancy_override=None,
        pec_mask_override=None, pec_occupancy_override=None, n_steps=None,
        num_periods=20.0, checkpoint=True, checkpoint_segments=None,
        emit_time_series=True, checkpoint_every=None, n_warmup=0,
        skip_preflight=False, distributed=False, devices=None,
        exchange_interval=1, port_s11_freqs=None,
        rlc_values_override=None) -> ForwardResult

import jax
import jax.numpy as jnp

grid = sim.freeze_mesh()
i0 = grid.position_to_index((0.018, 0.0, 0.0))[0]
i1 = grid.position_to_index((0.024, 0.0, 0.0))[0]

def loss(eps_slab):
    eps = jnp.ones(grid.shape).at[i0:i1].set(eps_slab)
    out = sim.forward(eps_override=eps, n_steps=300, skip_preflight=True)
    return jnp.sum(out.time_series[:, 0] ** 2)

print(jax.grad(loss)(3.0))

Per-cell versus per-edge conductivity in a design box. A single design_sigma_override array is per cell. rfx averages the four cells around each E edge, and that average also reaches the edge layer on the box’s plus faces. A 3-tuple (sigma_x, sigma_y, sigma_z) is per edge at the box indices and is written as-is. If a per-edge design needs that plus-face layer, declare the box one cell larger on that side.

Keep anything that changes array shapes, the geometry list or the solver path outside the function you differentiate. A combination the differentiable path does not support raises instead of returning a zero gradient. A model with add_refinement is refused by forward(). Guides: Autodiff and Adjoint, Inverse Design, Memory Reduction.

Each port family has its own calculator method on Simulation: compute_msl_s_matrix(), compute_waveguide_s_matrix(), compute_coaxial_line_reflection() and compute_coaxial_two_port(). Lumped and wire ports use run(compute_s_params=True). compute_s_matrix(lane=None, **kwargs) picks the right method from the registered ports and forwards your arguments. s_matrix_lane() tells you which one it would pick without running anything. Details: Sources & Ports.

Simulation.auto(freq_range, *, accuracy="standard", **kwargs) -> Simulation

auto_sim = Simulation.auto(freq_range=(1.5e9, 3.5e9), accuracy="draft")

This derives dx, the domain and the CPML thickness from the frequency range alone. accuracy is "draft", "standard" or "high". Any keyword argument overrides the derived value. It warns on purpose: the domain was sized without your geometry, so check it after you add shapes. To derive a mesh from your geometry instead, use auto_configure or plan_mesh on the Automation page.

These are documented in the generated reference: estimate_ad_memory, plan_ad_memory, ad_memory_preflight and explain_ad_memory (reverse-mode memory, see Memory Reduction); export_scene, export_artifact_bundle and artifact_report (saving a model and its results); conductor_mask.

• A graded mesh accepts fewer features than a uniform one. Snapshots, lumped port S-parameters, coaxial ports, UPML and Floquet ports raise there. See Support Boundaries.
• add_refinement works only through run() on a uniform mesh. forward(), optimize() and topology_optimize() refuse a refined model.
• precision="mixed" raises the CPML reflection floor. Don’t use it for S-parameters or low-reflection work.
• A completed run is not a converged run. Check result.settling_db and do a convergence study before you quote a number.