Automation

Automation helpers derive a first-pass mesh, domain, absorber, and run budget from geometry plus a frequency range, so you don’t hand-derive every simulation parameter.

Core helpers

Helper	Signature	What it does
auto_configure	auto_configure(geometry, freq_range, materials=None, accuracy="standard", *, boundary="cpml", dx_override=None, margin_override=None, n_steps_override=None, max_memory_mb=None)	derives dx, domain, CPML layers, timestep, n_steps, and (for thin z-features) a dz_profile; returns a SimConfig
plan_mesh	plan_mesh(geometry, freq_range, materials=None, accuracy="standard", *, boundary="cpml", dx_override=None, margin_override=None, n_steps_override=None, max_memory_mb=None, artifact_root=None)	wraps auto_configure and returns a serializable MeshPlan with the derived mesh, CFL basis, absorber, memory estimate, resolution/support rows, and declaration-only artifact paths
Simulation.auto	Simulation.auto(freq_range, *, accuracy="standard", **kwargs)	classmethod that builds a Simulation with mesh/domain/CPML derived from freq_range alone (empty geometry). Add geometry afterward; it warns by design to remind you
smooth_grading	smooth_grading(cells, max_ratio=1.3, *, preserve_regions=None)	inserts geometric transition cells so adjacent ratios outside preserved-region interiors do not exceed max_ratio (default 1.3); transitions already inside a preserved region remain unchanged
apply_thirds_rule	apply_thirds_rule(cells, boundary_indices)	at eligible interior material-interface indices, splits neighbouring cells into 1/3 + 2/3 pairs; edge/out-of-range indices and splits below 0.1 µm are skipped

For a nonempty geometry-derived plan, accuracy selects "draft" (10 cells/λ), "standard" (20 cells/λ), or "high" (40 cells/λ); any other value raises. Simulation.auto(...) starts from empty geometry and uses λ/10 for its initial cell size regardless of that setting, although other preset fields can still differ. smooth_grading and apply_thirds_rule are the same primitives auto_configure calls internally when it builds a non-uniform dz_profile; reach for them directly only when hand-building a mesh.

from rfx import Box, plan_mesh

geometry = [(Box((0.0, 0.0, 0.0), (0.02, 0.01, 0.002)), "fr4")]
materials = {"fr4": {"eps_r": 4.4, "sigma": 0.025}}

plan = plan_mesh(
    geometry,
    freq_range=(1.5e9, 3.5e9),
    materials=materials,
    accuracy="standard",
)
print(plan.to_markdown())   # inspect the derived mesh before committing to a run

# to_sim_kwargs() carries mesh/domain/boundary/dx (+ dz_profile when present).
mesh_kwargs = plan.to_sim_kwargs()

This is a planning example, not a runnable simulation. to_sim_kwargs() does not carry geometry or translate its coordinates into the derived absorber-free interior. When building the Simulation, place the final geometry clear of CPML, align thin z boundaries to the final profile edges, add sources and observables, and resolve the resulting preflight report.

plan_mesh(...) is the inspectable planning layer. It is a facade around auto_configure(...) and does not duplicate the mesh preset math. artifact_root only declares intended output paths; it never creates directories or writes files.

The serialized MeshPlan (schema_version="mesh-plan/v1") reports plan_source, the freq_range/accuracy/boundary inputs, and a stable cell_sizes block (nominal_dx, per-axis min/max, and profiles_present). Fields whose value is unknown are None rather than omitted — for example the lower frequency bound, margin, or the memory estimate. Serialize with plan.to_dict(), plan.to_json(), or plan.to_markdown(), and recover constructor kwargs with plan.to_sim_kwargs(). Geometry-derived plans use plan_source="auto_configure" and carry the requested accuracy, but they have not run Simulation.preflight() — a MeshPlan is a planning artifact, not physics validation.

For an already-configured Simulation, use sim.plan_mesh(...) instead (it accepts a memory budget, checkpoint spacing, and optional S-parameter checks, and runs preflight()). See the non-uniform mesh guide for when to choose each and Simulation for Simulation.auto and sim.plan_mesh.

When to use automation

• Use it for first-pass setup, not as a replacement for design review.
• Keep the derived mesh and domain visible in public examples.
• Use the result in public reporting only after it matches the support matrix and validation evidence for the intended RF workflow.

Non-uniform z profiles

For a thin substrate, auto_configure may return a graded dz_profile automatically (surfaced in MeshPlan.cell_sizes via profiles_present). To hand-build one, use smooth_grading() to bound adjacent-cell ratios outside the interiors listed in preserve_regions; ratios already inside a preserved region are left unchanged. That is useful setup evidence, but it does not by itself make a graded-z workflow a validated reference path.

Grading inserts transition cells, so physical material coordinates must be checked against the final cumulative cell edges. After adding geometry, run sim.preflight() and resolve graded_box_rasterization advisories: they flag a Box that occupies far fewer z cells than the nearby fine spacing implies. See the Non-Uniform Mesh guide for the alignment workflow.