perf(flocking): improve tests

Author: tolstenko

artificialintelligence/assignments/flocking/README.md

@@ -1,39 +1,19 @@
 # Flocking agents behavior assignment
 
-You are in charge to implement some functions to make some AI agents flock together in a game.
+You are in charge to implement some functions to make some AI agents flock together in a game. After finishing it, uou will be one step further to render it in a game engine, and start making reactive NPCs and enemies. You will learn all the basics concepts needed to code and customize your own AI behaviors.
 
 ## What is flocking?
 
 Flocking is a behavior that is observed in birds, fish and other animals that move in groups. It is a very simple behavior that can be implemented with a few lines of code. The idea is that each agent will try to move towards the center of mass of the group (cohesion), and will try to align its velocity with the average velocity of the group (AKA alignment). In addition, each agent will try to avoid collisions with other agents (AKA avoidance).
 
-In order to calculate the new position of the agent, we have to use some phisics formulas such as:
-
-- $ \overrightarrow{F} = K_c*\hat{F_c} + K_s*\hat{F_s} + K_a*\hat{F_a} $
-- $ \overrightarrow{V_{new}} = \overrightarrow{V_{cur}}+\frac{\overrightarrow{F}}{m} \cdot \Delta t $
-- $ P_{new} = P_{cur}+\overrightarrow{V_{cur}} \cdot \Delta t + \frac{\overrightarrow{F}}{m} \cdot \frac{\Delta t^2}{2} $
-
-!!! note "Notation"
+!!! note "Formal Notation Review"
 
     - $\overrightarrow{F}$ means a vector $F$ that has components. In a 2 dimensional vector it will hold $F_x$ and $F_y$. For example, if $F_x = 1$ and $F_y = 1$, then $\overrightarrow{F} = (1,1)$
     - $\overrightarrow{P_1P_2}$ means the vector that goes from $P_1$ to $P_2$. It is the same as $P_2-P_1$
     - The modulus notation means the length (magnitude) of the vector. $|\overrightarrow{F}| = \sqrt{F_x^2+F_y^2}$ For example, if $\overrightarrow{F} = (1,1)$, then $|\overrightarrow{F}| = \sqrt{2}$
     - The hat ^ notation means the unitary vector of the vector. $\hat{F} = \frac{\overrightarrow{F}}{|\overrightarrow{F}|}$ For example, if $\overrightarrow{F} = (1,1)$, then $\hat{F} = (\frac{1}{\sqrt{2}},\frac{1}{\sqrt{2}})$
     - The hat notation over 2 points means the unit vector that goes from the first point to the second point. $\widehat{P_1P_2} = \frac{\overrightarrow{P_1P_2}}{|\overrightarrow{P_1P_2}|}$ For example, if $P_1 = (0,0)$ and $P_2 = (1,1)$, then $\widehat{P_1P_2} = (\frac{1}{\sqrt{2}},\frac{1}{\sqrt{2}})$
 
-Where:
-
-- $\overrightarrow{F}$ is the force applied to the agent; 
-- $\overrightarrow{V}$ is the velocity of the agent;
-- $P$ is the position of the agent; 
-- $m$ is the mass of the agent;
-- $\Delta t$ is the time frame (1/FPS); 
-- $cur$ is the current value of the variable; 
-- $new$ is the new value of the variable to be used in the next frame.
-
-!!! note
-
-    For simplicity, we are going to assume that the mass of all agents is 1, and the time frame is 0.017s.
-
 It is your job to implement those 3 behaviors following the ruleset below:
 
 ### Cohesion
@@ -56,6 +36,10 @@ F_c = \begin{cases}
 \end{cases}
 $$
 
+!!! tip
+
+    Note that the maximum magnitude of $F_c$ is 1. Inclusive. This value can be multiplied by a constant $K_c$ to increase or decrease the cohesion force to looks more appealing.
+
 ### Separation
 
 It will move the agent away from other agents when they get too close.
@@ -66,27 +50,75 @@ It will move the agent away from other agents when they get too close.
 4. Clamp the force to a maximum value of $F_{Smax}$.
 
 $$
-F_s = \sum_{i=0}^{n-1} \begin{cases}
+\overrightarrow{F_s} = \sum_{i=0}^{n-1} \begin{cases}
       0 & \text{if } |\overrightarrow{AN_i}| = 0 \\
       \widehat{AN_i} / |\overrightarrow{AN_i}| & \text{if } 0 < |\overrightarrow{AN_i}| \leq r_s \\
     0 & \text{if } |\overrightarrow{AN_i}| > r_s
 \end{cases}
 $$
 
-The force will go near infinite when the distance between the agent and the neighbor is 0. To avoid this, after accumulating all the influences from every neighbor, the force will be clamped to a maximum value of $F_{Smax}$.
+!!! tip
+
+    Here you can see that if we have more than one neighbor and one of them is way too close, the force will be very high and make the influence of the other neighbors irrelevant. This is the expected behavior.
+
+The force will go near infinite when the distance between the agent and the neighbor is 0. To avoid this, after accumulating all the influences from every neighbor, the force will be clamped to a maximum magnitude of $F_{Smax}$.
+
+$$
+\overrightarrow{F_{s}} = \begin{cases} 
+    \overrightarrow{F_s} & \text{if } |\overrightarrow{F_s}| \leq F_{Smax} \\
+    \frac{\overrightarrow{F_s}}{|\overrightarrow{F_s}|} * F_{Smax} & \text{if } |\overrightarrow{F_s}| > F_{Smax}
+\end{cases}
+$$
+
+!!! tip
+
+    - You can implement those two math together, but it is better to isolate in two steps to make it easier to understand and debug.
+    - This is not an averaged force like the cohesion force, it is a sum of forces. So, the maximum magnitude of the force can be higher than 1.
 
 ### Alignment
 
 It is the force that will align the velocity of the agent with the average velocity of the group.
 
 1. The neighbors of an agent are all the agents that are within the alignment radius of the agent, including itself;
-2. Compute the average velocity of the group ($V_{avg}$);
+2. Compute the average velocity of the group ($\overrightarrow{V_{avg}}$);
 3. Compute the force that will move the agent towards the average velocity ($F_{alignment}$);
 
 $$
 V_{avg} = \frac{\sum_{i=0}^{n-1} V_i}{n}
 $$
 
+## Behavior composition
+
+The force composition is made by a weighted sum of the influences of those 3 behaviors. This is the way we are going to work, this is not the only way to do it, nor the more correct. It is just a way to do it. 
+
+- $ \overrightarrow{F} = K_c*\overrightarrow{F_c} + K_s*\overrightarrow{F_s} + K_a*\overrightarrow{F_a} $  `This is a weighted sum!`
+- $ \overrightarrow{V_{new}} = \overrightarrow{V_{cur}} + \overrightarrow{F} \cdot \Delta t $  `This is a simplification!`
+- $ P_{new} = P_{cur}+\overrightarrow{V_{new}} \cdot \Delta t $  `This is an approximation!`
+
+!!! warning
+
+    A more precise way for representing the new position would be to use full equations of motion. But given timestep is usually very small and it even squared, it is acceptable to ignore it. But here they are anyway, just dont use them in this assignment:
+
+    - $ \overrightarrow{V_{new}} = \overrightarrow{V_{cur}}+\frac{\overrightarrow{F}}{m} \cdot \Delta t $
+    - $ P_{new} = P_{cur}+\overrightarrow{V_{cur}} \cdot \Delta t + \frac{\overrightarrow{F}}{m} \cdot \frac{\Delta t^2}{2} $
+
+Where:
+
+- $\overrightarrow{F}$ is the force applied to the agent;
+- $\overrightarrow{V}$ is the velocity of the agent;
+- $P$ is the position of the agent;
+- $m$ is the mass of the agent, here it is always 1;
+- $\Delta t$ is the time frame (1/FPS);
+- $cur$ is the current value of the variable;
+- $new$ is the new value of the variable to be used in the next frame.
+
+The $\overrightarrow{V_{new}}$ and $P_{new}$ are the ones that will be used in the next frame and you will have to print to the console at the end of every single frame.
+
+!!! note
+
+    - For simplicity, we are going to assume that the mass of all agents is 1.
+    - In a real game simulation, it would be nice to apply some friction to the velocity of the agent to make it stop eventually or just clamp it to prevent the velocity get too high. But, for simplicity, we are going to ignore it.
+
 ## Input
 
 The input consists in a list of parameters followed by a list of agents. The parameters are:
@@ -109,6 +141,25 @@ Every agent is represented by 4 values in the same line, separated by a space:
 
 After reading the agents data, the program should read the time frame ($\Delta t$), simulate the agents and then output the new position of the agents in the same sequence and format it was read. The program should keep reading the time frame and simulating the agents until the end of the input.
 
+### Input Example
+
+In this example we are going to test only the cohesion behavior. The input is composed by the parameters and 2 agents. 
+
+```text
+1.000 0.000 0.000 0.000 1.000 0.000 0.000 2
+0.000 0.500 0.000 0.000
+0.000 -0.500 0.000 0.000
+0.010
+EOF
+```
+
 ## Output
 
+The expected output are the position and velocity for each simulation step after the time frame. After printing each simulation step, the program should wait for the next time frame and then simulate the next step.
+
+```text
+0.000 0.490 0.000 -0.010
+0.000 -0.490 0.000 0.010
+```
+
 ## Test cases