Update README, remove obsolete periodic lattice tutorial

Former-commit-id: b720e30291768b564b73823c5741fe59ab46ed57
This commit is contained in:
Marek Nečada 2020-06-26 22:40:00 +03:00
parent 6c79a9116b
commit 87c2b08701
5 changed files with 65 additions and 123 deletions

View File

@ -51,7 +51,7 @@ PROJECT_BRIEF = "Electromagnetic multiple scattering library and toolki
# and the maximum width should not exceed 200 pixels. Doxygen will copy the logo
# to the output directory.
PROJECT_LOGO =
PROJECT_LOGO = farfield.png
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
# into which the generated documentation will be written. If a relative path is

View File

@ -14,9 +14,11 @@ the particles. The system can consist either of a finite number of particles
or an infinite number of periodically arranged lattices (with finite number
of particles in a single unit cell).
Features
========
Finite systems
--------------
* Computing multipole excitations and fields scattered from nanoparticle
@ -31,7 +33,6 @@ Infinite systems (lattices)
---------------------------
* 2D-periodic systems with arbitrary unit cell geometry supported. (TODO 1D and 3D.)
* Computing multipole excitations and fields scattered from nanoparticle
arrays illuminated by plane (or other periodic) waves.
* Finding eigenmodes and calculating dispersion relations.
* Calculation of the scattered fields.
* *Calculation of total transmission and reflection properties (TODO).*
@ -39,6 +40,14 @@ Infinite systems (lattices)
symmetries of the lattice (decomposition to irreducible representations) (in development).*
Getting the code
================
The main upstream public repository is located at <https://repo.or.cz/qpms.git>.
Just clone the repository with `git` and proceed to the installation instructions
below.
Installation
============
The package depends on several python modules, a BLAS/LAPACK library with
@ -99,16 +108,65 @@ under root.
Tutorials
---------
* [Infinite system (lattice) tutorial][tutorial-infinite]
* [Finite system tutorial][tutorial-finite]
See also the examples directory.
See also the examples directory in the source repository.
Acknowledgments
================
This software has been developed in the [Quantum Dynamics research group][QD],
Aalto University, Finland. If you use the code in your work, please cite
**M. Nečada and P. Törmä, Multiple-scattering T-matrix simulations for nanophotonics: symmetries and periodic lattices, [arXiv: 2006.12968][lepaper] (2020)**
in your publications, presentations, and similar.
Please also have a look at other publications by the group
(google scholar Päivi Törmä), they may be useful for your work as well.
Bug reports
===========
If you believe that some parts of QPMS behave incorrectly, please mail
a bug report to <marek@necada.org>. To ensure that your message is not
considered spam, please start the subject line with `QPMS`.
If you were able to fix a bug yourself, please include the patch as well,
see below.
Contributions
=============
Contributions to QPMS are welcome, be it bug fixes, improvements to the
documentation, code quality, or new features.
You can send patches prepared using the
[`git format-patch`](https://git-scm.com/docs/git-format-patch) tool
to <marek@necada.org>.
If you plan to contribute with major changes to the codebase, it is
recommended to discuss that first (see the contact information below).
Contact & discussion
====================
You can contact the main author e.g. via [e-mail](marek@necada.org)
or [Telegram](https://t.me/necadam).
You are also warmly welcome to the [QPMS user chat](https://t.me/QPMScattering)
in Telegram!
[SCUFF-EM]: https://homerreid.github.io/scuff-em-documentation/
[OpenBLAS]: https://www.openblas.net/
[GSL]: https://www.gnu.org/software/gsl/
[cmake]: https://cmake.org
[TRITON-README]: README.Triton.md
[tRITON-README]: README.Triton.md
[tutorial-finite]: finite_systems.md
[tutorial-infinite]: lattices.md
[doxygen]: http://doxygen.nl/
[QD]: https://www.aalto.fi/en/department-of-applied-physics/quantum-dynamics-qd
[lepaper]: https://arxiv.org/abs/2006.12968

BIN
farfield.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.1 KiB

View File

@ -1,6 +1,8 @@
Using QPMS library for simulating finite systems
================================================
*** This tutorial is partly obsolete, the interpolators are no longer the first choice of getting the T-matrices. ***
The main C API for finite systems is defined in [scatsystem.h][], and the
most relevant parts are wrapped into python modules. The central data structure
defining the system of scatterers is [qpms_scatsys_t][],

View File

@ -1,118 +0,0 @@
Using QPMS library for finding modes of 2D-periodic systems
===========================================================
Calculating modes of infinite 2D arrays is now done
in several steps (assuming the T-matrices have already
been obtained using `scuff-tmatrix` or can be obtained
from Lorenz-Mie solution (spherical particles)):
1. Sampling the *k*, *ω* space.
2. Pre-calculating the
Ewald-summed translation operators.
3. For each *k*, *ω* pair, build the LHS operator
for the scattering problem (TODO reference), optionally decomposed
into suitable irreducible representation subspaces.
4. Evaluating the singular values and finding their minima.
The steps above may (and will) change as more user-friendly interface
will be developed.
Preparation: compile the `ew_gen_kin` utility
---------------------------------------------
This will change, but at this point, the lattice-summed
translation operators are computed using the `ew_gen_kin`
utility located in the `qpms/apps` directory. It has to be built
manually like this:
```bash
cd qpms/apps
c99 -o ew_gen_kin -Wall -I ../.. -I ../../amos/ -O2 -ggdb -DQPMS_VECTORS_NICE_TRANSFORMATIONS -DLATTICESUMS32 2dlattice_ewald.c ../translations.c ../ewald.c ../ewaldsf.c ../gaunt.c ../lattices2d.c ../latticegens.c ../bessel.c -lgsl -lm -lblas ../../amos/libamos.a -lgfortran ../error.c
```
Step 1: Sampling the *k*, *ω* space
--------------------------------------
`ew_gen_kin` expects a list of (*k_x*, *k_y*)
pairs on standard input (separated by whitespaces),
the rest is specified via command line arguments.
So if we want to examine the line between the Г point and the point
\f$ k = (0, 10^5\,\mathrm{m}^{-1}) \f$, we can generate an input
running
```bash
for ky in $(seq 0 1e3 1e5); do
echo 0 $ky >> klist
done
```
It also make sense to pre-generate the list of *ω* values,
e.g.
```bash
seq 6.900 0.002 7.3 | sed -e 's/,/./g' > omegalist
```
Step 2: Pre-calculating the translation operators
-------------------------------------------------
`ew_gen_kin` currently uses command-line arguments in
an atrocious way with a hard-coded order:
```
ew_gen_kin outfile b1.x b1.y b2.x b2.y lMax scuffomega refindex npart part0.x part0.y [part1.x part1.y [...]]
```
where `outfile` specifies the path to the output, `b1` and `b2` are the
direct lattice vectors, `lMax` is the multipole degree cutoff,
`scuffomega` is the frequency in the units used by `scuff-tmatrix`
(TODO specify), `refindex` is the refractive index of the background
medium, `npart` number of particles in the unit cell, and `partN` are
the positions of these particles inside the unit cell.
Assuming we have the `ew_gen_kin` binary in our `${PATH}`, we can
now run e.g.
```bash
for omega in $(cat omegalist); do
ew_gen_kin $omega 621e-9 0 0 571e-9 3 w_$omega 1.52 1 0 0 < klist
done
```
This pre-calculates the translation operators for a simple (one particle per unit cell)
621 nm × 571 nm rectangular lattice inside a medium with refractive index 1.52,
up to the octupole (`lMax` = 3) order, yielding one file per frequency.
This can take some time and
it makes sense to run a parallelised `for`-loop instead; this is a stupid but working
way to do it in bash:
```bash
N=4 # number of parallel processes
for omega in $(cat omegalist); do
((i=i%N)); ((i++==0)) && wait
ew_gen_kin $omega 621e-9 0 0 571e-9 3 w_$omega 1.52 1 0 0 < klist
echo $omega # optional, to follow progress
done
```
When this is done, we convert all the text output files into
numpy's binary format in order to speed up loading in the following steps.
This is done using the processWfiles_sortnames.py script located in the
`misc` directory. Its usage pattern is
```
processWfiles_sortnames.py npart dest src1 [src2 ...]
```
where `npart` is the number of particles in the unit cell, `dest`
is the destination path for the converted data (this will be
a directory), and the remaining arguments are paths to the
files generated by `ew_gen_kin`. In the case above, one could use
```
processWfiles_sortnames.py 1 all w_*
```
which would create a directory named `all` containing several
.npy files.
Steps 3, 4
----------
TODO. For the time being, see e.g. the `SaraRect/dispersions.ipynb` jupyter notebook
from the `qpms_ipynotebooks` repository
for the remaining steps.