Simulation

Simulation is the primary high-level builder in rfx. It owns the domain, boundary conditions, geometry, sources, probes, ports, and the time-domain run.

Constructor

from rfx import Simulation

sim = Simulation(
    freq_max=4e9,
    domain=(0.08, 0.06, 0.025),
    boundary="cpml",
    cpml_layers=16,
    dx=1e-3,
    mode="3d",
)

Key constructor arguments:

Argument	Meaning	Notes
freq_max	highest frequency of interest	drives mesh and timestep selection
domain	(x, y, z) domain size in metres	required unless derived by automation
boundary	boundary type	the public docs currently center on cpml
cpml_layers	absorber thickness	high-level Simulation default is 16
pec_faces	face-based PEC truncation	use for boundaries, not for a finite antenna ground plane
dx	base lateral cell size	may be inferred by automation
dz_profile / dx_profile / dy_profile	non-uniform cell profiles	workflow helper for thin-substrate or graded meshes
solver	solver family	the public reference lane is currently Yee

Ground-plane rule: if the structure needs a finite ground plane, model it as geometry. Do not use pec_faces={"z_lo"} as a substitute for antenna ground-plane metal.

Core methods

Method	Purpose	Public note
add(shape, material=...)	fill geometry with a named material	geometry should stay explicit in public examples
add_material(...)	register a named material	use this for custom dielectric / conductive / dispersive media
add_source(...)	inject a soft point source	preferred for ringdown and Harminv work
add_port(...)	add a lumped or wire port	use for impedance-normalized S-parameters within the lumped/wire evidence envelope
add_probe(...)	record a point observable	feeds Result.find_resonances()
add_ntff_box(...)	accumulate far-field data	use only when the radiation workflow is benchmarked
preflight(strict=False)	validate setup before a long run	returns a coded PreflightReport; use .errors, .warnings, .by_code(...), or .raise_for_failure() for automation gates
mesh_intelligence_report(...)	summarize configured grid, preflight issues, and AD memory estimates	useful for non-uniform and memory-constrained planning
plan_mesh(...)	return a serializable MeshPlan for this configured simulation	wraps mesh_intelligence_report(), preflight(), and optional S-parameter preflight checks
run(...)	advance the simulation	returns a Result object

Run loop

result = sim.run(n_steps=8000, compute_s_params=True)

run() returns a tuple-like Result object with fields such as time_series, s_params, freqs, ntff_data, and grid. Current main also warns on non-finite run/forward outputs instead of letting silent NaNs pass through ordinary workflows. For S-parameter claims, use the port-family evidence levels in the support matrix rather than the presence of s_params alone.

Automation entry points

Simulation also exposes a convenience constructor:

sim = Simulation.auto(freq_range=(1.5e9, 3.5e9), accuracy="standard")

Use Simulation.auto() when you want a quick starting point. Use the lower-level constructor when you need to inspect or override the derived setup.

Configured simulations can also produce the same planning artifact:

mesh_plan = sim.plan_mesh(
    n_steps=10_000,
    available_memory_gb=24.0,
    sparameter_calculator="waveguide",
)

MeshPlan is advisory: it records support checks and declaration-only artifact paths, but it does not claim solver replay or physics validation by itself. Passing artifact_root only fills intended paths; it does not write files. Configured-simulation plans use plan_source="configured_simulation", freq_range[0] = null, and accuracy = null because no auto-configure accuracy preset or lower-band edge is implied by an existing Simulation.

Current public boundary

This page covers the supported builder surface only. Lower-level solver internals, lower-level symbol inventories, and internal extensions are outside this curated public API until a guide and support entry document them.