Vadere-Components/Psychology-Layer.md

+One of our goals is to make pedestrian simulations more realistic. Most of the current locomotion models like the social force model or the optimal steps model only include physical aspects to navigate an agent through an environment.  For instance, obstacles repel an agent while targets attract agents. But, the key is to include also the psychological status of an agent in each simulation step. This layer represents the mental processes of perception and cognition of real humans and effects the behavior of an agent.
+
+Therefore, before agents are moved in Vadere by the locomotion layer, a perception and cognition step is executed which can affect the actual locomotion. See the following listing of Vadere's simulation loop:
+
+```java
+while (simulationIsRunning) {
+  ...
+  // Perception
+  perceptionModel.update(agents, stimuli);
+  ...
+  // Cognition
+  cognitionModel.update(agents);
+  ...
+  // Locomotion
+  locomotionModel.update(agents, time);
+   |
+   +-> if (agent.selfCategory == COOPERATIVE) {
+         Agent candidate = findSwapCandidate();
+         swapAgents(agent, candidate);
+       }
+  ...
+  time++;
+}
+```
+
+`perceptionModel` and `cognitionModel` are interfaces and can be set for each simulation run separately in the GUI, see following figure.
+
+![Vadere-GUI-PsychologyTab](uploads/54ba53dff66606b17cf71810a4d4cce8/Vadere-GUI-PsychologyTab.png)
+
+For instance, when using the `CooperativeCognitionModel`, agents do not block each other. Agents rather swap places with other agents to reach their target, see following figure.
+
+![Vadere-CooperativeCognitionModel-PsychologyEnabled](uploads/5fc7c905745557da2503e729973e4960/Vadere-CooperativeCognitionModel-PsychologyEnabled.png)
+
+## Perception Model
+
+The perception model can be influenced by environmental stimuli, see following figure.
+
+![Vadere-GUI-PerceptionTab](uploads/6647fb676092626a8435c6110e23f172/Vadere-GUI-PerceptionTab.png)
+
+Use following steps to add new stimuli to Vadere:
+
+1. Create a new class with stimulus attributes in the `VadereState/src/org/vadere/state/psychology/perception/types` package.
+2. In the class `VadereState/src/org/vadere/state/psychology/perception/types/Stimulus.java`, assign a name for the new stimulus. This name can then be entered in the "Psychology" tab of Vadere.
+3. Use an existing perception model like `SimplePerceptionModel` or implement your own and make the stimulus available for agents by using `agent.setMostImportantStimulus()`. On cognition layer, `agent.getMostImportantStimulus()` can be used to process this information further to set an agent's self category. This self category influences the motion of an agent on the locomotion layer. For instance, `SELF_CATEGORY.COOPERATIVE` causes agents to swap positions to reach a target.
+
+## References
+
+This psychology-inspired architecture was introduced after conducting an experiment with 69 students at the Munich University of Applied Sciences. The experiment results are available as journal preprint on arXiv: https://arxiv.org/abs/2005.12712
\ No newline at end of file