Memory-Reduction Path

Plan first, then validate physics

Memory reports and cell-savings factors are planning evidence. They do not replace a uniform-grid, analytic, or external-solver physics check for the RF observable you want to claim.

The memory-reduction goal in rfx is to keep JAX-native FDTD workflows small enough to run while preserving the support boundary for the observable being claimed.

Decision ladder

Need	Preferred lane	Public status
Ordinary RF reference, general S-parameters, ports, far-field claims	Uniform Cartesian Yee	validated default
Thin substrate or layered z structure that would force a tiny uniform cell everywhere	Non-uniform z mesh + segmented AD	limited-support path; verify against a uniform or external reference before public claims
Large inverse-design run where reverse-mode tape is the memory limit	checkpoint_every / segmented scan where the selected runner supports the physics	planning tool, not validation evidence
Need to reduce memory for a port-family S-parameter claim	Use the calculator-supported lane first, then document the memory plan	validation scope still follows the port-family support matrix

Use the documented memory-planning and non-uniform workflows for public examples; other local-refinement code paths require an explicit support entry before publication.

Non-uniform + segmented AD workflow

Start with the non-uniform lane when a small feature only needs fine cells along one axis, such as a thin substrate in a much larger air volume.

plan = sim.plan_ad_memory(n_steps=10_000, available_memory_gb=24.0)
report = sim.mesh_intelligence_report(
    n_steps=10_000,
    checkpoint_every=plan.checkpoint_every,
    available_memory_gb=24.0,
)

print(plan.recommendation)
print(report.cell_savings_factor)
print(report.recommendation)

plan_json = plan.to_json()
report_json = report.to_json()

Use the report to check:

• cell_savings_factor: comparison against a uniform-fine grid at the smallest configured cell size,
• preflight_issues: geometry, resolution, and feature-support warnings to resolve before trusting results,
• ad_memory.ad_segmented_gb: reverse-mode AD planning estimate when checkpoint_every is enabled,
• recommendation: compact next action for the configured case.

plan_ad_memory(...) is the budget-fitting helper: it returns checkpoint_every=None when full reverse-mode AD already fits, otherwise it recommends the smallest segmented-scan chunk length estimated to fit under the requested memory target.

For a reusable JSON artifact without running FDTD, use:

python scripts/memory_reduction_planning_artifact.py --available-memory-gb 24.0

Then run the physics validation appropriate to the observable: analytic resonance, uniform-grid convergence, Meep/openEMS comparison, or an existing cross-validation script. Do not treat a green memory report as an accuracy claim by itself.

What to archive with a memory-reduction run

For a validated memory-reduction result, keep these artifacts together:

1. mesh_intelligence_report(...).to_json(),
2. plan_ad_memory(...).to_json() when reverse-mode AD memory is part of the claim,
3. the exact run command and version/commit,
4. the physics validation artifact for the claimed observable,
5. any unsupported-feature decisions or validation errors,
6. gradient evidence if the result depends on jax.grad.

This keeps the memory story separate from the physics claim: saving cells or AD tape is useful only when the RF observable and gradient path remain inside their validated support boundary.