From f27c4379b7d9d8efa3861162985ca47190733f1c Mon Sep 17 00:00:00 2001
From: Pascal Engeler <engelerp@phys.ethz.ch>
Date: Tue, 21 Jan 2020 18:23:23 +0100
Subject: [PATCH] added dependencies to documentation
---
README.md | 142 +++++++++++++++++++++++++++++++++++++++++++++---------
1 file changed, 118 insertions(+), 24 deletions(-)
diff --git a/README.md b/README.md
index 31240fb..9e2c4fc 100644
--- a/README.md
+++ b/README.md
@@ -120,8 +120,11 @@ where it improves legibility. Consult the source files for more information.
- All versions of `op=` of the above
- `[]` with `std::size_t`
- `<<` with `std::ostream`
-4. Dependencies
-5. Dependents
+4. Dependents
+ - `DrumParameters`
+ - `LatticeGenerator` children
+5. Dependencies
+ - None
<a name="diagonalizer"></a>
#### `Diagonalizer` (diagonalizer.hpp), class to diagonalize symmetric Matrices
@@ -136,13 +139,58 @@ where it improves legibility. Consult the source files for more information.
- throws upon diagonalization failure
3. Further developments
- Only finding eigenvectors and -values in a certain range may be added later on
+4. Dependents
+ - `System`
+5. Dependencies
+ - None
<a name="drumparams"></a>
-#### `DrumParameters`(drum_parameters.hpp), contains data members characterizing the static state of a drum
+#### `DrumParameters`(drum_parameters.hpp), describes static state of a drum
+1. Explicit constructors
+ - Determined by implementation
+2. Member functions
+ - None or determined by implementation
+3. Public data members
+ - Determined by implementation
+4. Typical dependents
+ - `Driver`
+ - `Coupler`
+ - `Force` children
+ - `Grabber`
+ - `MatrixElementCalculator` children
+ - `LatticeGenerator` children
+5. Typical dependencies
+ - `Vec2`
<a name="drumvars"></a>
-#### `DrumVariables` (drum_variables.hpp), contains data members characterizing the dynamic state of a drum
-- Respect the constraints given by [this issue](https://gitlab.phys.ethz.ch/engelerp/rbcomb-simulation/issues/4).
+#### `DrumVariables` (drum_variables.hpp), describes dynamic state of a drum
+1. Explicit constructors
+ - Determined by implementation
+2. Member functions
+ - None or determined by implementation
+3. Public data members
+ - Determined by implementation
+ - Must include (required by [System](#system) and [Drum](#drum))
+ - Central drive coupling `value_t V`
+ - Neighbour couplings `value_t t0`, `value_t t1`, `value_t t2`
+ - Must include (required by [Rk4Stepper](#rk4s))
+ - current displacement `value_t x`
+ - current displacement storage `value_t x_temp`
+ - current velocity `value_t xdot`
+ - current velocity storage `value_t xdot_temp`
+ - `var` and `var_temp` must be initialized to the same value.
+4. Typical dependents
+ - `Driver`
+ - `Coupler`
+ - `Force` children
+ - `Grabber`
+ - `MatrixElementCalculator` children
+ - `System` through private push_dc()
+ - `Drum` (see [this issue](https://gitlab.phys.ethz.ch/engelerp/rbcomb-simulation/issues/4)).
+5. Typical dependencies
+ - `Vec2`
+6. Remarks
+ - Respect the constraints given by [this issue](https://gitlab.phys.ethz.ch/engelerp/rbcomb-simulation/issues/4).
<a name="drum"></a>
#### `Drum` (drum.hpp), represents a single drum top resonator
@@ -176,7 +224,18 @@ where it improves legibility. Consult the source files for more information.
- `void set_drive(value_t)`
- Sets central electrode coupling
- [deprecated](https://gitlab.phys.ethz.ch/engelerp/rbcomb-simulation/issues/4)
-5. Description
+5. Dependents
+ - `Coupler` children
+ - `Driver` children
+ - `Force` children
+ - `LatticeGenerator` children
+ - `MatrixElementCalculator` children
+ - `Rk4Stepper`
+ - `System`
+ - `Grabber`
+6. Dependencies
+ - None
+7. Description
- A drum is described by a set of (static) parameters (stiffness, mass, x-y position, etc),
which are to be stored in a container of type `params_t`. The variables (displacement, velocity,
electrode charges, etc.) are stored in a container of type `vars_t`. Example classes for
@@ -185,7 +244,7 @@ However, these containers likely need to be adapted to the situation at hand.
When time evolving, the stepper will use the container of
type `sbuffer_t` to store its intermediate results. Note that the default constructor of
this class is `delete`'d. It should be constructed from an object of type `params_t`.
-5. Further developments
+8. Further developments
- Abstract interfaces for `params_t` and `vars_t` could be added, but they would
be trivial.
@@ -201,7 +260,13 @@ be trivial.
3. Virtual functions
- `value_t operator()(drum_t drum, drum_t n1, drum_t n2, drum_t n3, value_t time)`
- Returns force on `drum` at `time`, given its three neighbours `n1`, `n2`, `n3`
-4. Description
+4. Typical dependents
+ - `Rk4Stepper`, but only virtually
+5. Typical dependencies
+ - `Drum`
+ - `params_t`
+ - `vars_t`
+6. Description
- This interface is a guide to complete implementation of a force functional. Any force
functional should derive from this class, but the child type should then be used in
order to avoid the vtable penalty.
@@ -225,7 +290,13 @@ showcases how a real force functional could be written.
- Move in time by `dt`
- `value_t operator()(size_t drum_index)`
- Returns drive of drum `drum_index` (wrt `drum_vec`) at current time
-4. Description
+4. Typical dependents
+ - `System`, but only virtually
+3. Typical dependencies
+ - `drum_t`
+ - `DrumParameters`
+ - `DrumVariables`
+5. Description
- 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.
@@ -234,7 +305,7 @@ order to avoid the vtable penalty.
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 `Driver` that time is advanced by the passed argument.
-Note that an rk4 scheme advances time in steps of `dt/2`.
+Note that an rk4 scheme advances time in twinned steps of `dt/2`.
- The functional should return the current drive on the drum with index passed as argument.
- An example implementation of a `Driver` is shown in `include/driver_simple.hpp`.
@@ -252,7 +323,13 @@ Note that an rk4 scheme advances time in steps of `dt/2`.
- 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
-4. Description
+4. Typical dependents
+ - `System`, but only virtually
+3. Typical dependencies
+ - `drum_t`
+ - `DrumParameters`
+ - `DrumVariables`
+5. 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.
@@ -261,7 +338,7 @@ order to avoid the vtable penalty.
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`.
+Note that an rk4 scheme advances time in twinned 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`.
@@ -290,8 +367,7 @@ differently.
6. Dependents
- None
7. Typical dependencies
- - `params_t`
- - Existence of `position` member
+ - `params_t` (existence of `position` member)
<a name="noc"></a>
##### Neighbour ordering convention
An important note is the __convention of neighbour ordering__. Each drum has neighbours 0 thru 3.
@@ -341,19 +417,16 @@ if one uses the couplings of the neighbours instead of the considered drum.
- The overload of the functional is done to avoid branching. When building the matrix, one calls
the individual functions correctly to accomodate the correct neighbours.
5. Dependents
- - `System`
- - Existence of the virtual functions
+ - `System`, but only virtually
6. Typical dependencies
- `params_t`
- - Class semantics
- `vars_t`
- - Class semantics
- - `drum_t`
- - `get_parameters()`
- - `get_variables()`
+ - `drum_t` (existence of `get_parameters()` and `get_variables()`)
<a name="rk4b"></a>
#### `RK4Buffer` (rk4_buffer.hpp), holds Rk4Stepper intermediate results
+1. Description
+ - This class must never be changed except when changing stepper
<a name="rk4s"></a>
#### `Rk4Stepper` (rk4_stepper.hpp), performs timesteps using rk4 scheme
@@ -370,8 +443,15 @@ the individual functions correctly to accomodate the correct neighbours.
- `void step_2(force_t, std::vector<drum_t>, std::vector<std::vector<int> >, value_t dt, value_t time)`
- `void step_3(force_t, std::vector<drum_t>, std::vector<std::vector<int> >, value_t dt, value_t time)`
- All of the above perform one step of a timestep, between successive steps certain
- other updates need to be taken care of.
+ other updates need to be taken care of by the [owner object](#system).
- Arguments: Force functional, Drum vector, Adjacency vector, time step, start time of current step
+4. Dependents
+ - `System`
+4. Dependencies
+ - `force_t`, but only virtually
+ - `buffer_t`
+ - `Drum`
+ - `vars_t`, see [DrumVariables](#drumvars)
<a name="sysparams"></a>
#### `SystemParameters` (system_parameters.hpp), holds system parameters
@@ -384,6 +464,10 @@ the individual functions correctly to accomodate the correct neighbours.
- `coupler`: The coupler_t object of the system
- `driver`: The driver_t object of the system
- `adjacency_vector`: A `std::vector<std::vector<int> >` representing the adjacency vector
+4. Dependents
+ - `System`
+5. Dependencies
+ - None
<a name="grabber"></a>
#### `Grabber` (grabber.hpp), grabs and saves data
@@ -409,7 +493,13 @@ the individual functions correctly to accomodate the correct neighbours.
- Saves data to the specified files.
- Is called by `System`.
- Returns `true` on success.
-4. Description
+4. Dependents
+ - `System`
+5. Dependencies
+ - `Drum`
+ - `DrumParameters`
+ - `DrumVariables`
+6. Description
- This class needs to be re-implemented whenever either `DrumParameters` or
`DrumVariables` changes.
- One should also implement a helper struct, as seen in `include/grabber.hpp`
@@ -435,7 +525,7 @@ the individual functions correctly to accomodate the correct neighbours.
- `f`: Force functional
- `sp`: System parameters
- `g`: Grabber
-2. Member functions
+3. Member functions
- `void simulate()`
- Runs a simulation with the set parameters.
- `void step()`
@@ -448,3 +538,7 @@ the individual functions correctly to accomodate the correct neighbours.
- Calls `grabber_t::save()`.
- `std::vector<value_t> get_matrix(matelecalc_t)`
- Returns the dynamic matrix as provided by the argument.
+4. Dependents
+ - None
+5. Dependencies
+ - All of them. Don't change this class before thinking a lot.
--
GitLab