meanas/docs/index.md

# meanas

`meanas` is a Python package for finite-difference electromagnetic simulation.
It combines:

- `meanas.fdfd` for frequency-domain operators, sources, waveguide modes, and SCPML
- `meanas.fdtd` for Yee-grid timestepping, CPML, energy/flux accounting, and phasor extraction
- `meanas.fdmath` for the shared discrete operators and derivations underneath both solvers

This documentation is built directly from the package docstrings. The API pages
are the source of truth for the mathematical derivations and calling
conventions.

## Examples and API Map

For most users, the tracked examples under `examples/` are the right entry
point. They show the intended combinations of tools for solving complete
problems.

Relevant starting examples:

- `examples/fdtd.py` for broadband pulse excitation and phasor extraction
- `examples/waveguide.py` for guided phasor-domain FDTD/FDFD comparison
- `examples/waveguide_real.py` for real-valued continuous-wave FDTD compared
  against real fields reconstructed from an FDFD solution, including guided-core,
  mode-weighted, and guided-mode / residual comparisons
- `examples/eme.py` for straight-interface mode matching / EME and modal
  scattering between two nearby waveguide cross-sections
- `examples/eme_bend.py` for straight-to-bent mode matching with cylindrical
  bend modes and a cascaded bend-network example
- `examples/fdfd.py` for direct frequency-domain waveguide excitation

For solver equivalence, prefer the phasor-based examples first. They compare
the extracted `+\omega` content of the FDTD run directly against the FDFD
solution and are the main accuracy benchmarks in the test suite.

`examples/waveguide_real.py` answers a different, stricter question: how well a
late raw real snapshot matches `Re(E_\omega e^{i\omega t})` on a monitor plane.
That diagnostic is useful, but it also includes orthogonal residual structure
that the phasor comparison intentionally filters out.

The API pages are better read as a toolbox map and derivation reference:

- Use the [FDTD API](api/fdtd.md) for time-domain stepping, CPML, phasor
  extraction, and real-field reconstruction from FDFD phasors.
- Use the [FDFD API](api/fdfd.md) for driven frequency-domain solves and sparse
  operator algebra.
- Use the [Waveguide API](api/waveguides.md) for mode solving, port sources,
  and overlap windows.
- Use the [fdmath API](api/fdmath.md) for the lower-level finite-difference
  operators and the shared discrete derivations underneath both solvers.

## Build outputs

The docs build generates two HTML views from the same source:

- a normal multi-page site
- a print-oriented combined page under `site/print_page/`

If `htmlark` is installed, `./make_docs.sh` also writes a fully inlined
`site/standalone.html`.