fdfd_tools/README.md

101 lines
3.2 KiB
Markdown
Raw Normal View History

# meanas README
2016-04-13 04:05:08 -07:00
2019-08-04 13:48:41 -07:00
**meanas** is a python package for electromagnetic simulations
** UNSTABLE / WORK IN PROGRESS **
Formerly known as [fdfd_tools](https://mpxd.net/code/jan/fdfd_tools).
2019-08-04 13:48:41 -07:00
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.
2016-05-30 22:30:45 -07:00
**Contents**
2019-08-04 13:48:41 -07:00
- 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
2016-05-30 22:30:45 -07:00
This package does *not* provide a fast matrix solver, though by default
2019-08-04 13:48:41 -07:00
`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.
2019-08-04 13:48:41 -07:00
For solving large (or 3D) FDFD problems, I recommend a GPU-based iterative
solver, such as [opencl_fdfd](https://mpxd.net/code/jan/opencl_fdfd) or
those included in [MAGMA](http://icl.cs.utk.edu/magma/index.html). Your
solver will need the ability to solve complex symmetric (non-Hermitian)
linear systems, ideally with double precision.
2016-05-30 22:30:45 -07:00
2019-10-08 23:59:03 -07:00
- [WORKING Source repository](https://mpxd.net/code/jan/fdfd_tools/src/branch/ongoing)
- *TODO* [Source repository](https://mpxd.net/code/jan/meanas)
- PyPI *TBD*
2019-08-04 13:48:41 -07:00
2016-05-30 22:30:45 -07:00
## Installation
**Requirements:**
2019-08-04 13:48:41 -07:00
* python 3 (tests require 3.7)
2016-05-30 22:30:45 -07:00
* numpy
* scipy
Install from PyPI with pip:
```bash
pip3 install 'meanas[test,examples]'
```
### Development install
Install python3.7 and virtualenv:
```bash
# This is for Debian/Ubuntu/other-apt-based systems; you may need an alternative command
sudo apt install python3.7 virtualenv build-essential python3.7-dev
```
If python 3.7 is not your default python3 version, create a virtualenv:
```bash
# Check python3 version:
python3 --version
# output: Python 3.7.5rc1
# Create a virtual environment using python3.7 and place it in the directory `venv/`
virtualenv -p python3.7 venv
```
In-place development install:
2016-05-30 22:30:45 -07:00
```bash
# Download using git
git clone --branch ongoing https://mpxd.net/code/jan/fdfd_tools.git meanas/
# NOTE: In the future this will become
#git clone https://mpxd.net/code/jan/meanas.git
# If you are using a virtualenv, activate it
source venv/bin/activate
# Install in-place (-e, editable) from ./meanas, including testing and example dependencies ([test, examples])
pip3 install --user -e './meanas[test,examples]'
# Run tests
python3 -m pytest
2016-05-30 22:30:45 -07:00
```
## Use
2019-08-04 13:48:41 -07:00
See `examples/` for some simple examples; you may need additional
packages such as [gridlock](https://mpxd.net/code/jan/gridlock)
to run the examples.