Compare commits

...
Author SHA1 Message Date
Forgejo Actions
c8615f6989 [docs] describe corrected FDFD solver and modal conventions 2026-10-28 19:03:37 -07:00
Forgejo Actions
4452dad609 [waveguide] correct modal reconstruction and calibrate full port bases 2026-10-28 19:03:37 -07:00
Forgejo Actions
112d88cac1 [farfield] align Fourier projection with outgoing wave convention 2026-10-28 19:03:29 -07:00
Forgejo Actions
cde834582d [fdfd] report solver failures and enforce conductor constraints 2026-10-28 19:03:24 -07:00
Forgejo Actions
4f75d63842 [tests] verify hybrid mode signs against matched CPML scattering references 2026-10-28 18:30:42 -07:00
Forgejo Actions
89c8ad0318 [bloch] solve transverse magnetic flux with a consistent energy metric 2026-10-28 18:29:21 -07:00
Forgejo Actions
be574d1a5b [farfield] preserve centered geometry and physical Fourier normalization 2026-10-28 18:14:22 -07:00
Forgejo Actions
b52ee4f622 [fdfd] correct backward mode signs, graded sensitivities, and flux precision 2026-10-28 18:14:22 -07:00
Forgejo Actions
b9aa06355b [fdmath] widen curl calculations and sparse reciprocals before arithmetic 2026-10-28 18:00:34 -07:00
Forgejo Actions
34075a7456 [docs] correct Yee calculus, source polarity, and phasor conventions 2026-10-28 17:49:32 -07:00
Forgejo Actions
247e3b0f73 [fdmath] fix dtype promotion, array-like unvectorization, and mirror bounds 2026-10-28 17:47:25 -07:00
Forgejo Actions
282ed2c38b [fdmath] correct Gridlock Yee spacing order
Use center-to-center intervals for forward E derivatives and base-cell widths for backward H derivatives in the Gridlock examples. Document the distinction from meshes defined directly by forward intervals and fix the random fixture's backward averaging direction.

Add coordinate-derivative regression coverage for graded periodic and nonperiodic Gridlock meshes using both functional and sparse operators.

Validation: 1689 tests passed, 586 skipped; no new Ruff findings in changed Python files.
2026-10-28 17:32:21 -07:00
Forgejo Actions
a08e9ce71b [eme] characterize orientation bias under modal truncation
Compare mixed and Galerkin testing against exact polarization/Fresnel interfaces and independent driven FDFD solves. Show complete-basis recovery, omitted-channel power, and the limits of longitudinal refinement, orientation averaging, and Euclidean least squares. Keep the default formulation unchanged and document its approximation limits.

Validation: 1689 tests passed, 584 skipped; Ruff and documentation build passed.
2026-10-18 23:21:29 -07:00
Forgejo Actions
7b01ddd789 [fdtd] reject zero and invalid CPML attenuation
Require a finite negative ln_R_per_layer before coefficient evaluation. Document None entries as the supported way to disable a face, and cover zero, signed zero, positive, and nonfinite targets with and without frequency shift.

Validation: 209 focused tests passed; Ruff passed.
2026-10-18 23:10:36 -07:00
Forgejo Actions
553cdf948c [scpml] share face construction between grid builders
Delegate uniform-grid PML faces to stretch_with_scpml, using physical-thickness scaling and electric-center/magnetic-edge samples. Cover disabled axes, touching faces, real profiles, and final stretch caps.

Validation: 200 focused tests passed; Ruff passed.
2026-10-18 23:09:02 -07:00
Forgejo Actions
7e407dd1ac [docs] document scattering conventions and frozen-basis workflows
Update examples for sampled-interface tapers, explicit physical CPML spacing, copied SCPML widths, and the consolidated complex mode solver. Document breaking API changes, overlap measures, and PML convergence.
2026-10-18 23:07:53 -07:00
Forgejo Actions
153536ee91 [numerics] fix modal scattering and Yee-grid updates
Integrate targeted complex mode bases, solve both interface incidences together, and cascade sampled taper S matrices. Add frozen-basis evaluation, explicit overlap measures, reproducible starts, shared 2D-to-3D conversion, PML controls, and lower-allocation derivatives.

Validation: 1629 tests passed, 584 skipped.
2026-10-18 23:07:47 -07:00
Forgejo Actions
0e89fe0460 [fdfd.waveguide_2d_complex] add 2d complex modesolver 2026-07-14 21:15:45 -07:00
Forgejo Actions
e851e25568 [examples] fix eme bend example 2026-07-14 00:21:34 -07:00
Forgejo Actions
37ed9d10bc [fdfd.waveguide_3d] add FDFD-based S-matrix solve 2026-07-14 00:21:12 -07:00
Forgejo Actions
f3500e497b [waveguide_2d] improve test coverage 2026-06-25 18:57:17 -07:00
Forgejo Actions
cd3deb87fb [waveguide_cyl] fix stray arg and tests 2026-06-25 12:05:25 -07:00
Forgejo Actions
c249e78cd9 [waveugide_cyl] adjust radius calculation 2026-06-25 12:01:36 -07:00
Forgejo Actions
bb4322ded9 [waveguide_cyl] adjust operators to match waveguide_2d in the large-radius limit 2026-06-25 12:00:48 -07:00
Forgejo Actions
f1b1efdb39 [waveguide_cyl] enable mu 2026-06-25 11:52:42 -07:00
Forgejo Actions
444ae49a74 [fdfd.eme] enable using leaky modes 2026-05-04 19:03:30 -07:00
Forgejo Actions
7e6363ea04 [fdfd.eme] Add semi-analytic taper approximation 2026-05-04 18:41:38 -07:00
Forgejo Actions
bf99f35f9b bump version to v0.12 2026-04-22 21:11:05 -07:00
Forgejo Actions
39291a8314 [eme] add analytic tests 2026-04-22 21:10:18 -07:00
Forgejo Actions
061c3f2e90 [_normalized_fields] remove unused args 2026-04-22 21:09:59 -07:00
Forgejo Actions
35fc67faa3 [compute_overlap_e] remove omega arg (unused) 2026-04-22 21:08:12 -07:00
Forgejo Actions
a1568a6f16 ignore some lint 2026-04-21 21:20:34 -07:00
Forgejo Actions
c6c9159b13 type hints and lint 2026-04-21 21:13:34 -07:00
Forgejo Actions
eec3fc28a7 [docs] update colors 2026-04-21 19:51:57 -07:00
Forgejo Actions
010da1ccf5 [tests] add some slow tests 2026-04-21 19:40:49 -07:00
Forgejo Actions
1a2c6ab524 [EME] add more docs and tests 2026-04-21 19:40:32 -07:00
Forgejo Actions
8b67696d7f bump version to v0.11 2026-04-20 11:03:18 -07:00
Forgejo Actions
f8ad0250d1 [eme / examples] add EME examples 2026-04-20 10:15:25 -07:00
Forgejo Actions
9a0c693848 [docs] docs dark mode 2026-04-19 20:22:36 -07:00
Forgejo Actions
bb920b8e33 [tests / fdtd.pml] add pml test 2026-04-19 17:30:04 -07:00
Forgejo Actions
ff278e6fa1 [docs] more docs cleanup 2026-04-19 16:57:22 -07:00
Forgejo Actions
dc92d4a79d [docs] clean up latex leaking into docs site 2026-04-19 16:40:05 -07:00
Forgejo Actions
40efe7a450 [docs] clarify FDFD-to-FDTD field reconstruction 2026-04-19 16:15:06 -07:00
Forgejo Actions
e50637dc1c [waveguide_real / phasor] more work towards real-FDTD to FDFD equivalence 2026-04-19 15:47:00 -07:00
Forgejo Actions
f7aa21a42a [examples] add waveguide_real 2026-04-19 14:43:49 -07:00
Forgejo Actions
3e4aee1197 [fdtd.phasor] add phasor-to-real helpers 2026-04-19 14:43:37 -07:00
Forgejo Actions
4b8a462df7 [phasor] add real-valued scaling 2026-04-19 12:34:28 -07:00
Forgejo Actions
c0b41752e1 [phasor] add temporal_phasor and temporal_phasor_scale 2026-04-19 10:57:10 -07:00
Forgejo Actions
318c43d62d [docs] high level doc updates 2026-04-19 00:50:22 -07:00
Forgejo Actions
6f29dd89a8 Update dependency groups 2026-04-19 00:41:07 -07:00
bedb338ac9 [docs] add push_with_docs script 2026-04-19 00:19:57 -07:00
a82eb5858a [docs] switch generated docs to MkDocs 2026-04-18 23:55:40 -07:00
5e95d66a7e [docs] expand API and derivation docs 2026-04-18 23:55:40 -07:00
0568e1ba50 [tests] add a waveguide scattering test 2026-04-18 23:55:40 -07:00
d4c1082ca9 [tests] FDFD/FDTD equivalence test 2026-04-18 23:55:40 -07:00
d99ef96c96 [fdtd.phasor] add accumulate_phasor* 2026-04-18 23:55:40 -07:00
8cdcd08ba0 [tests] refactor tests 2026-04-18 23:55:40 -07:00
267d161769 [tests] more test coverage 2026-04-18 23:55:40 -07:00
0afe2297b0 [fdfd.operators] fix eh_full for non-None mu 2026-04-18 23:55:40 -07:00
0ff23542ac [tests] more tests 2026-04-18 23:55:40 -07:00
9ac24892d6 [tests] test more 2D waveguide results 2026-04-18 23:55:40 -07:00
f3d13e1486 [fdfd.eme] do a better job of enforcing no gain 2026-04-18 23:55:40 -07:00
e6756742be [bloch] add some more tests and clean up solves 2026-04-18 23:55:40 -07:00
87bb3af3f9 [fdfd] minor fixes and more tests 2026-04-18 23:55:40 -07:00
07b16ad86a [bloch] fixup some vectorization and add tests 2026-04-18 23:55:40 -07:00
f35b334100 [fdfd.waveguide_3d] improve handling of out-of-bounds overlap_e windows 2026-04-18 23:55:40 -07:00
593098bf8f [fdfd.functional] fix handling of mu in e_full and m2j sign 2026-04-18 23:55:40 -07:00
38a5c1a9aa [tests] add some more tests around numerical self-consistency 2026-04-18 23:49:53 -07:00
bc55baf4a6 [tests] add coverage and test options 2026-04-18 23:49:53 -07:00
7eea919f94 [fdtd.boundaries] use tuples for indexing 2026-04-18 23:49:53 -07:00
74bebea837 [fdfd.farfield] fix kys calculation and some near-0 behavior 2026-04-18 23:49:53 -07:00
8d49901b58 [fdtd.misc] fix some packets/pulses 2026-04-18 23:49:53 -07:00
9d419aa3ea [fdtd.misc.gaussian_beam] avoid some nans at w0 near 0 2026-04-18 23:05:08 -07:00
4913211883 [fdfd.eme] fix abcd array construction 2026-04-18 23:05:07 -07:00
f5af0fef55 [waveguide_3d] fixup and doc update 2026-04-18 23:04:44 -07:00
7e8ff23356 misc example updates 2026-04-18 23:02:10 -07:00
jan
be647658d3 [eigensolvers] Increase number of lanczos vectors (ncv) based on number of requested eigenvalues 2025-12-10 23:07:28 -08:00
jan
c46bed8298 update optional deps 2025-12-10 21:15:38 -08:00
jan
fb3bef23bf [examples/fdfd] split fdfd example into two files 2025-12-10 21:14:34 -08:00
jan
d4f1008c5c [fdfd.waveguide*] comment updates 2025-12-10 19:45:26 -08:00
jan
b486fa325b Rework field types, use sparse arrays instead of matrices, rework eme arg naming, improve type annotations and linter cleanup 2025-12-10 02:14:20 -08:00
jan
b7ad5dea2b [fdfd.bloch] drop unnecessary noqas 2025-12-10 02:05:24 -08:00
jan
684b891e0f [waveguide_3d] clean up docstrings 2025-12-09 22:56:16 -08:00
jan
4a80ca8b12 [waveguide_cyl] silence some debug prints 2025-12-09 22:55:52 -08:00
e3169b9e20 bump version to v0.10 2025-04-16 22:20:16 -07:00
35ecbad15e remove old lint 2025-04-16 22:19:21 -07:00
43e01a814d examples will use new gridlock 2025-04-16 22:19:14 -07:00
9eb0e28bcb [meanas.fdtd.misc] add basic pulse and beam shapes 2025-03-12 23:40:00 -07:00
c858b20d47 Bump numpy dependency to >=2.0 2025-03-12 23:19:20 -07:00
777ecbc024 [fdfd.solvers.generic] add option to pass a guess solution 2025-02-05 00:13:46 -08:00
c4f8749941 [fdfd.solvers.generic] report residual scaled to b 2025-02-05 00:09:25 -08:00
cd5cc9eb83 [fdfd.eme] Add basic (WIP) eignmode expansion functionality 2025-01-28 22:07:19 -08:00
99e8d32eb1 [waveguide_cyl] frequency should be real 2025-01-28 22:06:32 -08:00
1cb0cb2e4f [fdfd.waveguide_cyl] Improve documentation and add auxiliary functions (e.g. exy2exyz) 2025-01-28 21:59:59 -08:00
234e8d7ac3 delete h version of operator in comment 2025-01-28 19:55:09 -08:00
83f4d87ad8 [fdfd.waveguide*] misc fixes 2025-01-28 19:54:48 -08:00
1987ee473a improve type annotations 2025-01-28 19:54:13 -08:00
4afc6cf62e cleanup latex 2025-01-14 22:34:52 -08:00
53d5812b4a [waveguide_2d] Remove \gamma from docs in favor of just using \beta 2025-01-14 22:34:35 -08:00
651e255704 add derivation for exy2e() 2025-01-14 22:15:18 -08:00
71c2bbfada Add linear_wavenumbers() for calculating 1/distance wavenumbers 2025-01-14 22:02:43 -08:00
6a56921c12 Return angular wavenumbers, and remove r0 arg (leaving only rmin) 2025-01-14 22:02:19 -08:00
006833acf2 add logger 2025-01-14 22:01:29 -08:00
155f30068f add inner_product() and use it for energy calculation 2025-01-14 22:01:10 -08:00
7987dc796f mode numbers may be any sequence 2025-01-14 22:00:21 -08:00
829007c672 Only keep the real part of the energy 2025-01-14 22:00:08 -08:00
659566750f update for new gridlock syntax 2025-01-14 21:59:46 -08:00
76701f593c Check overlap only on forward-propagating part of mode 2025-01-14 21:59:37 -08:00
4e3a163522 indentation & style 2025-01-14 21:59:12 -08:00
50f92e1cc8 [vectorization] add nvdim arg allowing unvec() on 2D fields 2025-01-14 21:58:46 -08:00
b3c2fd391b [waveguide_2d] Return modes sorted by wavenumber (descending) 2025-01-14 21:57:54 -08:00
c543868c0b check for sign=0 case 2025-01-14 21:51:32 -08:00
e54735d9c6 Fix cylindrical waveguide module
- Properly account for rmin vs r0
- Change return values to match waveguide_2d
- Change operator definition to look more like waveguide_2d

remaining TODO:
- Fix docs
- Further consolidate operators vs waveguide_2d
- Figure out E/H field conversions
2025-01-07 00:10:15 -08:00
4f2433320d fix zip(strict=True) for 2D problems 2025-01-07 00:05:19 -08:00
47415a0beb Return list-of-vectors from waveguide mode solve 2025-01-07 00:04:53 -08:00
e459b5e61f clean up comments and some types 2025-01-07 00:04:01 -08:00
36431cd0e4 enable numpy 2.0 and recent scipy 2024-07-29 02:25:16 -07:00
739e96df3d avoid a copy 2024-07-29 00:34:17 -07:00
63e7cb949f explicitly specify closed variables 2024-07-29 00:33:58 -07:00
c53a3c4d84 unused var 2024-07-29 00:33:43 -07:00
5dd9994e76 improve some type annotations 2024-07-29 00:32:52 -07:00
1021768e30 simplify indentation 2024-07-29 00:32:20 -07:00
95e923d7b7 improve error handling 2024-07-29 00:32:03 -07:00
3f8802cb5f use strict zip 2024-07-29 00:31:44 -07:00
43bb0ba379 use generators where applicable 2024-07-29 00:31:16 -07:00
e19968bb9f linter-related test updates 2024-07-29 00:30:00 -07:00
43f038d761 modernize type annotations 2024-07-29 00:29:39 -07:00
d5fca741d1 remove type:ignore from scipy imports (done at pyproject.toml level) 2024-07-29 00:27:59 -07:00
ca94ad1b25 use path.open() 2024-07-29 00:23:08 -07:00
10f26c12b4 add ruff and mypy configs 2024-07-29 00:22:54 -07:00
ee51c7db49 improve type annotations 2024-07-28 23:23:47 -07:00
36bea6a593 drop unused import 2024-07-28 23:23:21 -07:00
b16b35d84a use new numpy.random.Generator approach 2024-07-28 23:23:11 -07:00
6f3ae5a64f explicitly re-export some names 2024-07-28 23:22:21 -07:00
99c22d572f bump numpy version 2024-07-28 23:21:59 -07:00
2f00baf0c6 fixup cylindrical wg example 2024-07-18 19:31:17 -07:00
2712d96f2a add notes on references 2024-07-18 19:31:17 -07:00
dc3e733e7f flake8 fixes 2024-07-18 19:31:17 -07:00
95e3f71b40 use f-strings in place of .format() 2024-07-18 19:31:17 -07:00
639f88bba8 add sensitivity calculation 2024-07-18 19:31:17 -07:00
ccfd4fbf04 use parentheses instead of backslash 2024-07-15 16:32:48 -07:00
77715da8b4 Use raw strings to avoid double backslashes 2024-07-15 16:32:31 -07:00
2d48858973 drop duplicate import 2024-07-15 16:10:51 -07:00
8c49710861 black bg for tex svgs 2024-07-14 22:09:16 -07:00
22565328ab use parens in place of backslashes 2024-07-14 22:08:52 -07:00
4c8a07bf20 Use raw strings to eliminate repeated backslashes 2024-07-14 22:08:30 -07:00
128 changed files with 17996 additions and 3934 deletions

4
.gitignore vendored
View file

@ -54,6 +54,10 @@ coverage.xml
# documentation
doc/
site/
_doc_mathimg/
doc.md
doc.htex
# PyBuilder
target/

158
README.md
View file

@ -49,13 +49,28 @@ linear systems, ideally with double precision.
**Requirements:**
* python >=3.11
* python >=3.12
* numpy
* scipy
Install from PyPI with pip:
```bash
pip3 install meanas
```
Optional extras:
- `meanas[test]`: pytest and coverage
- `meanas[docs]`: MkDocs-based documentation toolchain
- `meanas[examples]`: optional runtime dependencies used by the tracked examples
- `meanas[dev]`: the union of `test`, `docs`, and `examples`, plus local lint/docs-publish helpers
Examples:
```bash
pip3 install 'meanas[test]'
pip3 install 'meanas[docs]'
pip3 install 'meanas[examples]'
pip3 install 'meanas[dev]'
```
@ -80,9 +95,13 @@ source my_venv/bin/activate
# Install in-place (-e, editable) from ./meanas, including development dependencies ([dev])
pip3 install --user -e './meanas[dev]'
# Run tests
# Fast local iteration: excludes slower 3D/integration/example-smoke checks
cd meanas
python3 -m pytest -rsxX | tee test_results.txt
python3 -m pytest -q -m "not complete"
# Complete pre-commit confidence run: includes the slower integration tests and
# tracked example smoke tests
python3 -m pytest -q | tee test_results.txt
```
#### See also:
@ -94,6 +113,133 @@ 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 a collection of finite-difference electromagnetics tools:
- `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, including targeted complex bases from the default half-sized
beta-squared or explicit signed-beta formulations, transpose-left and
Lorentz-dual projection fields on a shared field-array axis, separately
returned PML-mode diagnostics, overlap-based tracking,
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.
For most users, the tracked examples under `examples/` are the right entry
point. The library API is primarily a toolbox; the module docstrings and API
pages are there to document the mathematical conventions and derivations behind
those tools.
## Documentation
API and workflow docs are generated from the package docstrings with
[MkDocs](https://www.mkdocs.org/), [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/),
and [mkdocstrings](https://mkdocstrings.github.io/).
Install the docs toolchain with:
```bash
pip3 install -e './meanas[docs]'
```
Then build the docs site with:
```bash
./make_docs.sh
```
This produces:
- a normal multi-page site under `site/`
- a combined printable single-page HTML site under `site/print_page/`
- an optional fully inlined `site/standalone.html` when `htmlark` is available
The docs build uses a local MathJax bundle vendored under `docs/assets/`, so
the rendered HTML does not rely on external services for equation rendering.
The tracked examples under `examples/` are the intended entry points for users:
- `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/waveguide_real.py`: real-valued continuous-wave FDTD on a straight
guide, with late-time monitor slices, guided-core windows, and mode-weighted
errors compared directly against real fields reconstructed from the matching
FDFD solution, plus a guided-mode / orthogonal-residual split.
- `examples/eme.py`: straight-interface mode matching / EME, including port
mode solving, interface scattering, and modal field visualization.
- `examples/eme_bend.py`: straight-to-bent waveguide mode matching with
cylindrical bend modes, interface scattering, and a cascaded bend-network
example built with `scikit-rf`.
- `examples/eme_taper_cmt.py`: sampled-interface EME with stable S cascading for a
continuously varying rib-waveguide taper.
- `examples/eme_taper_pml_modes.py`: targeted complex/PML mode solving,
tracking, and construction of EME taper sections.
- `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.
This is the primary FDTD/FDFD equivalence workflow. The phasor extraction step
filters the time-domain run down to the guided `+\omega` content that FDFD
solves for directly, so it is the cleanest apples-to-apples comparison.
### Real-field reconstruction workflow
For a continuous-wave real-valued FDTD run:
1. Build the analytic source phasor for the structure, for example with
`waveguide_3d.compute_source(...)`.
2. Run the real-valued FDTD simulation using the real part of that source.
3. Solve the matching FDFD problem from the analytic source phasor on the
stretched `dxes`.
4. Reconstruct late real `E/H/J` snapshots with
`reconstruct_real_e/h/j(...)` and compare those directly against the
real-valued FDTD fields, ideally on a monitor window or mode-weighted norm
centered on the guided field rather than on the full transverse plane. When
needed, split the monitor field into guided-mode and orthogonal residual
pieces to see whether the remaining mismatch is actually in the mode or in
weak nonguided tails.
This is a stricter diagnostic, not the primary equivalence benchmark. A raw
monitor slice contains both the guided field and the remaining orthogonal
content on that plane,
$$ E_{\text{monitor}} = E_{\text{guided}} + E_{\text{residual}} , $$
so its full-plane instantaneous error is naturally noisier than the extracted
phasor comparison even when the underlying guided `+\omega` content matches
well.
`examples/waveguide_real.py` is the reference implementation of this workflow.

3
docs/api/eigensolvers.md Normal file
View file

@ -0,0 +1,3 @@
# eigensolvers
::: meanas.eigensolvers

77
docs/api/fdfd.md Normal file
View file

@ -0,0 +1,77 @@
# fdfd
::: meanas.fdfd
## Core operator layers
::: meanas.fdfd.functional
::: meanas.fdfd.operators
::: meanas.fdfd.solvers
::: meanas.fdfd.scpml
::: meanas.fdfd.farfield
## Bloch magnetic materials
Bloch state vectors store the transverse Fourier coefficients of magnetic flux
`B = mu * H`. They equal `H` when permeability is omitted. Pass the same `mu`
to `bloch.hmn_2_hxyz(...)` and `bloch.hmn_2_exyz(...)` when converting solved
vectors to fields. The eigensolver uses the projected `mu**-1` energy metric
for finite positive real permeability, including anisotropic and spatially
varying profiles. Its preconditioner remains finite at the Gamma point.
## Far-field normalization
The near-to-far transform includes the cell area `dx * dy`, so normalized
far-field amplitudes describe a Fourier integral and converge under spatial
refinement. This changes amplitudes previously returned as unweighted FFT sums.
The inverse applies the matching Fourier quadrature and returns spacings for
the requested output shape. Both transforms center their origins at index
`size // 2`; padding and cropping preserve that sample. The inverse does not
modify input spectra.
Transforms use the library's `exp(+i omega t)` time convention: outgoing plane
waves vary as `exp(-i k dot r)`, so the angular projection uses a positive
Fourier phase. The inverse uses a negative phase. Far-field vector pairs are
ordered as polar and azimuthal components; near-field pairs are Cartesian.
## Solver and port calibration
The default QMR wrapper raises `RuntimeError` on breakdown or failure to
converge. PEC rows impose zero electric fields with unit diagonal entries;
`solvers.generic` zeroes the corresponding source and initial-guess entries.
H-only and EH operators impose analogous constraints for PMC locations.
FDFD port calibration uses the complete incoming-amplitude matrix from all
excitations, solving `S @ incoming_amplitudes = raw_outgoing_amplitudes`.
Diagnostics include these matrices and the incoming/outgoing flux Gram
matrices. Guided powers retain cross terms between nonorthogonal modes.
Lossless modes at or above the propagation-grid band edge require a finer
mesh for power normalization. Lorentz-normalized evanescent modes use the
decaying spatial branch. Expansion on graded grids uses each electric
component's own Yee intervals.
## SCPML conventions
`stretch_with_scpml` now uses `-1` for the low-index face and `+1` for the
high-index face, matching CPML and propagation conventions. It returns copied
widths by default; pass `copy=False` to request mutation explicitly.
Both SCPML builders accept `kappa_function(depth)` for real stretching and
`max_imag_ratio` to limit the final dimensionless `abs(Im(s))/Re(s)`. Start a
mode-solver convergence study with `max_imag_ratio=1.0`: overly strong imaginary
stretching can produce above-light-line PML artifacts. The cap is not a general
spectral guarantee, and weaker absorption can increase boundary reflections.
Check domain size, PML thickness, strength, mode localization, and residuals.
The general scattering profile remains uncapped by default.
`uniform_grid_scpml` builds unit widths by applying `stretch_with_scpml` to
both faces of each enabled axis. Both builders divide imaginary grading by
physical layer thickness and sample electric widths at cell centers and
magnetic widths at cell edges. This corrects the uniform builder's previous
thickness-independent strength and reversed E/H sample offsets; retune existing
uniform-builder profiles using domain/PML convergence checks.

26
docs/api/fdmath.md Normal file
View file

@ -0,0 +1,26 @@
# fdmath
For Gridlock's default E-field Yee shifts, construct solver spacings as
`dxes = [grid.autoshifted_dxyz(), grid.dxyz]`. The forward E curl needs
distances between adjacent base-cell centers; the backward H curl needs
distances between adjacent upper cell edges. Reversing these two width families
introduces an error on graded grids that uniform grids hide.
If constructing the mesh directly from **forward derivative intervals** `d`,
with H samples at their midpoints, the backward intervals instead follow
`(d + numpy.roll(d, 1)) / 2` for periodic boundaries. These `d` arrays are
already center-to-center distances, whereas `grid.dxyz` contains base-cell
volume widths. Applying this averaging rule to `grid.dxyz` does not fix the
ordering error above.
::: meanas.fdmath
## Functional and sparse operators
::: meanas.fdmath.functional
::: meanas.fdmath.operators
::: meanas.fdmath.vectorization
::: meanas.fdmath.types

24
docs/api/fdtd.md Normal file
View file

@ -0,0 +1,24 @@
# fdtd
::: meanas.fdtd
## Core update and analysis helpers
::: meanas.fdtd.base
::: meanas.fdtd.pml
::: meanas.fdtd.boundaries
::: meanas.fdtd.energy
::: meanas.fdtd.phasor
CPML derivatives use electric widths for forward differences and magnetic
widths for backward differences. `cpml_params(..., dx=1.0)` specifies the uniform
physical cell width normal to a face; arbitrary nonuniform PML grading is not
implemented by this constructor. Scale the timestep consistently with the grid.
`ln_R_per_layer` must be finite and strictly negative. Zero attenuation raises
`ValueError`; disable individual CPML faces with `None` in the parameter table
passed to `updates_with_cpml`.

14
docs/api/index.md Normal file
View file

@ -0,0 +1,14 @@
# API Overview
The package is documented directly from its docstrings. The most useful entry
points are:
- [meanas](meanas.md): top-level package overview
- [eigensolvers](eigensolvers.md): generic eigenvalue utilities used by the mode solvers
- [fdfd](fdfd.md): frequency-domain operators, sources, PML, solvers, and far-field transforms
- [waveguides](waveguides.md): straight, cylindrical, and 3D waveguide mode helpers
- [fdtd](fdtd.md): timestepping, CPML, energy/flux helpers, and phasor extraction
- [fdmath](fdmath.md): shared discrete operators, vectorization helpers, and derivation background
The waveguide and FDTD pages are the best places to start if you want the
mathematical derivations rather than just the callable reference.

3
docs/api/meanas.md Normal file
View file

@ -0,0 +1,3 @@
# meanas
::: meanas

153
docs/api/waveguides.md Normal file
View file

@ -0,0 +1,153 @@
# waveguides
::: meanas.fdfd.waveguide_2d
::: meanas.fdfd.waveguide_3d
::: meanas.fdfd.waveguide_cyl
## Overlap measures and normalization
`waveguide_2d.inner_product(..., measure="physical", conj_h=True)` uses real
Yee widths for physical Poynting power. `measure="stretched"` keeps complex
widths for coordinate reaction. `lorentz_metric` and `lorentz_overlap` default
to the stretched measure. Use the same grid and measure when constructing and
using dual fields. A real overlap grid still defines a consistent constructed
dual basis, even when the eigenproblem uses a separate PML grid.
`normalized_fields_e/h(..., normalization="lorentz")` normalizes unconjugated
self-reaction to one. This fixes phase up to a sign and is distinct from unit
forward power, which remains the default. Zero-power or self-orthogonal modes
raise `ValueError`; open self-orthogonal modes require paired primal/dual
normalization through `ModeBasis`.
## Targeted and reproducible mode solving
For modes near an effective index guess, use `solve_modes_near` with
`target_wavenumbers=[omega * n_guess]`. It targets the electric beta-squared
operator at `(omega * n_guess)**2`; `solve_modes_near_beta` instead targets the
first-order signed-beta operator. Both use the LU shift-invert backend and
support `eigensolver_opts={"v0": starting_vector}`. Factorization cost and
memory depend on the grid, so this is not universally faster than indexed
solving. `solve_modes` keeps its global mode-number semantics and now accepts
`rng` or `v0` for reproducible initialization.
`waveguide_3d.mode_from_2d` accepts a supplied transverse electric eigenvector
and reuses field reconstruction, normalization, numerical-dispersion
correction, Yee staggering, rotation, and full-grid embedding without solving
an eigenproblem.
## Interface and sampled-taper scattering
All scattering matrices use outgoing rows and incoming columns, ordered
`[left, right]`:
```text
[b_left ] [R_left T_right_to_left] [a_left ]
[b_right] = [T_left_to_right R_right] [a_right]
```
`get_s` and `get_abcd` require explicit `dxes`. Mixed Petrov-Galerkin testing is
the default: left electric duals test H continuity, and right magnetic duals
test E continuity. Both incidence directions are solved together with full
projection matrices. Mixed scattering supports unequal mode counts.
`formulation="galerkin"` selects equal-count left testing of both equations.
Neither formulation silently clips transmission. The optional `force_nogain`
and `force_reciprocal` flags are numerical projections, not general physical
tests for arbitrary open or evanescent modal coordinates.
`get_taper_s` replaces finite-difference CMT with half propagation in the left
basis, a midpoint interface, and half propagation in the right basis for each
sampled interval. Redheffer composition avoids growing passive backward
transfer branches. Refine section sampling and modal/PML bases to establish
convergence. The ineffective `rtol`, `atol`, and `max_step` arguments have been
removed. The existing `eme_taper_cmt.py` example filename is retained.
```python
prepared = eme.prepare_taper(sections, dxes)
s_original = eme.evaluate_taper_s(prepared)
s_longer = eme.evaluate_taper_s(prepared, z_coords=prepared.z_coords * 1.2)
s_changed_beta = eme.evaluate_taper_s(
prepared, wavenumber_matrices=beta_matrices,
)
```
`PreparedTaper` owns read-only copies of phase-aligned interface data. Beta
matrix overrides have shape `(section, mode, mode)` in the original supplied
section bases; recorded basis transforms are applied automatically. Explicit
backward branches require backward beta overrides when forward beta is changed.
Evaluation performs no field overlaps or eigensolves. Length sweeps reuse the
sampled model; wavelength sweeps with reused fields are explicitly frozen-basis
approximations. Reprepare when fields, duals, grids, or formulations change.
`cascade_s(left, right, internal_modes=...)` connects spatially ordered S
matrices, including unequal external ports. Public `abcd_to_s` and `s_to_abcd`
use `[f_right, b_right] = ABCD @ [f_left, b_left]` and require equal port counts.
`get_taper_abcd` converts the stable S result; zero transmission or an
unrepresentable transfer matrix raises `LinAlgError`. Prefer S for long lossy
devices. Singular interface and cascade systems also raise contextual errors
rather than silently substituting pseudoinverses.
::: meanas.fdfd.eme
## Orientation bias under modal truncation
Mixed testing is a projected approximation: H continuity is tested on the left
and E continuity on the right. Swapping the ports changes the testing spaces
when the retained modal subspaces are incomplete. This effect survives checks
of reciprocity and unitarity.
A reproducible Maxwell counterexample is a uniform isotropic medium with two
degenerate linear polarizations. Keep one polarization on each port, rotated
so their overlap is `a=0.8`. There is no material interface: true reflection is
zero and transmission into the retained receiver is `a`. The other polarization
carries the remaining transmitted power, `1-a**2=0.36`.
| Calculation | R_left | R_right | T_left_to_right | T_right_to_left |
| --- | ---: | ---: | ---: | ---: |
| Exact full basis, then restrict ports | 0 | 0 | 0.8 | 0.8 |
| Truncated mixed | 0.219512 | -0.219512 | 0.975610 | 0.975610 |
| Swap ports, mixed, then reorder | -0.219512 | 0.219512 | 0.975610 | 0.975610 |
| Truncated left Galerkin | 0 | 0 | 1.25 | 0.8 |
| Euclidean E/H least squares | 0 | 0 | 0.8 | 0.8 |
An independent driven 3D FDFD solve with PML agrees with the exact reference
from either incidence direction: transmission is 0.8 within `1e-12`, with
reflection below `2e-8` in the test fixture. Keeping both polarizations makes
mixed testing match the exact complete scattering matrix and restores
port-relabeling covariance.
For the single retained polarization, mixed testing yields
`r=(1-a**2)/(1+a**2)` and `t=2*a/(1+a**2)`. The spurious reflection is quadratic
in a small angle between adjacent retained polarizations. However, longitudinal
refinement alone is insufficient: rotating a single retained vector through a
uniform degenerate medium makes the sampled chain approach artificial following
of that vector (`|T|` approaches 1), while the physical endpoint overlap remains
0.8. Keeping the complete degenerate block recovers the physical result at every
sampling density tested.
Two tempting corrections are insufficient. Averaging the two port orientations
cancels reflection in this example but leaves transmission at 0.975610. Plain
Euclidean E/H least squares gives the correct uniform-medium result, but is not
a general replacement. A second fixture uses exact degenerate modes of diagonal
positive epsilon/mu tensors, with electric scaling `(1,2)` on the left and
`(1,3)` on the right and a 30-degree polarization rotation on both ports. After
single-mode truncation, least squares has unequal directional transmissions
(approximately 0.850839 and 1.092163) and a maximum singular value of 1.104947.
The complete Fresnel solution is reciprocal and lossless.
The mixed default remains unchanged. Retain complete coupled/degenerate blocks
when the geometry can mix them, check modal-basis convergence as well as section
sampling, and compare against independent full-field results. Neither orientation
averaging nor gain/reciprocity postprocessing recovers omitted-channel physics.
Orientation discrepancy is a useful diagnostic, not a bound on transmission
error. These examples use real power-orthonormal propagating modes; for general
complex modes, the reciprocity constraint involves the modal orthogonality
matrix, as derived by [Svendsen, Haakestad, and Skaar](https://arxiv.org/abs/1301.2458).
Reproduce the analytic, full-basis, candidate-formulation, taper-refinement, and
driven-FDFD checks with:
```sh
OPENBLAS_NUM_THREADS=1 python -m pytest meanas/test/test_eme_orientation.py -q
```

1
docs/assets/vendor/mathjax/core.js vendored Normal file

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

1
docs/assets/vendor/mathjax/loader.js vendored Normal file

File diff suppressed because one or more lines are too long

View file

@ -0,0 +1,38 @@
{
"etag": "7ab8013dfc2c395304109fe189c1772ef87b366a",
"files": {
"core.js": 212262,
"loader.js": 16370,
"startup.js": 22870,
"input/tex-full.js": 270711,
"input/asciimath.js": 107690,
"input/mml.js": 13601,
"input/mml/entities.js": 32232,
"output/chtml.js": 211041,
"output/chtml/fonts/tex.js": 104359,
"output/chtml/fonts/woff-v2/MathJax_Zero.woff": 1368,
"output/chtml/fonts/woff-v2/MathJax_Vector-Regular.woff": 1136,
"output/chtml/fonts/woff-v2/MathJax_Vector-Bold.woff": 1116,
"output/chtml/fonts/woff-v2/MathJax_Typewriter-Regular.woff": 17604,
"output/chtml/fonts/woff-v2/MathJax_Size4-Regular.woff": 5148,
"output/chtml/fonts/woff-v2/MathJax_Size3-Regular.woff": 3244,
"output/chtml/fonts/woff-v2/MathJax_Size2-Regular.woff": 5464,
"output/chtml/fonts/woff-v2/MathJax_Size1-Regular.woff": 5792,
"output/chtml/fonts/woff-v2/MathJax_Script-Regular.woff": 11852,
"output/chtml/fonts/woff-v2/MathJax_SansSerif-Regular.woff": 12660,
"output/chtml/fonts/woff-v2/MathJax_SansSerif-Italic.woff": 14628,
"output/chtml/fonts/woff-v2/MathJax_SansSerif-Bold.woff": 15944,
"output/chtml/fonts/woff-v2/MathJax_Math-Regular.woff": 19288,
"output/chtml/fonts/woff-v2/MathJax_Math-Italic.woff": 19360,
"output/chtml/fonts/woff-v2/MathJax_Math-BoldItalic.woff": 19776,
"output/chtml/fonts/woff-v2/MathJax_Main-Regular.woff": 34160,
"output/chtml/fonts/woff-v2/MathJax_Main-Italic.woff": 20832,
"output/chtml/fonts/woff-v2/MathJax_Main-Bold.woff": 34464,
"output/chtml/fonts/woff-v2/MathJax_Fraktur-Regular.woff": 21480,
"output/chtml/fonts/woff-v2/MathJax_Fraktur-Bold.woff": 22340,
"output/chtml/fonts/woff-v2/MathJax_Calligraphic-Regular.woff": 9600,
"output/chtml/fonts/woff-v2/MathJax_Calligraphic-Bold.woff": 9908,
"output/chtml/fonts/woff-v2/MathJax_AMS-Regular.woff": 40808
},
"version": "3.1.4"
}

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

Some files were not shown because too many files have changed in this diff Show more