# Python API map

The top-level `fdtdx` namespace re-exports the principal public API. This page emphasizes the paths exercised by the current examples; specialized parameter transforms, GDS helpers, and field-projection detectors are also available from the top level.

## Setup and execution

```{eval-rst}
.. autofunction:: fdtdx.auto_grid

.. autofunction:: fdtdx.auto_boundary_config

.. autofunction:: fdtdx.auto_config

.. autofunction:: fdtdx.auto_interface_aligned_grid

.. autofunction:: fdtdx.auto_pml_layers

.. autofunction:: fdtdx.place_objects

.. autofunction:: fdtdx.apply_params

.. autofunction:: fdtdx.run_fdtd
```

## Configuration and grid

```{eval-rst}
.. autoclass:: fdtdx.SimulationConfig
   :members: courant_number, time_step_duration, time_steps_total, has_symmetry

.. autoclass:: fdtdx.GradientConfig

.. autoclass:: fdtdx.UniformGrid

.. autoclass:: fdtdx.QuasiUniformGrid

.. autoclass:: fdtdx.RectilinearGrid
```

## Scene and materials

| API | Role |
|---|---|
| `SimulationVolume` | defines the finite physical domain |
| `Material` | permittivity, permeability, conductivity, and dispersion |
| `UniformMaterialObject` | axis-aligned material region |
| `Cylinder`, `Sphere` | curved primitives with optional subpixel smoothing |
| `ExtrudedPolygon` | extruded 2D polygon; useful for PIC geometry |
| `Device` | parameterized material region for inverse design |
| `BoundaryConfig` | per-face boundary policy |

```{eval-rst}
.. autoclass:: fdtdx.Material

.. autoclass:: fdtdx.SimulationVolume

.. autoclass:: fdtdx.UniformMaterialObject

.. autoclass:: fdtdx.ExtrudedPolygon
```

## Sources

All sources carry a `WaveCharacter`, direction/polarization information where applicable, a temporal profile, and placement inherited from `SimulationObject`.

| API | Spatial model |
|---|---|
| `PointDipoleSource` | local electric dipole |
| `UniformPlaneSource` | finite uniform linearly polarized plane |
| `GaussianPlaneSource` | finite Gaussian beam |
| `ModePlaneSource` | eigenmode on a cross-section |
| `TFSFPlaneSourceRegion` | total-field/scattered-field box |

```{eval-rst}
.. autoclass:: fdtdx.WaveCharacter
   :members: get_frequency, get_period, get_wavelength

.. autoclass:: fdtdx.UniformPlaneSource

.. autoclass:: fdtdx.ModePlaneSource
```

Temporal profiles are `SingleFrequencyProfile`, `GaussianPulseProfile`, and `CustomTimeSignalProfile`.

## Inverse design

```{eval-rst}
.. autoclass:: fdtdx.TopologyOptimizerConfig

.. autoclass:: fdtdx.TopologyOptimizationResult

.. autofunction:: fdtdx.optimize_topology

.. autofunction:: fdtdx.conic_filter

.. autofunction:: fdtdx.tanh_projection

.. autofunction:: fdtdx.erosion_dilation_penalty

.. autofunction:: fdtdx.d4_symmetrize

.. autofunction:: fdtdx.binary_density

.. autoclass:: fdtdx.LevelSetBoundary2D
   :members: from_density, initial_parameters, boundary_window, decode, interface_normal, preserves_topology, rebase

.. autofunction:: fdtdx.boundary_topology_signature

.. autofunction:: fdtdx.topology_safe_boundary_step

.. autofunction:: fdtdx.fixed_frequency_cavity_ldos

.. autofunction:: fdtdx.initialize_planned_recorder
```

## Detectors

| API | Primary result |
|---|---|
| `FieldDetector` | selected field components over a region |
| `EnergyDetector` | electromagnetic energy history |
| `PhasorDetector` | complex fields at requested frequencies |
| `PoyntingFluxDetector` | integrated time-domain flux |
| `PhasorPoyntingFluxDetector` | frequency-domain flux |
| `ModeOverlapDetector` | complex amplitude in an eigenmode |
| `ClosedSurfacePoyntingFluxDetector` | net flux through a volume |

```{eval-rst}
.. autoclass:: fdtdx.PhasorDetector

.. autoclass:: fdtdx.PhasorPoyntingFluxDetector

.. autoclass:: fdtdx.ModeOverlapDetector
```

## Modes, ports, and metrics

```{eval-rst}
.. autofunction:: fdtdx.compute_mode

.. autofunction:: fdtdx.calculate_sparam

.. autofunction:: fdtdx.calculate_sparams

.. autofunction:: fdtdx.compute_energy

.. autofunction:: fdtdx.compute_poynting_flux
```

## Serialization and visualization

Use `export_json`/`import_from_json` for the semantic scene, `export_vti` or `export_vtr` for VTK-compatible volume output, and `plot_setup`, `plot_material`, or `plot_field_slice` for local inspection. See [output and diagnostics](output.md).

```{admonition} Stability contract
:class: note

The upstream project is pre-1.0. These docs track the checked-out fork and use tested examples as the strongest compatibility contract. Pin a commit for production research and record it with results.
```