From e60f7abd9d890112cc598e08909a65bd71ed2642 Mon Sep 17 00:00:00 2001
From: Pascal Engeler <engelerp@phys.ethz.ch>
Date: Tue, 21 Jan 2020 10:41:43 +0100
Subject: [PATCH] Unit test doc

---
 README.md | 61 +++++++++++++++++++++++++++++++------------------------
 1 file changed, 35 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 3ebb946..c795d0e 100644
--- a/README.md
+++ b/README.md
@@ -6,8 +6,9 @@ such that it is flexible enough to adapt easily to any given situation. The list
 contents is the following:
 
 1. [ RBComb simulation framework. ](#RSF)
-2. [ Implementing a new project. ](#INP)
-2. [ Classes. ](#Classes)
+2. [ Unit tests](#UT)
+3. [ Implementing a new project. ](#INP)
+4. [ Classes. ](#Classes)
    - [ Vec2. ](#vec2)
    - [ Diagonalizer. ](#diagonalizer)
    - [ DrumParameters. ](#drumparams)
@@ -28,6 +29,12 @@ contents is the following:
 
 
 
+<a name="UT"></a>
+## Unit tests
+Unit tests are available in the subfolder `unit_tests`. They can be run from within
+that directory by issuing `make run`. They should all compile and run fine.
+
+
 <a name="INP"></a>
 ## Implementing a new project
 In order to implement a new project, follow these steps:
@@ -41,20 +48,22 @@ In order to implement a new project, follow these steps:
 2. Write custom versions of classes `DrumParameters` (everything that is static) and `DrumVariables`
 (everything that is dynamic) to accomodate these. Inspiration in `lib/drum_variables.hpp` and
 `lib/drum_parameters.hpp`.
-4. Write custom `Grabber` that extracts the relevant data (inspiration in `include/grabber.hpp`)
-3. Write custom child of `Force` to calculate the force.
-4. Write custom children of `Coupler` and `Driver` to correctly update the drive and couplings.
-5. If desired, write a custom child of `LatticeGenerator` to generate a custom lattice,
+3. Write custom `Grabber` that extracts the relevant data (inspiration in `include/grabber.hpp`)
+4. Write custom child of `Force` to calculate the force.
+5. Write custom children of `Coupler` and `Driver` to correctly update the drive and couplings.
+6. If desired, write a custom child of `LatticeGenerator` to generate a custom lattice,
 or use the generator `projects/braidingTightBinding/include/rbcomb_generator_braid.hpp` to
 create the RBComb.
-6. If desired, write a child of `MatrixElementCalculator` to calculate matrix elements
+7. If desired, write a child of `MatrixElementCalculator` to calculate matrix elements
 for the dynamic matrix.
-7. Check the unit tests (`unit_tests`) or other projects to see how a `main.cpp` could be
+8. Check the unit tests (`unit_tests`) or other projects to see how a `main.cpp` could be
 constructed.
 
-Hints for organizing and running simulations
+Hints for organizing, building and running simulations
 1. Use a Makefile.
    - The framework should be compiled with c++ 2a.
+   - The `Diagonalizer` requires LAPACK to be linked.
+   - Get inspiration from other projects.
 2. Organize executables in `bin`
 3. Store data and plots in subfolders of `results`
 
@@ -68,7 +77,7 @@ described in the following. Note that qualifiers, references and the like are di
 where it improves legibility. Consult the source files for more information.
 
 <a name="vec2"></a>
-### `Vec2` (vec2.hpp), 2-vector utility class
+#### `Vec2` (vec2.hpp), 2-vector utility class
 1. Template arguments
    - `value_t`: type of vector entries
 2. Members
@@ -106,7 +115,7 @@ where it improves legibility. Consult the source files for more information.
      - `<<` with `std::ostream`
 
 <a name="diagonalizer"></a>
-### `Diagonalizer` (diagonalizer.hpp), class to diagonalize symmetric Matrices
+#### `Diagonalizer` (diagonalizer.hpp), class to diagonalize symmetric Matrices
 1. Member functions
    - `std::vector<double> ev(std::vector<double> mat, size_t N)`
      - returns eigenvalues of the symmetric matrix mat of linear size N
@@ -118,13 +127,13 @@ where it improves legibility. Consult the source files for more information.
    - Only finding eigenvectors and -values in a certain range may be added later on
 
 <a name="drumparams"></a>
-### `DrumParameters`(drum_parameters.hpp), contains data members characterizing the static state of a drum
+#### `DrumParameters`(drum_parameters.hpp), contains data members characterizing the static state of a drum
 
 <a name="drumvars"></a>
-### `DrumVariables` (drum_variables.hpp), contains data members characterizing the dynamic state of a drum
+#### `DrumVariables` (drum_variables.hpp), contains data members characterizing the dynamic state of a drum
 
 <a name="drum"></a>
-### `Drum` (drum.hpp), represents a single drum top resonator
+#### `Drum` (drum.hpp), represents a single drum top resonator
 1. Template arguments
    - `value_t`: Scalar type
    - `params_t`: Drum parameters container type
@@ -160,7 +169,7 @@ this class is `delete`'d. It should be constructed from an object of type `param
 be trivial.
 
 <a name="force"></a>
-### `Force` (force.hpp), force functional
+#### `Force` (force.hpp), force functional
 1. Template arguments
    - `value_t`: Scalar type
    - `params_t`: Drum parameters type
@@ -180,7 +189,7 @@ functional exists to fit special cases as well. The file `include/force_simple.h
 showcases how a real force functional could be written.
 
 <a name="driver"></a>
-### `Driver` (driver.hpp), calculate drive of drums
+#### `Driver` (driver.hpp), calculate drive of drums
 1. Template arguments
    - `value_t`: Scalar type
    - `drum_t`: Drum type
@@ -205,7 +214,7 @@ Note that an rk4 scheme advances time in steps of `dt/2`.
    - An example implementation of a `Driver` is shown in `include/driver_simple.hpp`.
 
 <a name="coupler"></a>
-### `Coupler` (coupler.hpp), calculate couplings between drums
+#### `Coupler` (coupler.hpp), calculate couplings between drums
 1. Template arguments
    - `value_t`: Scalar type
    - `drum_t`: Drum type
@@ -235,7 +244,7 @@ Note that an rk4 scheme advances time in steps of `dt/2`.
    - An example implementation of a `Coupler` is shown in `include/coupler_simple.hpp`.
 
 <a name="latticegenerator"></a>
-### `LatticeGenerator` (lattice_generator.hpp), generates drum lattices
+#### `LatticeGenerator` (lattice_generator.hpp), generates drum lattices
 1. Template arguments
    - `value_t`: Scalar type
    - `params_t`: Drum parameters type
@@ -260,7 +269,7 @@ differently.
    - `params_t`
      - Existence of `position` member
 <a name="noc"></a>
-#### Neighbour ordering convention
+##### Neighbour ordering convention
 An important note is the __convention of neighbour ordering__. Each drum has neighbours 0 thru 3.
 For drums in different sublattices, these neighbours are:
 - Sublattice 'A':
@@ -278,7 +287,7 @@ are assumed to respect the above convention. Note that with this convention,
 neighbours see each other as the same neighbour index (the i-th neighbour of j
   sees j as its i-th neighbour). __Never violate this convention__.
 <a name="inc"></a>
-#### Inexistent neighbour convention
+##### Inexistent neighbour convention
 Another __convention__ concerns __inexistent neighbours__. For that purpose, this class should append
 an auxiliary drum to the end of the drum vector. If neighbour i of a drum does not exist
 (due to boundary, for example), the corresponding neighbour index will point to the
@@ -287,7 +296,7 @@ drum are to be kept at 0. This condition can then be applied in force calculatio
 if one uses the couplings of the neighbours instead of the considered drum.
 
 <a name="mec"></a>
-### `MatrixElementCalculator` (matrix_element_calculator.hpp), calculates matrix elements
+#### `MatrixElementCalculator` (matrix_element_calculator.hpp), calculates matrix elements
 1. Template arguments
    - `value_t`: Scalar type
    - `params_t`: Drum parameters type
@@ -318,10 +327,10 @@ the individual functions correctly to accomodate the correct neighbours.
      - `get_variables()`
 
 <a name="rk4b"></a>
-### `RK4Buffer` (rk4_buffer.hpp), holds Rk4Stepper intermediate results
+#### `RK4Buffer` (rk4_buffer.hpp), holds Rk4Stepper intermediate results
 
 <a name="rk4s"></a>
-### `Rk4Stepper` (rk4_stepper.hpp), performs timesteps using rk4 scheme
+#### `Rk4Stepper` (rk4_stepper.hpp), performs timesteps using rk4 scheme
 1. Template arguments
    - `value_t`: Scalar type
    - `params_t`: Drum parameters container type
@@ -337,7 +346,7 @@ the individual functions correctly to accomodate the correct neighbours.
      - Arguments: Force functional, Drum vector, Adjacency vector, time step, start time of current step
 
 <a name="sysparams"></a>
-### `SystemParameters` (system_parameters.hpp), holds system parameters
+#### `SystemParameters` (system_parameters.hpp), holds system parameters
 1. Template arguments
    - `coupler_t`: Coupler type
    - `driver_t`: Driver type
@@ -347,7 +356,7 @@ the individual functions correctly to accomodate the correct neighbours.
    - `adjacency_vector`: A `std::vector<std::vector<int> >` representing the adjacency vector
 
 <a name="grabber"></a>
-### `Grabber` (grabber.hpp), grabs and saves data
+#### `Grabber` (grabber.hpp), grabs and saves data
 1. Template arguments
    - `value_t`: Scalar type
    - `drum_t`: Drum type
@@ -368,7 +377,7 @@ the individual functions correctly to accomodate the correct neighbours.
    - One should also implement a helper struct, as seen in `include/grabber.hpp`
 
 <a name="system"></a>
-### `System` (system.hpp), holds all parts together
+#### `System` (system.hpp), holds all parts together
 1. Template arguments
    - `value_t`: Scalar type
    - `drum_t`: Drum type
-- 
GitLab