Start some intro to simulating infinite lattices

Former-commit-id: 696f8821e5ea25946904d3241ac01a2df39a8e77

lattices.md

@@ -0,0 +1,108 @@
+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, \omega$ space.
+ 2. Pre-calculating the
+    Ewald-summed translation operators.
+ 3. For each $k, \omega$ 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:
+
+```
+  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, \omega$ 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
+$k = (0, 1\cdot10^5\mathrm{m}^{-1})$, we can generate an input
+running
+```
+  for ky in $(seq 0 1e3 1e5); do
+    echo 0 $ky >> klist
+  done
+```
+
+It also make sense to pre-generate the list of $\omega$ values,
+e.g. 
+```
+  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_in` binary in our `${PATH}`, we can
+now run e.g.
+```
+  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.
+
+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 s_*
+```
+which would create a directory named `all` containing several
+.npy files.
+
+
+Steps 3, 4
+----------
+
+TODO. For the time being, see e.g. the [TODO SPECIFY] jupyter notebook
+for the remaining steps.
+