[docs] expand API and derivation docs

README.md

@@ -94,6 +94,59 @@ python3 -m pytest -rsxX | tee test_results.txt
 
 ## Use
 
-See `examples/` for some simple examples; you may need additional
-packages such as [gridlock](https://mpxd.net/code/jan/gridlock)
-to run the examples.
+`meanas` is organized around a few core workflows:
+
+- `meanas.fdfd`: frequency-domain wave equations, sparse operators, SCPML, and
+  iterative solves for driven problems.
+- `meanas.fdfd.waveguide_2d` / `meanas.fdfd.waveguide_3d`: waveguide mode
+  solvers, mode-source construction, and overlap windows for port-based
+  excitation and analysis.
+- `meanas.fdtd`: Yee-step updates, CPML boundaries, flux/energy accounting, and
+  on-the-fly phasor extraction for comparing time-domain runs against FDFD.
+- `meanas.fdmath`: low-level finite-difference operators, vectorization helpers,
+  and derivations shared by the FDTD and FDFD layers.
+
+The most mature user-facing workflows are:
+
+1. Build an FDFD operator or waveguide port source, then solve a driven
+   frequency-domain problem.
+2. Run an FDTD simulation, extract one or more frequency-domain phasors with
+   `meanas.fdtd.accumulate_phasor(...)`, and compare those phasors against an
+   FDFD reference on the same Yee grid.
+
+Tracked examples under `examples/` are the intended starting points:
+
+- `examples/fdtd.py`: broadband FDTD pulse excitation, phasor extraction, and a
+  residual check against the matching FDFD operator.
+- `examples/waveguide.py`: waveguide mode solving, unidirectional mode-source
+  construction, overlap readout, and FDTD/FDFD comparison on a guided structure.
+- `examples/fdfd.py`: direct frequency-domain waveguide excitation and overlap /
+  Poynting analysis without a time-domain run.
+
+Several examples rely on optional packages such as
+[gridlock](https://mpxd.net/code/jan/gridlock).
+
+### Frequency-domain waveguide workflow
+
+For a structure with a constant cross-section in one direction:
+
+1. Build `dxes` and the diagonal `epsilon` / `mu` distributions on the Yee grid.
+2. Solve the port mode with `meanas.fdfd.waveguide_3d.solve_mode(...)`.
+3. Build a unidirectional source with `compute_source(...)`.
+4. Build a matching overlap window with `compute_overlap_e(...)`.
+5. Solve the full FDFD problem and project the result onto the overlap window or
+   evaluate plane flux with `meanas.fdfd.functional.poynting_e_cross_h(...)`.
+
+### Time-domain phasor workflow
+
+For a broadband or continuous-wave FDTD run:
+
+1. Advance the fields with `meanas.fdtd.maxwell_e/maxwell_h` or
+   `updates_with_cpml(...)`.
+2. Inject electric current using the same sign convention used throughout the
+   examples and library: `E -= dt * J / epsilon`.
+3. Accumulate the desired phasor with `accumulate_phasor(...)` or the Yee-aware
+   wrappers `accumulate_phasor_e/h/j(...)`.
+4. Build the matching FDFD operator on the stretched `dxes` if CPML/SCPML is
+   part of the simulation, and compare the extracted phasor to the FDFD field or
+   residual.