Update documentation

docs/source/concepts/routing.rst

@@ -42,6 +42,11 @@ When a stage is reached, the agent will wait for its completion and then continu
 A stage may already count as completed when the stage is reached or when some condition is fulfilled.
 The various types of stages will be explained below.
 
+.. note::
+
+    All stages added to the simulation need to be inside the walkable area.
+    This needs to be uphold when the geometry is changed.
+
 Waypoint
 ^^^^^^^^
 
@@ -196,8 +201,6 @@ In the following, you can see how to add a waiting set to a simulation and how t
 Journeys
 --------
 
-Multiple stages can be combined into what in *JuPedSim* is called a Journey.
-
 For creating more complex routes in *JuPedSim* multiple stages can be combined to a so called Journey.
 
 For example:
@@ -264,6 +267,7 @@ After this, the cycle restarts with the first stage.
     :align: center
 
 To create a round-robin transition as described above, you can follow these steps:
+
 .. code-block:: python
 
     journey.set_transition_for_stage(

docs/source/conf.py

@@ -74,6 +74,9 @@
 def skip_submodules(app, what, name, obj, skip, options):
     if what == "module":
         skip = True
+    if what == "method":
+        if name.endswith("as_native"):
+            skip = True
     return skip
 
 

notebooks/corner.ipynb

@@ -16,6 +16,8 @@
    "source": [
     "# Movement around Corners\n",
     "\n",
+    "This notebook can be directly downloaded {download}`here <./corner.ipynb>` to run it locally.\n",
+    "\n",
     "In the following we'll investigate the movement of pedestrians around corners. When pedestrians walk around corners they are expected to slow down and take a path that is close to the corner. According to RiMEA Test 6 [1] a scenario is configured where **20 agents** move towards a **corner** at which they should turn to the left.\n",
     "\n",
     "Let's begin by importing the required packages for our simulation:"
@@ -351,6 +353,16 @@
     "As expected the agents choose the shortest path and approach the corner in a funnel-shaped formation. Agents moving closer to the corner become slower than agents at the edge of the crowd who choose a longer path around the corner."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "d67d3ca7",
+   "metadata": {},
+   "source": [
+    "# Download\n",
+    "\n",
+    "This notebook can be directly downloaded {download}`here <./corner.ipynb>` to run it locally."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "a4c85934",

notebooks/double-bottleneck.ipynb

@@ -13,6 +13,8 @@
    "source": [
     "# Movement through Bottlenecks\n",
     "\n",
+    "This notebook can be directly downloaded {download}`here <./double-bottleneck.ipynb>` to run it locally.\n",
+    "\n",
     "In this following, we'll investigate the movement of a crowd through **two successive bottlenecks** with a simulation. We expect that a jam occurs at the first bottleneck but not at the second one since the flow is considerably reduced by the first bottleneck.\n",
     "\n",
     "For this purpose, we'll setup a simulation scenario according to the RiMEA Test 12 [1] and analyse the results with pedpy to inspect the density and flow. After that we'll vary the width of the bottlenecks and investigate the effects on the movement.\n",
@@ -817,6 +819,16 @@
     "The results show: the smaller the width of the bottleneck, the smaller the flow as it takes longer for all 150 agents to enter the first bottleneck."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "0ef428ce",
+   "metadata": {},
+   "source": [
+    "# Download\n",
+    "\n",
+    "This notebook can be directly downloaded {download}`here <./double-bottleneck.ipynb>` to run it locally."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "79c725d7-c79b-4e83-a432-a52a8c67f012",

notebooks/getting_started.ipynb

@@ -212,8 +212,9 @@
     "The next step is to provide the initial positions of the agents in the simulation. \n",
     "*JuPedSim* provides different helper functions to automatically distribute the agents:\n",
     "\n",
-    "- distribute a given number of agents inside a polygon\n",
-    "- distribute agents by a given density inside a polygon\n",
+    "- distribute a given number of agents inside a polygon (see {func}`~jupedsim.distribute_by_number`)\n",
+    "- distribute agents by a given density inside a polygon (see {func}`~jupedsim.distribute_by_density`)\n",
+    "- ... (more methods can be found in the [API reference](/api/jupedsim/index), the names start with `distribute`)\n",
     "\n",
     "However, as we want to compare our simulation to the real-life experimental data, the agents in the simulation will start at the same positions as the pedestrians in the experiment. \n",
     "So we load the trajectory from the experiment and extract the locations at frame 0, which is the start of the experiment."
@@ -252,7 +253,7 @@
     "To use it in *JuPedSim* we need to state, that we will use this model in the creation of the simulation object.\n",
     "\n",
     "We also need to provide the previously defined geometry and the output file, where the resulting trajectories will be stored. \n",
-    "Here, we will use the built-in `SqliteTrajectoryWriter`, which will write the results as a `sqlite`-database."
+    "Here, we will use the built-in {class}`~jupedsim.SqliteTrajectoryWriter`, which will write the results as a `sqlite`-database."
    ]
   },
   {
@@ -283,7 +284,7 @@
     "After we defined the simulation we need to add a goal, which the agents should target. \n",
     "As we already defined the exit polygon above, we can add it to the simulation as a stage.\n",
     "After adding the exit to the simulation, we need to create a journey containing that exit.\n",
-    "Journeys are used to manage more complex routing situation, but this will be explained in more detail in some **TODO other guide**."
+    "Journeys are used to manage more complex routing situation, an explanation of the underlying routing concept can be found [here](/concepts/routing)."
    ]
   },
   {

notebooks/journey.ipynb

@@ -7,6 +7,8 @@
    "source": [
     "# How to work with Journeys\n",
     "\n",
+    "This notebook can be directly downloaded {download}`here <./journey.ipynb>` to run it locally.\n",
+    "\n",
     "With JuPedSim, directing agents towards exits and ensuring a smooth evacuation from the simulation area is straightforward and versatile. \n",
     "There might be scenarios where it's vital to navigate agents along various paths, thus creating diverse evacuation situations. \n",
     "Let's explore different routing strategies of agents using a simple geometric space - a corner.\n",
@@ -648,6 +650,16 @@
     "\n",
     "As the waypoint placement proves to be instrumental, ensuing studies or simulations might delve into optimizing these placements, exploring a range of scenarios and algorithmic strategies to discern optimal configurations for various contexts. Furthermore, additional research could investigate the scalability of these findings, examining the consistency of agent distribution patterns in scenarios with varying agent quantities, environmental layouts, and navigational complexities."
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e5ae96a2",
+   "metadata": {},
+   "source": [
+    "# Download\n",
+    "\n",
+    "This notebook can be directly downloaded {download}`here <./journey.ipynb>` to run it locally."
+   ]
   }
  ],
  "metadata": {

notebooks/lane-formation.ipynb

@@ -27,6 +27,8 @@
    "source": [
     "# Lane formation in bi-directional flow\n",
     "\n",
+    "This notebook can be directly downloaded {download}`here <./lane-formation.ipynb>` to run it locally.\n",
+    "\n",
     "Lane formation is a quantitative phenomenon, that is observed in bidirectional pedestrian flows. It involves pedestrians automatically forming a number of lanes with varying widths, where individuals within each lane move in the same direction. This self-organizing behavior of pedestrians can have a significant impact on overall evacuation time.\n",
     "\n",
     "In this example, we will replicate a simple experiment performed by [Feliciani et al 2016](https://doi.org/10.1103/PhysRevE.94.032304).\n",
@@ -536,6 +538,15 @@
     "\n",
     "The following result show mainly that a **balanced ratio** lead in the simulation to **higher densities** and more conflicts that remain mainly unsolved. This in turns is reflected in **higher evacuation times**.\n"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Download\n",
+    "\n",
+    "This notebook can be directly downloaded {download}`here <./lane-formation.ipynb>` to run it locally."
+   ]
   }
  ],
  "metadata": {

notebooks/motivation.ipynb

@@ -7,6 +7,8 @@
    "source": [
     "# Modelling Motivation\n",
     "\n",
+    "This notebook can be directly downloaded {download}`here <./motivation.ipynb>` to run it locally.\n",
+    "\n",
     "## Simulation of a corridor with different motivations\n",
     "\n",
     "In this demonstration, we model a narrow corridor scenario featuring three distinct groups of agents. Among them, one group exhibits a higher level of motivation compared to the others.\n",
@@ -344,6 +346,15 @@
     "\n",
     "Conversely, the first group maintains a consistent pace and doesn't attempt to overtake the now-lagging third group."
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Download\n",
+    "\n",
+    "This notebook can be directly downloaded {download}`here <./motivation.ipynb>` to run it locally."
+   ]
   }
  ],
  "metadata": {

notebooks/queues_waiting.ipynb

@@ -13,6 +13,8 @@
    "source": [
     "# Waiting in Queues\n",
     "\n",
+    "This notebook can be directly downloaded {download}`here <./queues_waiting.ipynb>` to run it locally.\n",
+    "\n",
     "In the following, we'll simulate scenarios where agents are waiting in queues as an example for implementing **crowd management measures**. Since waiting behaviour is not a process that can be modelled by the operational model itself we explicitely need to define (and trigger) the **waiting behaviour** of the agents. In this example, we'll simulate a scenario where people arrive to a concert and can approach the entrance by four line-up gates. At the gates a ticket control is performed that lasts 10 seconds for each person.\n",
     "\n",
     "Let's import the required package:\n"
@@ -811,6 +813,16 @@
     ")\n",
     "animate(trajectory_data_uneven, walkable_area, every_nth_frame=5)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6dea5741",
+   "metadata": {},
+   "source": [
+    "# Download\n",
+    "\n",
+    "This notebook can be directly downloaded {download}`here <./queues_waiting.ipynb>` to run it locally."
+   ]
   }
  ],
  "metadata": {

notebooks/routing.ipynb

@@ -6,6 +6,8 @@
    "source": [
     "# How Route Choice can Impact Evacuation Times\n",
     "\n",
+    "This notebook can be directly downloaded {download}`here <./routing.ipynb>` to run it locally.\n",
+    "\n",
     "In this demonstration, we'll be simulating a room with a single exit. \n",
     "We'll place two distinct groups of agents in a designated zone within the room. \n",
     "Each group will be assigned a specific route to reach the exit: \n",
@@ -115,7 +117,7 @@
     "centroid = distribution_polygon.centroid\n",
     "plt.text(\n",
     "    centroid.x, centroid.y, \"Start\", ha=\"center\", va=\"center\", fontsize=10\n",
-    ");"
+    ")"
    ]
   },
   {
@@ -384,6 +386,15 @@
     "\n",
     "Please note that in the section [Allocation and Configuration of Agents](#distribution), we employed a consistent seed number for agent distribution. For dependable outcomes, it's advised to run the simulations multiple times to ensure statistical significance. Morover, more percentage values between 0 and 100 will enhance the quality of the results."
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Download\n",
+    "\n",
+    "This notebook can be directly downloaded {download}`here <./routing.ipynb>` to run it locally."
+   ]
   }
  ],
  "metadata": {

notebooks/single-file.ipynb

@@ -31,6 +31,8 @@
    "source": [
     "# Simulating Single-File Movement\n",
     "\n",
+    "This notebook can be directly downloaded {download}`here <./single-file.ipynb>` to run it locally.\n",
+    "\n",
     "Pedestrian dynamics often focuses on the relationship between two key variables: density and either flow or velocity. The relationship is often visualized in what's termed as the fundamental diagram. By quantifying the capacity of pedestrian facilities, it serves as an essential tool for evaluating escape routes in emergencies and determining the effectiveness of various pedestrian movement models when depicting pedestrian streams.\n",
     "\n",
     "A fundamental question arises: how does one investigate the intricacies of the fundamental diagram without the interference of external factors? \n",
@@ -426,6 +428,15 @@
     "\n",
     "The model effectively simulates agents that adhere closely to a central path due to the dense distribution of waypoints with small radii. However, the disappearance of stop-and-go waves over time highlights a limitation inherent to velocity-based models. Such models may not be suitable for scenarios where persistent stop-and-go dynamics are expected or required. Future iterations of the model may benefit from incorporating additional factors or behaviors to better simulate such dynamics."
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Download\n",
+    "\n",
+    "This notebook can be directly downloaded {download}`here <./single-file.ipynb>` to run it locally."
+   ]
   }
  ],
  "metadata": {

python_modules/jupedsim/jupedsim/models/collision_free_speed.py

@@ -8,9 +8,12 @@
 
 @dataclass(kw_only=True)
 class CollisionFreeSpeedModel:
-    """Parameters for Collision Free Speed Model
+    """Collision Free Speed Model
 
-    All attributes are initialized with reasonably good defaults.
+    A general description of the Collision Free Speed Model can be found in the originating publication
+    https://arxiv.org/abs/1512.05597
+
+    A more detailed description can be found at https://pedestriandynamics.org/models/collision_free_speed_model/
 
     Attributes:
         strength_neighbor_repulsion: Strength of the repulsion from neighbors

python_modules/jupedsim/jupedsim/models/collision_free_speed_v2.py

@@ -8,7 +8,16 @@
 
 @dataclass(kw_only=True)
 class CollisionFreeSpeedModelv2:
-    """Collision Free Speed Model v2 has no model parameters."""
+    """Collision Free Speed Model V2
+
+    This is a variation of the Collision Free Speed Model where geometry and neighbor repulsion are individual
+    agent parameters instead of global parameters.
+
+    A general description of the Collision Free Speed Model can be found in the originating publication
+    https://arxiv.org/abs/1512.05597
+
+    A more detailed description can be found at https://pedestriandynamics.org/models/collision_free_speed_model/
+    """
 
     pass
 

python_modules/jupedsim/jupedsim/models/generalized_centrifugal_force.py

@@ -10,6 +10,12 @@
 class GeneralizedCentrifugalForceModel:
     """Parameters for Generalized Centrifugal Force Model
 
+    .. warning::
+        Unfortunately we broke the model before the 1.0 release and did not notice it in time.
+        For the time being please do not use this model.
+
+        We track the defect here: https://github.com/PedestrianDynamics/jupedsim/issues/1337
+
     All attributes are initialized with reasonably good defaults.
 
     Attributes: