Improve documentation

notebooks/simulator_tutorial.ipynb

@@ -334,7 +334,7 @@
     "\n",
     "All information about the agents that are not shared by other entities. At the moment, the agents are braitenberg vehicles, that is why they have behaviors, wheels, motors, proximeter ... \n",
     "\n",
-    "The agents perceive the environment trough proximeters, and the behavior determines motor activations according to proximeter activations. They are implemented in [this file](../vivarium/simulator/behaviors.py) "
+    "The agents perceive the environment trough proximeters, and the behavior determines motor activations according to proximeter activations. They are implemented in [this file](../vivarium/simulator/behaviors.py)."
    ]
   },
   {
@@ -505,7 +505,9 @@
    "source": [
     "### Run a simulation and save it\n",
     "\n",
-    "state initial + run sim = modifier cet etat  ... At the moment the simulation will run with the default behavior assigned to the agents. They are in agressive mode, which means they will rush toward the closest entity in their field of view. The simulation also includes physics elements such as collisions between entities etc. All the functions used to compute the next state of the simulation are currently located in the [physcis engine](../vivarium/simulator/physics_engine.py) file. "
+    "To run a simulation, we update the initial state at each timestep. By default, agents are assigned an aggressive behavior, causing them to move toward the closest entity within their field of view. The simulation also incorporates physics elements, such as collisions between entities.\n",
+    "\n",
+    "All the functions used to compute the next state of the simulation are currently located in the [physcis engine](../vivarium/simulator/physics_engine.py) file. As the simulation progresses, you can save its state for further analysis or visualization."
    ]
   },
   {
@@ -569,7 +571,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We can also speed up the simulation by using jax loops (lax.fori_loop / lax.scan) instead of classical loops."
+    "We can also speed up the simulation by using jax loops ([lax.fori_loop](https://jax.readthedocs.io/en/latest/_autosummary/jax.lax.fori_loop.html) / [lax.scan](https://jax.readthedocs.io/en/latest/_autosummary/jax.lax.scan.html)) instead of classical loops."
    ]
   },
   {
@@ -586,7 +588,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Render the state history"
+    "### Render the state history\n",
+    "\n",
+    "After running the simulation for 2000 steps twice, we will combine the two state histories and visualize the entire simulation sequence."
    ]
   },
   {