More documentation

README.md

@@ -122,9 +122,9 @@ showcases how a real force functional could be written.
    - `void step(value_t dt)`
      - Move in time by `dt`
    - `value_t operator()(size_t drum_index)`
-     - Returns drive of drum `drum_index` at current time
+     - Returns drive of drum `drum_index` (wrt `drum_vec`) at current time
 3. Description
-This interface is a guide to complete implementation of a drive calculation class. Any drive
+This interface is a guide to complete implementation of a drive calculation class. Any driver
 class should derive from this class, but the child type should then be used in
 order to avoid the vtable penalty.
 
@@ -141,6 +141,74 @@ The functional should return the current drive on the drum with index passed as
 
 An example implementation of a `Driver` is shown in `include/driver_simple.hpp`.
 
+### Interface template type `Coupler` (coupler.hpp), calculate couplings between drums
+1. Template arguments
+   - `value_t`: Scalar type
+   - `drum_t`: Drum type
+2. Virtual functions
+   - `void precompute(value_t t_end, value_t dt, std::vector<drum_t> drum_vec)`
+     - Called once at begin of `system` lifetime
+   - `void step(value_t dt)`
+     - Move in time by `dt`
+   - `value_t operator()(size_t drum_index, size_t neighbour_index)`
+     - Returns coupling between drums `drum_index` and `neighbour_index` (wrt `drum_vec`) at current time
+3. Description
+This interface is a guide to complete implementation of a coupling calculation class. Any coupler
+class should derive from this class, but the child type should then be used in
+order to avoid the vtable penalty.
+
+The purpose of this class is to set the coupling of each neighbouring pair of drums at specific times.
+
+In the `precompute` function, this class is passed all information it could need about
+the system. Hence it can in principle precompute all values for all drums and all times
+of the simulation.
+
+The member `step` is called to inform the `Coupler` that time is advanced by the passed argument.
+Note that an rk4 scheme advances time in steps of `dt/2`.
+
+The functional should return the current coupling between the two drums with indices passed as arguments.
+
+An example implementation of a `Coupler` is shown in `include/coupler_simple.hpp`.
+
+### Interface template type `LatticeGenerator` (lattice_generator.hpp), generates drum lattices
+1. Template arguments
+   - `value_t`: Scalar type
+   - `params_t`: Drum parameters type
+   - `vars_t`: Drum variables type
+   - `sbuffer_t`: Stepper buffer type
+2. Virtual functions
+   - `std::pair<std::vector<drum_t>, std::vector<int> > operator()(params_t)`
+     - Takes a `params_t`
+     - Returns a pair that characterizes the generated lattice
+       - a vector of drums `ds`
+       - an adjacency vector of vectors `adj`, such that `ds[i]` and `ds[adj[i]]` are neighbours
+     - All drums have the same `params_t`, except that the `position` members differ.
+3. Description
+An example child of the `LatticeGenerator` is shown in the file `include/rbcomb_generator.hpp`.
+
+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':
+  - 0, adj[0]: straight down
+  - 1, adj[1]: top left
+  - 2, adj[2]: top right
+- Sublattice 'B':
+  - 0, adj[0]: straight up
+  - 1, adj[1]: bottom right
+  - 2, adj[2]: bottom left
+Here _adj[]_ signifies the adjacency list of the given drum. Similarly, the couplings
+_t0_ thru _t2_ in objects of type `params_t` should also respect this ordering. More
+generally, whenever neighbours of a specific drum are ordered in some fashion, they
+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__.
+4. Further developments
+In the future, there may be another overload for the functional. For example, it could either take an
+`std::vector<params_t>` or an additional random number generator to construct the drums
+differently.
+
+
+
 ### Template Type `Rk4Stepper` (rk4_stepper.hpp), performs timesteps using rk4 scheme
 1. Template arguments
    - `value_t`: Scalar type