diff --git a/Doxyfile b/Doxyfile index 88ea97c..8ed3582 100644 --- a/Doxyfile +++ b/Doxyfile @@ -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 diff --git a/README.md b/README.md index 1b51e3b..4c69dc0 100644 --- a/README.md +++ b/README.md @@ -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 . +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 . 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 . + +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 diff --git a/farfield.png b/farfield.png new file mode 100644 index 0000000..8baf1d8 Binary files /dev/null and b/farfield.png differ diff --git a/finite_systems.md b/finite_systems.md index cb198ef..f4b2294 100644 --- a/finite_systems.md +++ b/finite_systems.md @@ -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][], diff --git a/lattices.md b/lattices.md deleted file mode 100644 index 7abaf5e..0000000 --- a/lattices.md +++ /dev/null @@ -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. -