meanas/README.md

meanas

meanas is a python package for electromagnetic simulations

** UNSTABLE / WORK IN PROGRESS **

Formerly known as fdfd_tools.

This package is intended for building simulation inputs, analyzing simulation outputs, and running short simulations on unspecialized hardware. It is designed to provide tooling and a baseline for other, high-performance purpose- and hardware-specific solvers.

Contents

• Finite difference frequency domain (FDFD)
  • Library of sparse matrices for representing the electromagnetic wave equation in 3D, as well as auxiliary matrices for conversion between fields
  • Waveguide mode operators
  • Waveguide mode eigensolver
  • Stretched-coordinate PML boundaries (SCPML)
  • Functional versions of most operators
  • Anisotropic media (limited to diagonal elements eps_xx, eps_yy, eps_zz, mu_xx, ...)
  • Arbitrary distributions of perfect electric and magnetic conductors (PEC / PMC)
• Finite difference time domain (FDTD)
  • Basic Maxwell time-steps
  • Poynting vector and energy calculation
  • Convolutional PMLs

This package does not provide a fast matrix solver, though by default meanas.fdfd.solvers.generic(...) will call scipy.sparse.linalg.qmr(...) to perform a solve. For 2D FDFD problems this should be fine; likewise, the waveguide mode solver uses scipy's eigenvalue solver, with reasonable results.

For solving large (or 3D) FDFD problems, I recommend a GPU-based iterative solver, such as opencl_fdfd or those included in MAGMA. Your solver will need the ability to solve complex symmetric (non-Hermitian) linear systems, ideally with double precision.

• Source repository
• PyPI
• Github mirror

Installation

Requirements:

• python >=3.11
• numpy
• scipy

Install from PyPI with pip:

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:

pip3 install 'meanas[test]'
pip3 install 'meanas[docs]'
pip3 install 'meanas[examples]'
pip3 install 'meanas[dev]'

Development install

Install python3 and git:

# This is for Debian/Ubuntu/other-apt-based systems; you may need an alternative command
sudo apt install python3 build-essential python3-dev git

In-place development install:

# Download using git
git clone https://mpxd.net/code/jan/meanas.git

# If you'd like to create a virtualenv, do so:
python3 -m venv my_venv

# If you are using a virtualenv, activate it
source my_venv/bin/activate

# Install in-place (-e, editable) from ./meanas, including development dependencies ([dev])
pip3 install --user -e './meanas[dev]'

# Run tests
cd meanas
python3 -m pytest -rsxX | tee test_results.txt

See also:

• git book
• venv documentation
• python language reference
• python standard library

Use

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, 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, Material for MkDocs, and mkdocstrings.

Install the docs toolchain with:

pip3 install -e './meanas[docs]'

Then build the docs site with:

./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/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.

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.