Update README, remove obsolete periodic lattice tutorial

Former-commit-id: b720e30291768b564b73823c5741fe59ab46ed57

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

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

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][],

lattices.md

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