From 63a52e8d6aa66e266c677542550302250368769c Mon Sep 17 00:00:00 2001
From: Pascal Engeler <engelerp@phys.ethz.ch>
Date: Mon, 20 Jan 2020 16:46:41 +0100
Subject: [PATCH] More documentation
---
README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 70 insertions(+), 2 deletions(-)
diff --git a/README.md b/README.md
index 598c817..3577e04 100644
--- a/README.md
+++ b/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
--
GitLab