Anticipation Velocity Model (AVM)

CMakeLists.txt

@@ -224,7 +224,7 @@ add_subdirectory(python_bindings_jupedsim)
 # Code formatting
 ################################################################################
 if(UNIX AND WITH_FORMAT)
-    set(clang-format-version 15)
+    set(clang-format-version 18)
     find_program(CLANG_FORMAT
         NAMES
             clang-format-${clang-format-version}

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,47 @@ 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. Walls are treated as gliding surfaces:
+when an agent is within critical distance of a wall and moving toward it, their
+direction is projected parallel to the wall surface. 
+Movement calculation occurs in two steps: first, combining the desired direction
+with neighbor influences, then adjusting for wall interactions when necessary.
+Walls do not influence the speed of agents, only their direction.
+
+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,72 @@
+#! /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.8
+    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,
+            )
+        )
+
+    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
  */