jan/meanas
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity
meanas/README.md

5.6 KiB
Raw Blame History

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.

Installation

Requirements:

  • python >=3.11
  • numpy
  • scipy

Install from PyPI with pip:

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:

Use

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.

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.