Inlining + Reorganization + Roofline

docs/Overview_Formulas_Variables.md

@@ -0,0 +1,194 @@
+# Overview — Formulas & Variables
+
+As a reference the paper was used (9805244v1.pdf)
+
+## 1. Variables
+ 
+### Per pedestrian $\alpha$
+ 
+| Paper | Code | Type | Meaning | Ref |
+|---|---|---|---|---|
+| $r_\alpha$ | `curr_pos` | `Vector2d` | position |  |
+| $v_\alpha$ | `curr_vel` | `Vector2d` | actual velocity (capped) | |
+| $w_\alpha$ | `w` | `Vector2d` | preferred velocity (integrates force) |  |
+| $e_\alpha$ | `e` | `Vector2d` | desired direction, unit vector | |
+| $r_\alpha^k$ | `destination` | `Vector2d` | next destination |  |
+| $v_\alpha^0$ | `desired_v0` | `double` | desired speed | |
+| $v_{\max,\alpha}$ | `v_max` | `double` | maximum speed $= 1.3 \cdot v_\alpha^0$ |  |
+| $F_\alpha$ | `f_i` | `Vector2d` | total force accumulator |  |
+
+ 
+### Global / scene
+ 
+| Paper | Code | Meaning | Ref |
+|---|---|---|---|
+| $n_p$ | `n_p` | number of pedestrians (CLI arg 1) |  |
+| $n_{\text{iter}}$ | `n_iter` | number of timesteps (CLI arg 2) | |
+| — | `BOARD_LENGTH` | walkway length, x-axis (50 m) ||
+| — | `BOARD_WIDTH` | walkway width, y-axis (10 m) | |
+| $B$ | `Obstacle` | line segment (start, end) | |
+ 
+### Constants
+ 
+| Paper | Code | Value | Unit | Ref |
+|---|---|---|---|---|
+| $\tau_\alpha$ | `tau_alpha` | 0.5 | s | |
+| $V_{\alpha\beta}^0$ | `V0_AB` | 2.1 | m²/s² | |
+| $\sigma$ | `SIGMA` | 0.3 | m ||
+| $U_{\alpha B}^0$ | `U0_AB` | 10.0 | m²/s² |  |
+| $R$ | `R` | 0.2 | m |  |
+| $c$ | `c` | 0.5 | — |  |
+| $\varphi$ | `phi` | 45 | degree ($2 \varphi = 90$) | |
+| $\Delta t$ | `delta_t` | 2 | s (look-ahead, used in $b$) ||
+| — | `dt` | 0.2 | s (Euler integration step) |  |
+
+
+## 2. Formulas
+ 
+### 2.1 Desired direction — Eq. 1 (p. 4)
+ 
+$$
+e_\alpha = \frac{r_\alpha^k - r_\alpha}{\| r_\alpha^k - r_\alpha \|}
+$$
+ 
+### 2.2 Acceleration toward desired velocity — Eq. 2 (p. 4)
+ 
+$$
+F_\alpha^0 = \frac{v_\alpha^0 \cdot e_\alpha - v_\alpha}{\tau_\alpha}
+$$
+ 
+Uses **actual** velocity $v_\alpha$.
+ 
+### 2.3 Pedestrian–pedestrian potential & force — Eq. 3 (p. 4), Eq. 13 (p. 7)
+ 
+$$
+V_{\alpha\beta}(b) = V_{\alpha\beta}^0 \cdot \exp\!\left(-\frac{b}{\sigma}\right)
+$$
+ 
+$$
+f_{\alpha\beta} = -\nabla_{r_{\alpha\beta}} V_{\alpha\beta}(b)
+= \frac{V_{\alpha\beta}^0}{\sigma} \cdot \exp\!\left(-\frac{b}{\sigma}\right) \cdot \nabla b
+$$
+
+### 2.4 Elliptical $b$ — Eq. 4 (p. 5)
+ 
+$$
+r_{\alpha\beta} = r_\alpha - r_\beta
+$$
+ 
+$$
+s_\beta = v_\beta \cdot \Delta t
+
+$$
+
+ 
+$$
+2b = \sqrt{\left(\| r_{\alpha\beta} \| + \| r_{\alpha\beta} - s_\beta \cdot e_\beta \|\right)^2 - s_\beta^2}
+$$
+ 
+Gradient (derived from Eq. 4, not given explicitly in paper):
+ 
+$$
+\nabla b = \frac{\| r_{\alpha\beta} \| + \| r_{\alpha\beta} - s_\beta \, e_\beta \|}{4b}
+\left(
+  \frac{r_{\alpha\beta}}{\| r_{\alpha\beta} \|}
+  + \frac{r_{\alpha\beta} - s_\beta \, e_\beta}{\| r_{\alpha\beta} - s_\beta \, e_\beta \|}
+\right)
+$$
+
+
+### 2.5 Border potential & force — Eq. 5 (p. 5), Eq. 13 (p. 7)
+ 
+$$
+U_{\alpha B}\!\left(\| r_{\alpha B} \|\right) = U_{\alpha B}^0 \cdot \exp\!\left(-\frac{\| r_{\alpha B} \|}{R}\right)
+$$
+ 
+$$
+f_{\alpha B} = \frac{U_{\alpha B}^0}{R} \cdot \exp\!\left(-\frac{\| r_{\alpha B} \|}{R}\right) \cdot \frac{r_{\alpha B}}{\| r_{\alpha B} \|}
+$$
+ 
+where $r_{\alpha B} = r_\alpha - r_B^\alpha$, and $r_B^\alpha$ is the nearest point of border $B$ to $\alpha$.
+ 
+### 2.6 Perception weight — Eq. 7 (p. 6)
+ 
+$$
+w(e,\, f) =
+\begin{cases}
+1 & \text{if } e \cdot f \geq \| f \| \cos\varphi \\
+c & \text{otherwise}
+\end{cases}
+$$
+ 
+### 2.7 Weighted force terms — Eq. 8 (p. 6) + team convention
+ 
+$$
+F_{\alpha\beta} = w(e_\alpha,\; -f_{\alpha\beta}) \cdot f_{\alpha\beta}
+$$
+ 
+$$
+F_{\alpha B} = w(e_\alpha,\; -f_{\alpha B}) \cdot f_{\alpha B}
+\qquad \text{(team convention; not explicit in paper)}
+$$
+ 
+> **Note:** Paper Eq. 8 only defines $w$ weighting for ped–ped $F_{\alpha\beta}$; applying it to border $F_{\alpha B}$ is our extension. (Reason see page 6, top: "However, the formulas above for attractive and repulsive effects only hold for situations that are perceived in the desired direction e_alpha(t) of motion.")
+
+ 
+### 2.8 Total force — Eq. 9 (p. 6), no attractors (Eq. 6) / fluctuations
+ 
+$$
+F_\alpha = F_\alpha^0 + \sum_\beta F_{\alpha\beta} + \sum_B F_{\alpha B}
+$$
+ 
+> Paper Eq. 9 also includes attractor term $\sum_i F_{\alpha i}$ (Eq. 6, p. 5) and Eq. 10 adds fluctuations; both omitted here per team convention.
+ 
+### 2.9 Speed cap — Eq. 12 (p. 7)
+ 
+$$
+g\!\left(\frac{v_{\max}}{\| w \|}\right) =
+\begin{cases}
+1 & \text{if } \| w \| \leq v_{\max} \\[4pt]
+\dfrac{v_{\max}}{\| w \|} & \text{otherwise}
+\end{cases}
+$$
+ 
+### 2.10 Equations of motion — Eq. 10 (p. 6), Eq. 11 (p. 7)
+ 
+$$
+\frac{dw_\alpha}{dt} = F_\alpha
+$$
+ 
+$$
+v_\alpha = w_\alpha \cdot g\!\left(\frac{v_{\max}}{\| w_\alpha \|}\right)
+$$
+ 
+$$
+\frac{dr_\alpha}{dt} = v_\alpha
+$$
+ 
+## 3. One Euler timestep (per pedestrian)
+ 
+Discretisation of Eq. 10–11; not given explicitly in paper.
+ 
+$$
+F_\alpha \leftarrow F_\alpha^0(v_\alpha,\, e_\alpha) + \sum_\beta F_{\alpha\beta} + \sum_B F_{\alpha B}
+$$
+ 
+$$
+w_\alpha^{\text{new}} \leftarrow w_\alpha + F_\alpha \cdot dt
+$$
+ 
+$$
+v_\alpha^{\text{new}} \leftarrow w_\alpha^{\text{new}} \cdot g\!\left(\frac{v_{\max}}{\| w_\alpha^{\text{new}} \|}\right)
+$$
+ 
+$$
+r_\alpha^{\text{new}} \leftarrow r_\alpha + v_\alpha^{\text{new}} \cdot dt
+$$
+ 
+$$
+e_\alpha^{\text{new}} \leftarrow \frac{r_\alpha^k - r_\alpha^{\text{new}}}{\| r_\alpha^k - r_\alpha^{\text{new}} \|}
+$$
+ 
+> **Convention:** force pass over all $\alpha$ first, integration pass second.
+>
+