Anticipation Velocity Model (AVM)

.gitignore

@@ -24,3 +24,9 @@ __pycache__/
 /dist/
 /jupedsim.egg-info/
 /docs/build
+
+# clangd cache
+/.cache/
+
+# compile_commands
+/compile_commands.json

docs/source/notebooks/index.rst

@@ -5,6 +5,7 @@ Notebooks
 .. toctree::
     :maxdepth: 1
 
+    model-comparison
     corner
     double-bottleneck
     journey

docs/source/notebooks/model-comparison.ipynb

@@ -0,0 +1 @@
+../../../notebooks/model-comparison.ipynb

docs/source/pedestrian_models/index.rst

@@ -7,6 +7,7 @@ models. Below is a list of all the models that are currently available. Please
 refer to the links in the respective section for a detailed discussion of the
 respective model.
 
+
 **************************
 Collision Free Speed Model
 **************************
@@ -44,6 +45,79 @@ available on `PedestrianDynamics`_.
 
 The original publication can be found at https://arxiv.org/abs/1512.05597
 
+**************************
+Anticipation Velocity Model
+**************************
+
+The anticipation velocity model (AVM) is a mathematical approach for pedestrian
+dynamics that prevents collisions through anticipatory behavior. The model divides
+anticipation into three components: situation perception, future prediction, and
+strategy selection.
+Building upon the collision-free speed model (CSM), AVM determines agent movement
+through exponential repulsion from nearby agents. Unlike CSM, the influence
+direction is orthogonal to the agent's desired direction.
+Repulsion strength is affected by agents within the perception field -
+specifically, those in the union of two half-planes where the agent moves or
+intends to move. Agents adjust their speed based on anticipated distance to the
+nearest neighbor in their headway, enabling navigation through congested areas
+without overlap.
+The model incorporates a reaction time factor to adjust the turning process rate
+from the current to the new direction.
+
+**Wall Influence**
+
+Walls are treated as gliding surfaces, meaning that agents adjust their movement
+to avoid collisions while maintaining smooth trajectories along wall boundaries.
+The influence of walls on an agent's movement is determined based on their distance
+to the wall and the direction of their movement.
+The following rules govern the behavior:
+
+1. **Critical Wall Distance**:
+   - A critical wall distance is defined as the sum of the agent's radius and
+     a configurable buffer distance (`wallBufferDistance`).
+   - If an agent comes within this critical distance to a wall,
+     their direction is adjusted to ensure a minimum distance is maintained.
+
+2. **Influence Start Distance**:
+   - An influence start distance is set at twice the critical wall distance to
+     allow for smoother adjustments as the agent approaches the wall.
+
+3. **Direction Adjustment**:
+   - When an agent is within the critical wall distance and moving toward the wall:
+     - The direction is projected parallel to the wall to ensure no penetration occurs.
+     - A small outward component is added to maintain the minimum distance from the wall.
+   - When an agent is between the critical wall distance and the influence start distance:
+     - If moving toward the wall, their direction is adjusted with a smooth transition
+       factor to gradually reduce components moving perpendicular to the wall.
+
+4. **Wall Direction Handling**:
+   - The agent's movement direction is decomposed into parallel and perpendicular
+     components relative to the wall surface.
+   - Adjustments are applied only to the perpendicular component, ensuring the parallel
+     component remains intact for smooth movement along the wall.
+
+In summary walls do not affect the speed of agents, only their direction.
+Agents glide along walls by adjusting their direction while maintaining the
+desired movement as much as possible. When necessary, the influence transitions smoothly
+as the agent moves closer to or farther from the wall.
+
+The anticipation velocity  model takes into account the length of the agent,
+which determines the required space for movement, and the maximum achievable
+speed of the agent. This simplified and computationally efficient model aims to
+mirror real-world pedestrian behaviors while maintaining smooth movement
+dynamics.
+
+The parameters of the anticipation velocity model can be defined per-agent.
+
+In :class:`~jupedsim.models.AnticipationVelocityModel` neighbor and wall
+parameters are per-agent parameters that can be set individually via
+:class:`~jupedsim.models.AnticipationVelocityModelAgentParameters` and can be
+changed at any time.
+
+
+The original publication can be found at https://doi.org/10.1016/j.trc.2021.103464
+
+
 ***********************************
 Generalized Centrifugal Force Model
 ***********************************

examples/example7_avm.py

@@ -0,0 +1,73 @@
+#! /usr/bin/env python3
+
+# Copyright © 2012-2024 Forschungszentrum Jülich GmbH
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+import pathlib
+import sys
+
+import jupedsim as jps
+from shapely import Polygon
+
+
+def main():
+    room1 = Polygon([(0, 0), (10, 0), (10, 10), (0, 10)])  # Room 1 (10m x 10m)
+    room2 = Polygon([(15, 0), (25, 0), (25, 10), (15, 10)])
+    width = 0.6
+    num_agents = 10
+    corridor = Polygon(
+        [
+            (10, 5 - width / 2),
+            (15, 5 - width / 2),
+            (15, 5 + width / 2),
+            (10, 5 + width / 2),
+        ]
+    )
+    geometry = room1.union(room2).union(corridor)
+    exit_polygon = Polygon([(24, 4.5), (25, 4.5), (25, 5.5), (24, 5.5)])
+    trajectory_file = "example_7.sqlite"
+    simulation = jps.Simulation(
+        model=jps.AnticipationVelocityModel(),
+        geometry=geometry,
+        trajectory_writer=jps.SqliteTrajectoryWriter(
+            output_file=pathlib.Path(trajectory_file)
+        ),
+    )
+
+    exit_id = simulation.add_exit_stage(exit_polygon)
+    journey = jps.JourneyDescription([exit_id])
+    journey_id = simulation.add_journey(journey)
+
+    start_positions = jps.distribute_by_number(
+        polygon=Polygon([(0, 0), (5, 0), (5, 10), (0, 10)]),
+        number_of_agents=num_agents,
+        distance_to_agents=0.5,
+        distance_to_polygon=0.2,
+    )
+
+    for position in start_positions:
+        simulation.add_agent(
+            jps.AnticipationVelocityModelAgentParameters(
+                journey_id=journey_id,
+                stage_id=exit_id,
+                position=position,
+                anticipation_time=0.5,
+                reaction_time=0.3,
+                wall_buffer_distance=0.05,
+            )
+        )
+
+    while simulation.agent_count() > 0 and simulation.iteration_count() < 3000:
+        try:
+            simulation.iterate()
+        except KeyboardInterrupt:
+            print("CTRL-C Received! Shutting down")
+            sys.exit(1)
+    print(
+        f"Simulation completed after {simulation.iteration_count()} iterations ({simulation.elapsed_time()} s)"
+    )
+    print(f"{trajectory_file = }")
+
+
+if __name__ == "__main__":
+    main()

examples/example8_headon_AVM.py

@@ -0,0 +1,62 @@
+#! /usr/bin/env python3
+
+# Copyright © 2012-2024 Forschungszentrum Jülich GmbH
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+import pathlib
+
+import jupedsim as jps
+from shapely import Polygon
+
+
+def main():
+    width = 2
+    length = 10
+    geometry = Polygon([(0, 0), (length, 0), (length, width), (0, width)])
+    exit_polygon = Polygon(
+        [(length - 0.5, 0), (length, 0), (length, width), (length - 0.5, width)]
+    )
+    trajectory_file = "headon_AVM.sqlite"
+    simulation = jps.Simulation(
+        model=jps.AnticipationVelocityModel(),
+        geometry=geometry,
+        trajectory_writer=jps.SqliteTrajectoryWriter(
+            output_file=pathlib.Path(trajectory_file)
+        ),
+    )
+
+    exit_id = simulation.add_exit_stage(exit_polygon)
+    journey = jps.JourneyDescription([exit_id])
+    journey_id = simulation.add_journey(journey)
+
+    start_positions = [(3, 0.5 * width), (0.5 * length, 0.5 * width)]
+    parameters = [
+        jps.AnticipationVelocityModelAgentParameters(
+            journey_id=journey_id,
+            stage_id=exit_id,
+            position=start_positions[0],
+            radius=0.2,
+            v0=1.2,
+        ),
+        jps.AnticipationVelocityModelAgentParameters(
+            journey_id=journey_id,
+            stage_id=exit_id,
+            position=start_positions[1],
+            radius=0.2,
+            v0=0.2,
+        ),
+    ]
+    for position, param in zip(start_positions, parameters):
+        simulation.add_agent(parameters=param)
+
+    while simulation.agent_count() > 0 and simulation.iteration_count() < 1000:
+        simulation.iterate()
+
+    print(
+        f"Simulation completed after {simulation.iteration_count()} iterations ({simulation.elapsed_time()} s)"
+    )
+    print(f">> {trajectory_file = }")
+
+
+if __name__ == "__main__":
+    main()

examples/example8_headon_CSM.py

@@ -0,0 +1,62 @@
+#! /usr/bin/env python3
+
+# Copyright © 2012-2024 Forschungszentrum Jülich GmbH
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+import pathlib
+
+import jupedsim as jps
+from shapely import Polygon
+
+
+def main():
+    width = 2
+    length = 10
+    geometry = Polygon([(0, 0), (length, 0), (length, width), (0, width)])
+    exit_polygon = Polygon(
+        [(length - 0.5, 0), (length, 0), (length, width), (length - 0.5, width)]
+    )
+    trajectory_file = "headon_CSM.sqlite"
+    simulation = jps.Simulation(
+        model=jps.CollisionFreeSpeedModel(),
+        geometry=geometry,
+        trajectory_writer=jps.SqliteTrajectoryWriter(
+            output_file=pathlib.Path(trajectory_file)
+        ),
+    )
+
+    exit_id = simulation.add_exit_stage(exit_polygon)
+    journey = jps.JourneyDescription([exit_id])
+    journey_id = simulation.add_journey(journey)
+
+    start_positions = [(3, 0.5 * width), (0.5 * length, 0.5 * width)]
+    parameters = [
+        jps.CollisionFreeSpeedModelAgentParameters(
+            journey_id=journey_id,
+            stage_id=exit_id,
+            position=start_positions[0],
+            radius=0.2,
+            v0=1.2,
+        ),
+        jps.CollisionFreeSpeedModelAgentParameters(
+            journey_id=journey_id,
+            stage_id=exit_id,
+            position=start_positions[1],
+            radius=0.2,
+            v0=0.2,
+        ),
+    ]
+    for position, param in zip(start_positions, parameters):
+        simulation.add_agent(parameters=param)
+
+    while simulation.agent_count() > 0 and simulation.iteration_count() < 1000:
+        simulation.iterate()
+
+    print(
+        f"Simulation completed after {simulation.iteration_count()} iterations ({simulation.elapsed_time()} s)"
+    )
+    print(f">> {trajectory_file = }")
+
+
+if __name__ == "__main__":
+    main()

libjupedsim/CMakeLists.txt

@@ -11,6 +11,7 @@ add_library(jupedsim_obj OBJECT
     src/build_info.cpp
     src/collision_free_speed_model.cpp
     src/collision_free_speed_model_v2.cpp
+    src/anticipation_velocity_model.cpp
     src/error.cpp
     src/generalized_centrifugal_force_model.cpp
     src/geometry.cpp
@@ -112,6 +113,7 @@ install(
         ${header_dest}/build_info.h
         ${header_dest}/collision_free_speed_model.h
         ${header_dest}/collision_free_speed_model_v2.h
+        ${header_dest}/anticipation_velocity_model.h
         ${header_dest}/error.h
         ${header_dest}/export.h
         ${header_dest}/generalized_centrifugal_force_model.h

libjupedsim/include/jupedsim/agent.h

@@ -2,6 +2,7 @@
 /* SPDX-License-Identifier: LGPL-3.0-or-later */
 #pragma once
 
+#include "anticipation_velocity_model.h"
 #include "collision_free_speed_model.h"
 #include "collision_free_speed_model_v2.h"
 #include "error.h"
@@ -116,6 +117,16 @@ JPS_Agent_GetSocialForceModelState(JPS_Agent handle, JPS_ErrorMessage* errorMess
 JUPEDSIM_API JPS_CollisionFreeSpeedModelV2State
 JPS_Agent_GetCollisionFreeSpeedModelV2State(JPS_Agent handle, JPS_ErrorMessage* errorMessage);
 
+/**
+ * Access Anticipation Velocity Model state.
+ * Precondition: Agent needs to use Anticipation Velocity Model
+ * @param handle of the agent to access.
+ * @param[out] errorMessage if not NULL: will be set to a JPS_ErrorMessage in case of an error.
+ * @return state or NULL on error
+ */
+JUPEDSIM_API JPS_AnticipationVelocityModelState
+JPS_Agent_GetAnticipationVelocityModelState(JPS_Agent handle, JPS_ErrorMessage* errorMessage);
+
 /**
  * Opaque type of an iterator over agents
  */