# Simulation API

Channel: development; package: 2.0.0rc1; source: 2c32b7cf79b796fae825bfa08fc73d9914e61723

Page: https://remilab.ai/rfx/guide/api-reference/
Source: https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/docs/public/guide/api-reference.mdx

This page is a map of the calls you use in almost every model and the objects
they return. Each row links to the API page with the full signature and
arguments. For every public symbol, see the
[generated reference](https://remilab.ai/rfx/api/generated/).

## The workflow in calls

```text
sim = Simulation(freq_max, domain, dx=..., boundary="cpml")   # domain and mesh
sim.add_material(...); sim.add(shape, material=...)           # materials, geometry
sim.add_source(...) or sim.add_port(...)                      # excitation
sim.add_probe(...); sim.add_flux_monitor(...)                 # observables
sim.preflight()                                               # check
result = sim.run(n_steps=...)                                 # solve -> Result
```

## Building a model

| Call | Does | Reference |
|---|---|---|
| `Simulation(freq_max, domain, *, dx, boundary, cpml_layers, dz_profile, ...)` | domain, mesh, boundaries | [Simulation](https://remilab.ai/rfx/api/simulation/#constructor) |
| `add_material(name, *, eps_r, sigma, mu_r, debye_poles, lorentz_poles)` | a named material | [Geometry & Materials](https://remilab.ai/rfx/api/geometry-materials/#materials) |
| `add(shape, *, material)` | fill a `Box`, `Sphere`, `Cylinder`, `PolylineWire`, `Via`, `MeshShape`... | [Geometry & Materials](https://remilab.ai/rfx/api/geometry-materials/#placing-shapes) |
| `add_thin_conductor(shape, *, surface_impedance_f0=None)` | a copper sheet | [Geometry & Materials](https://remilab.ai/rfx/api/geometry-materials/#metal-sheets) |
| `add_source(position, component, *, waveform, amplitude_kind="current")` | point source, no impedance | [Sources & Ports](https://remilab.ai/rfx/api/sources-ports/#sources) |
| `add_tfsf_source(...)` | plane wave | [Sources & Ports](https://remilab.ai/rfx/api/sources-ports/#sources) |
| `add_port`, `add_msl_port`, `add_waveguide_port`, `add_coaxial_port` | ports for S-parameters | [Sources & Ports](https://remilab.ai/rfx/api/sources-ports/#ports) |
| `add_probe`, `add_dft_plane_probe`, `add_flux_monitor`, `add_ntff_box` | observables | [Results & Observables](https://remilab.ai/rfx/api/results/#observables) |

## Checking and running

| Call | Returns | Reference |
|---|---|---|
| `preflight()` | `PreflightReport` (read `.ok`, `.errors`, `.warnings`) | [Simulation](https://remilab.ai/rfx/api/simulation/#checking-before-you-run) |
| `fidelity_report()` | where each shape landed on the grid | [Simulation](https://remilab.ai/rfx/api/simulation/#checking-before-you-run) |
| `run(n_steps= / num_periods= / until_decay=, ...)` | `Result` | [Simulation](https://remilab.ai/rfx/api/simulation/#run) |
| `forward(eps_override=..., ...)` | `ForwardResult`, differentiable with JAX | [Simulation](https://remilab.ai/rfx/api/simulation/#forward-the-differentiable-path) |
| `plan_mesh(...)`, `Simulation.auto(...)` | a proposed mesh and domain | [Automation](https://remilab.ai/rfx/api/functions/) |

## S-parameters

Each port family has its own calculator:

| Ports | Call | Returns |
|---|---|---|
| lumped / wire `add_port` | `run(compute_s_params=True, s_param_freqs=...)` | `Result.s_params`, `Result.freqs` |
| microstrip `add_msl_port` | `compute_msl_s_matrix()` | `MSLSMatrixResult` |
| waveguide `add_waveguide_port` | `compute_waveguide_s_matrix()` | `WaveguideSMatrixResult` |
| coaxial `add_coaxial_port` | `compute_coaxial_line_reflection()` or `compute_coaxial_two_port()` | `CoaxialLineReflectionResult`, `CoaxialTwoPortResult` |

`sim.compute_s_matrix()` chooses the calculator from the registered ports, and
`sim.s_matrix_lane()` tells you which one it would use. Microstrip and coaxial
ports are not computed by `run(compute_s_params=True)`. Details:
[Sources & Ports](https://remilab.ai/rfx/api/sources-ports/#s-parameter-calculators).

## Reading results

| Object | Main contents | Reference |
|---|---|---|
| `Result` | `time_series`, `dt`, `settling_db`, `s_params`, `freqs`, `flux_monitors`, `dft_planes`, `ntff_data`, `snapshots`; `find_resonances()`, `s11()`, `s_db()` | [Results & Observables](https://remilab.ai/rfx/api/results/#result) |
| `ForwardResult` | `time_series`, `s_params`, `dft_planes`, `ntff_data` | [Results & Observables](https://remilab.ai/rfx/api/results/#forwardresult) |
| S-parameter results | `S` or `s_params` indexed `[receiver, driven, freq]` | [Results & Observables](https://remilab.ai/rfx/api/results/#s-parameter-results) |

Before you trust a spectrum, check `result.settling_db` (below about −40 dB).
For what is supported, limited or refused, see
[Support Boundaries](https://remilab.ai/rfx/support/).