From 2ee5a3f43ba4dc42e1d920d8d6b86230a6d62384 Mon Sep 17 00:00:00 2001
From: Morgan Plain <morganjplain@gmail.com>
Date: Thu, 21 Dec 2023 03:04:41 +0100
Subject: [PATCH] add comments for force mechanics

---
 src/main/frontend/extensions/graph/pixi.cljs | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/src/main/frontend/extensions/graph/pixi.cljs b/src/main/frontend/extensions/graph/pixi.cljs
index 3fd333d66..8af8faca4 100644
--- a/src/main/frontend/extensions/graph/pixi.cljs
+++ b/src/main/frontend/extensions/graph/pixi.cljs
@@ -54,19 +54,34 @@
    :edge {:color "#A5B4FC"}})
 
 (defn layout!
+  "Node forces documentation can be read in more detail here https://d3js.org/d3-force"
   [nodes links link-dist]
   (let [nodes-count (count nodes)
         simulation (forceSimulation nodes)]
     (-> simulation 
         (.force "link"
+                ;; The link force pushes linked nodes together or apart according to the desired link distance. 
+                ;; The strength of the force is proportional to the difference between the linked nodes distance 
+                ;; and the target distance, similar to a spring force.
                 (-> (forceLink)
                     (.id (fn [d] (.-id d)))
                     (.distance link-dist)
                     (.links links)))
         (.force "charge"
+                ;; The many-body (or n-body) force applies mutually amongst all nodes. 
+                ;; It can be used to simulate gravity or electrostatic charge.
                 (-> (forceManyBody)
+                    ;; The minimum distance between nodes over which this force is considered. 
+                    ;; A minimum distance establishes an upper bound on the strength of the force between two nearby nodes, avoiding instability.
+                    (.distanceMin 1)
+                    ;; The maximum distance between nodes over which this force is considered.
+                    ;; Specifying a finite maximum distance improves performance and produces a more localized layout.
                     (.distanceMax (if (> nodes-count 500) 4000 600))
+                    ;; For a cluster of nodes that is far away, the charge force can be approximated by treating the cluster as a single, larger node.
+                    ;; The theta parameter determines the accuracy of the approximation
                     (.theta 0.5)
+                    ;; A positive value causes nodes to attract each other, similar to gravity, 
+                    ;; while a negative value causes nodes to repel each other, similar to electrostatic charge.
                     (.strength -600)))
         (.force "collision"
                 (-> (forceCollide)
@@ -75,6 +90,9 @@
         (.force "x" (-> (forceX 0) (.strength 0.02)))
         (.force "y" (-> (forceY 0) (.strength 0.02)))
         (.force "center" (forceCenter))
+        ;; The decay factor is akin to atmospheric friction; after the application of any forces during a tick, 
+        ;; each node’s velocity is multiplied by 1 - decay. As with lowering the alpha decay rate, 
+        ;; less velocity decay may converge on a better solution, but risks numerical instabilities and oscillation.
         (.velocityDecay 0.8))
     (reset! *simulation simulation)
     simulation))