GITBOOK-78: better diagrams

gitbook/manual/1.-create-and-modify-pattern/patterns.md

@@ -25,7 +25,7 @@ Photographs and diagrams of different rose windows with complex mullion geometri
 <figure><img src="../../.gitbook/assets/rose-windows.png" alt=""><figcaption><p> (a) Notre Dame de Mantes, France; (b) Notre Dame de Chartres, France (Photo by Holly Hayes); (c) Durham Cathedral, England (Photo by Carcharoth on Wikipedia); (d) Notre Dame de Paris, France (Photo by Ellen Brown); (e) Bisshop’s Eye of Lincoln Cathedral, England (Photo from Cornell University Library); (f) Sainte-Chapelle Paris, France.</p></figcaption></figure>
 
 {% hint style="warning" %}
-`Pattern` is a COMPAS [mesh](https://compas-dev.github.io/main/api/generated/compas.datastructures.Mesh.html#compas.datastructures.Mesh) object. A mesh datastructure is network of faces, where the connectivity of the faces are defined by halfedge adjacencies.&#x20;
+`Pattern` is a [COMPAS mesh](https://compas.dev/compas/latest/api/compas.datastructures.Mesh.html) object. A mesh datastructure is network of faces, where the connectivity of the faces are defined by halfedge adjacencies.&#x20;
 {% endhint %}
 
 ***

gitbook/manual/2.-define-boundary-conditions/boundary-conditions-2.md

@@ -2,12 +2,12 @@
 
 <table><thead><tr><th width="221"></th><th width="253"></th><th></th></tr></thead><tbody><tr><td><img src="../../.gitbook/assets/RV_boundaries (1).svg" alt="" data-size="original"></td><td><p><strong>Rhino command name</strong></p><p><code>RV_pattern_bnoundaries</code></p></td><td><p><strong>source file</strong></p><p><a href="../../../plugin/RV_pattern_boundaries.py"><code>RV_pattern_boundaries.py</code></a></p></td></tr></tbody></table>
 
-The treatment of the openings are very much dependent on the type of vault that is being investigated.  `RV_pattern_bnoundaries` enables users to relax the Pattern in a much more controlled way by defining the _sag_ value for each opening, which is calculated based on the percentage of the length of the opening. The $$q$$s for the boundary edges are automatically calculated based on the target _sag_ values, which are then used for the relaxation using the same force density method used in `RV_pattern_relax`. Default sag value of 10 is applied to each opening.&#x20;
+The treatment of the openings are very much dependent on the type of vault that is being investigated.  `RV_pattern_bnoundaries` enables users to relax the Pattern in a much more controlled way by defining the `sag` value for each opening, which is calculated based on the percentage of the length of the opening. The $$q$$s for the boundary edges are automatically calculated based on the target `sag` values, which are then used for the relaxation using the same force density method used in `RV_pattern_relax`. Default `sag` value of 10 is applied to each opening.&#x20;
 
 ***
 
 ### Sag
 
-Below are variations of a simple 10x10 grid pattern with different sag values applied to each opening. The sag values can be adjusted uniformly across all openings or varied individually for each one.
+Below are variations of a simple 10x10 grid pattern with different sag values applied to each opening. The `sag` values can be adjusted uniformly across all openings or varied individually for each one.
 
 <figure><img src="../../.gitbook/assets/RV_sag-examples.png" alt=""><figcaption></figcaption></figure>

gitbook/manual/diagrams.md

@@ -4,14 +4,12 @@
 | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
 | <img src="../.gitbook/assets/RV_FormDiagram (1).svg" alt="" data-size="original"> | <p><strong>Rhino command name</strong></p><p><code>RV_form</code></p> | <p><strong>source file</strong></p><p><a href="../../plugin/RV_form.py"><code>RV_form.py</code></a></p> |
 
-`FormDiagram` is the 2D projection of the thrust network. In RV2, a `FormDiagram` is represented by the mesh datastructure.&#x20;
+`FormDiagram` is the 2D projection of the `ThrustDiagram`. The boundary condition information, such as the support locations and loading conditions, is automatically inherited from the `Pattern`. Any edges of the pattern, of which both endpoints are supports are removed from the `FormDiagram`.&#x20;
 
-The boundary condition information, such as the support locations and loading conditions, is automatically inherited from the `Pattern`. Any edges of the pattern, of which both endpoints are supports are removed from the `FormDiagram`.&#x20;
-
-A `FormDiagram` is represented by the mesh datastructure.
+A `FormDiagram` is represented by the [COMPAS mesh datastructure](https://compas.dev/compas/latest/api/compas.datastructures.Mesh.html).
 
 <figure><img src="../.gitbook/assets/formdiagram_boundary-edges.jpg" alt=""><figcaption><p>Depending on how the support vertices are defined, corners of the Pattern are automatically processed during the creation of the <code>FormDiagram</code>.</p></figcaption></figure>
 
-<figure><img src="../.gitbook/assets/formdiagram_corners.jpg" alt=""><figcaption><p>Automatic removal of the corner supports of a quad mesh, which have edges at that support that are fully constrained.</p></figcaption></figure>
+<figure><img src="../.gitbook/assets/formdiagram_corners.jpg" alt=""><figcaption><p>Automatic removal of the corner supports of a quad grid mesh, which have edges at that support that are fully constrained.</p></figcaption></figure>
 
 <figure><img src="../.gitbook/assets/formdiagram_corners-triangle.jpg" alt=""><figcaption><p>Automatic removal of the corner supports in a tri mesh, which have edges at that support that are fully constrained.</p></figcaption></figure>

gitbook/manual/equilibrium.md

@@ -6,14 +6,18 @@
 
 Once the `FormDiagram` has been successfully created, the `ForceDiagram` can be created. When it is first created, the `ForceDiagram` is the dual diagram of the `FormDiagram`. 
 
-A `ForceDiagram` is represented by the mesh datastructure. 
+A `ForceDiagram` is represented by the [COMPAS mesh datastructure](https://compas.dev/compas/latest/api/compas.datastructures.Mesh.html). 
 
 ***
 
 ## Centroidal Dual
 
-The Force Diagram is the dual of the Form Diagram, in the sense that both diagrams have the same number of edges and that vertices in one diagram correspond to faces in the other, and vice versa.
+The `ForceDiagram` is the topological dual of the `FormDiagram`, in the sense that both diagrams have the same number of edges and that vertices in one diagram correspond to faces in the other, and vice versa.
 
-Initially, the Force Diagram is created as the "centroidal dual" of the Form Diagram. This means that the geometry of the Force Diagram is defined by placing its vertices at the centroids of their corresponding faces in the Form Diagram.
+Initially, the `ForceDiagram` is created as the "centroidal dual" of the `FormDiagram`. This means that the geometry of the Force Diagram is defined by placing its vertices at the centroids of their corresponding faces in the `FormDiagram`.
 
-<figure><img src="../.gitbook/assets/forcediagram-dual.jpg" alt=""><figcaption><p>The initial form and force diagrams are topologically dual, but not yet reciprocal</p></figcaption></figure>
+
+
+<figure><img src="../.gitbook/assets/RV_dual-diagram.png" alt=""><figcaption><p><code>ForceDiagram</code> (rigiht) is created as the "centroidal dual" of the <code>FormDiagram</code> (left).</p></figcaption></figure>
+
+<figure><img src="../.gitbook/assets/RV_dual-diagram_edges.png" alt=""><figcaption><p>The initial form and force diagrams are topologically dual, but not yet reciprocal. Here, the corresponding dual edges are highlighted for an arbitrary node.</p></figcaption></figure>

gitbook/manual/horizontal-equilibrium.md

@@ -4,58 +4,48 @@
 | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
 | <img src="../.gitbook/assets/RV_horizontal-eq (1).svg" alt="" data-size="original"> | <p><strong>Rhino command name</strong></p><p><code>RV_tna_horizontal</code></p> | <p><strong>source file</strong></p><p><a href="../../plugin/RV_tna_horizontal.py"><code>RV_tna_horizontal.py</code></a></p> |
 
-This function geometrically reconfigures the the edges of the ForceDiagram, such that the corresponding edges of the FormDiagram and Forcediagram become parallel (in the conventional graphic statics sense), or perpendicular (the 90° rotated, RhinoVAULT convention). The resulting ForceDiagram and FormDiagram are reciprocal where the two diagrams are topological duals of the other and all pairs of corresponding edges are parallel (within tolerance).
-
-***
-
-## Reciprocal Diagrams
-
-In order for the Form and Force Diagram to describe the distribution of horizontal thrust in a three-dimensional network of compression forces in equilibrium with vertical loads applied to its nodes, they need to be not only dual, but also reciprocal.&#x20;
-
-Two diagrams are reciprocal if they are dual, and if their corresponding edges are at a constant angle with each other. Typically, corresponding edges are required to be parallel, or perpendicular, but any other constant angle is sufficient as well.
-
-In RhinoVAULT, the Form and Force Diagram are considered reciprocal if corresponding edges are perpendicular.
+`RV_tna_horizontal` geometrically reconfigures the the edges of the `ForceDiagram`, such that the corresponding edges of the `FormDiagram` and `ForceDiagram` become parallel to each another (in the conventional graphic statics sense), or perpendicular (the 90° rotated, RhinoVAULT convention). The resulting `ForceDiagram` and `FormDiagram` are _reciprocal_ when the two diagrams are topological duals of the other and all pairs of corresponding edges are parallel (within tolerance).
 
 <figure><img src="../.gitbook/assets/forcediagram-reciprocal.jpg" alt=""><figcaption><p>After horizontal equilibrium has been found, the form and force diagrams are now reciprocal.</p></figcaption></figure>
 
 ***
 
 ## Horizontal Forces
 
-Once the Form and Force Diagram are reciprocal they describe the horizontal equilibrium of the corresponding three-dimensional force network. The edges of the Form Diagram define the directions and points of application of the forces, whereas the edges of the Force Diagram define the distribution of force magnitudes along those directions.
-
-The magnitudes of horizontal forces are equal to the lengths of the edges in the Force Diagram, multiplied with a scaling factor.&#x20;
+Once the `FormDiagram` and `ForceDiagram` are reciprocal, they describe the horizontal equilibrium of the corresponding three-dimensional force network. The edges of the `FormDiagram` define the directions and points of application of the forces, whereas the edges of the `ForceDiagram` define the distribution of force magnitudes along those directions. The magnitudes of horizontal forces are equal to the lengths of the edges in the `ForceDiagram`, multiplied with a scaling factor.&#x20;
 
 ***
 
 ## Algorithm Parameters
 
 ### Alpha
 
-In RhinoVAULT, horizontal equilibrium is computed by parallelising the edges of the Form and Force Diagram to corresponding target vectors. These target vectors are defined as the weighted average of the vectors of corresponding edge pairs. Therefore, the most important parameter for the calculation of horizontal equilibrium in RV2 is `alpha`, which is the weighting factor for the calculation of the target vectors.
-
-If `alpha = 100`, the target vectors are completely defined by the vectors of the edges of the Form Diagram. This means that only the geometry of the Force Diagram will be updated to achieve horizontal equilibrium. This is the default.
-
-If `alpha = 0`, the target vectors are completely defined by the edges of the force diagram. Therefore only the Form Diagram will be updated.
+In RhinoVAULT, horizontal equilibrium is computed by parallelising the edges of the Form and Force Diagram to corresponding target vectors. These target vectors are defined as the weighted average of the vectors of corresponding edge pairs. Therefore, the most important parameter for the calculation of horizontal equilibrium in RhinoVAULT is `alpha`, which is the weighting factor for the calculation of the target vectors.
 
-For all other values, the target vectors are calculated using the following formula:
+If `alpha = 100`, the target vectors are completely defined by the vectors of the edges of the `FormDiagram`. This means that only the geometry of the `ForceDiagram` will be updated to achieve horizontal equilibrium. This is the default. If `alpha = 0`, the target vectors are completely defined by the edges of the `ForceDiagram`. Therefore only the `FormDiagram` will be updated. For all other values, the target vectors are calculated using the following formula:
 
 $$
 t_i = \alpha \cdot \hat{e}_{i, form} + (1 - \alpha) \cdot \hat{e}_{i, force}
 $$
 
-Note that using `alpha` efficiently requires a bit of practice and experience. Since the Form Diagram defines the intended  layout of horizontal forces and RV2 has many tools for designing force layouts that provide a good starting point for form finding explorations, it is usually a good idea to start with `alpha = 100`. However, once you have the horizontal equilibrium under control, playing around with lower `alpha` values can have a significant influence on finding nicely balanced force distributions.
+Note that using different values of `alpha` requires a bit of practice and experience. Since the `FormDiagram` defines the intended  layout of horizontal forces and RhinoVAULT has many functionalities for designing force layouts that provide a good starting point for form finding explorations, it is usually a good idea to start with `alpha = 100`. However, once you have the horizontal equilibrium under control, playing around with lower `alpha` values can have a significant influence on finding nicely balanced force distributions.
 
 ### Iterations
 
-Computing horizontal equilibrium is an iterative process. The default number of iterations is `100`. For sensible force layouts, this value should go a long way. However, there are many cases in which more iterations are required. For example, if the Form Diagram has multiple open/unsupported edges, and especially if those edges have a low "sag" value, more iterations will typically be required to reduce all angle deviations between corresponding edges to less than 5 degrees.
+Computing horizontal equilibrium is an iterative process. The default number of `iterations` is 100. For sensible force layouts, a horizontal equilibrium can be found in less `iterations`. However, there are many cases in which more `iterations` are required. For example, if the `FormDiagram` has multiple open/unsupported edges, and especially if those edges have a high `sag` value, more `iterations` will typically be required to reduce all angle deviations between corresponding edges to less than the default tolerance of 5 degrees.
 
-Computing horizontal equilibrium is quite fast. Therefore, don't hesitate to set the number of iterations to `1000` or more if the need arises. However, don't go completely overboard either (`10000` iterations is quite excessive in most cases), because the calculation has no stoppage criterion, since it tends to be more computationally expensive to check for convergence than to just run all the requested iterations.
+Computing horizontal equilibrium is quite fast. Therefore, don't hesitate to set the number of `iterations` to 1000 or more if the need arises. However, don't go completely overboard either (10000 `iterations` is quite excessive in most cases), because the calculation has no stoppage criterion, since it tends to be more computationally expensive to check for convergence than to just run all the requested `iterations`.
 
 Furthermore, resolving all angle deviations is not an absolute requirement, and is in many cases unnecessary. For example, the angle deviations between very short edges tend to be quite persistent as they are dominated by edges with (much) longer lengths during the calculation process. Since short edges in the Force Diagram also represent (relatively) small horizontal forces, these deviations can often be ignored.
 
+{% hint style="warning" %}
+`RV_tna_horizontal` does not have a termination criteria. It will always run the number of `iterations` that has been defined.
+{% endhint %}
+
 ### Refreshrate
 
-The iterations of the horizontal equilibrium calculation process is dynamically visualised. The rate at which the diagrams are updated is controlled by the refreshrate. The default value is `10`, which means that the diagrams are updated every 10 iterations.
+The `iterations` of the horizontal equilibrium calculation process is dynamically visualized. The rate at which the `iterations` are visualized is controlled by the `refreshrate`. The default value is 5, which means that the diagrams are updated every 5 iterations.
+
+For large diagrams the dynamic visualization slows down the calculations a little bit. In situations where a high numbers of `iterations` (> 1000) is required, it is advisable to set the `refreshrate` to a higher value. For example, if the number of `iterations` is 1000, then a refresh rate of 50 seems more appropriate.
 
-For large diagrams the dynamic visualisation slows down the calculations a little bit. In these cases, and/or for high numbers of iterations (`> 1000`), it is therefore advisable to set the refreshrate to a higher value. For example, if the number of iterations is `1000`, then a refresh rate of `100` seems more appropriate.
+<figure><img src="../.gitbook/assets/RV_horizontal_sequence.gif" alt=""><figcaption><p>Animation of iterations in<code>RV_tna_horizontal</code> for a simple pattern.</p></figcaption></figure>