From 843d7ac50e18706aeafe85f5eaae1471605f6494 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marek=20Ne=C4=8Dada?= <marek@necada.org>
Date: Thu, 13 Jun 2019 12:37:31 +0300
Subject: [PATCH] Docs update

Former-commit-id: 7cd3cfaf51783a252b9ab606ffe329cd581e824d
---
 README.md         |  6 +++---
 finite_systems.md | 16 ++++++++++++++++
 lattices.md       | 10 +++++-----
 3 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index c398018..925623c 100644
--- a/README.md
+++ b/README.md
@@ -47,7 +47,7 @@ You also need a fresh enough version of [cmake][].
 
 After GSL is installed, you can install qpms to your local python library using::
 
-```
+```{.sh}
   cmake .
   make amos
   python3 setup.py install --user
@@ -66,7 +66,7 @@ Documentation
 =============
 
 Documentation of QPMS is a work in progress. Most of the newer code
-is documented using doxygen comments. To build the documentation, just run
+is documented using [doxygen][] comments. To build the documentation, just run
 `doxygen`
 in the root directory; the documentation will then be found in 
 `docs/html/index.html`.
@@ -89,4 +89,4 @@ Tutorials
 [TRITON-README]: README.Triton.md
 [tutorial-finite]: finite_systems.md
 [tutorial-infinite]: lattices.md
-
+[doxygen]: http://doxygen.nl/
diff --git a/finite_systems.md b/finite_systems.md
index c922b7b..cb198ef 100644
--- a/finite_systems.md
+++ b/finite_systems.md
@@ -9,6 +9,10 @@ which holds information about particle positions and their T-matrices
 keeps track about the symmetry group and how the particles transform
 under the symmetry operations.
 
+
+SVD of a finite symmetric system of scatterers
+----------------------------------------------
+
 Let's have look how thinks are done on a small python script.
 The following script is located in `misc/201903_finiterectlat_AaroBEC.py`.
 
@@ -163,10 +167,22 @@ and saving the lowest singular values (or all singular values smaller than
 The singular vectors corresponding to zero singular values represent the 
 "modes" of the finite array.
 
+
+Analysing the results
+---------------------
+
 *TODO analyzing the resulting files.*
 
+Examples of how the data generated above can be analysed
+can be seen in the jupyter notebooks from the [qpms_ipynotebooks][]
+repository in the `AaroBEC` directory.
 
 
+
+
+
+
+[qpms_ipynotebooks]: https://version.aalto.fi/gitlab/qd/qpms_ipynotebooks 
 [scatsystem.h]: @ref scatsystem.h
 [qpms_scatsys_t]: @ref qpms_scatsys_t
 [scuff-tmatrix]: https://homerreid.github.io/scuff-em-documentation/applications/scuff-tmatrix/scuff-tmatrix/
diff --git a/lattices.md b/lattices.md
index 9ebb1d3..7abaf5e 100644
--- a/lattices.md
+++ b/lattices.md
@@ -26,7 +26,7 @@ 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
 ``` 
@@ -41,7 +41,7 @@ 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
@@ -49,7 +49,7 @@ running
 
 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
 ```
 
@@ -71,7 +71,7 @@ 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
@@ -82,7 +82,7 @@ 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