Merge branch 'main' of github.com:flowersteam/vivarium

README.md

@@ -35,6 +35,8 @@ pip install -r requirements.txt
 pip install -e . 
 ```
 
+If your are a UPF student, continue from [here](notebooks/sessions/README.md).
+
 ## 🚀 Usage
 
 Vivarium can be used in three main ways:  

notebooks/sessions/README.md

@@ -1,14 +1,26 @@
 This directory contains educational sessions that enable you controlling a simulation from a Notebook controller.
 
+You will need a set of software tools installed on your computer, which are listed below. **If you are unsure about how to install or use them, first ask a professor or another student, we will help you.**
+- A Python distribution
+    - On MacOS and Windows, the recommended one is [Anaconda](https://www.anaconda.com/)
+    - On Linux it is usually pre-installed
+- A virtual environment
+    - Either `venv` or `conda`
+- [pip](https://pypi.org/project/pip/)
+- [git](https://git-scm.com/)
+- [Jupyter](https://jupyter.org/)
+    - It can usually be installed with `pip`
+
 - If not already done, first install the required software by following the instructions in the main [README](../../).
-    - For MacOS and Windows: If Python and/or Jupyter Notebook is not installed on your computer, first [install Anaconda](https://www.anaconda.com/).
-- Launch `jupyter notebook` by opening another terminal (on Windows: open Anaconda Prompt instead) and executing:
+    - First create a dedicated directory on your computer, e.g. within your `Documents` folder, and execute the intallation instructions from this directory. In the following we will refer to this directory as `<PATH_TO_LOCAL_VIVARIUM_REPO>`.
+    - Just follow the steps in the "Installation" section of the README, then come back here.
+- Launch `jupyter lab` (or `jupyter notebook`) by opening another terminal (on Windows: open Anaconda Prompt instead) and executing:
 ```bash
 cd <PATH_TO_LOCAL_VIVARIUM_REPO>
 source env_vivarium/bin/activate
 jupyter notebook
 ```
-- This will open a web page in the browser with a list of files. Open the practical session you want to do (`session_1.ipynb` if it is the first class).
+- This will open a web page in the browser with a list of files and directories. Go to `notebooks/sessions` and open the practical session you want to do (`session_1.ipynb` if it is the first class).
 
 The rest of the session is described in this newly opened document, please continue from there. 
 Here is a quick overview of the available sessions:

notebooks/sessions/session_2.ipynb

@@ -19,8 +19,9 @@
    "metadata": {},
    "source": [
     "**Reminders :** \n",
-    "- Save your work as indicated at the beginning of the `session_1.ipynb` notebook.\n",
+    "- Work on a copy of this notebook and save your work as indicated at the beginning of the `session_1.ipynb` notebook.\n",
     "- Each time you encounter a cell containing code in this notebook (as in the cell starting with `from vivarium.controllers...` below), you have to execute it by clicking on the cell and pressing `Shift+Enter` (unless it is explicitly specified not to do it). This will import the necessary modules and functions to use the simulator.\n",
+    "- If you experience issues, have a look at the [Troubleshooting tutorial](../tutorials/troubleshooting.ipynb)\n",
     "\n",
     "<!-- TODO: load scene !-->"
    ]
@@ -55,7 +56,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Wait until the interface link shows up (http://localhost:5006/run_interface) and click on it, and make sure the scene is present on your browser. \n",
+    "Wait until the interface link shows up (it should be http://localhost:5006/run_interface or similar) and click on it, and make sure the scene is present on your browser. Keep both this notebook and the interface window open, ideally side by side.\n",
     "\n",
     "Create a controller that will be used to control the simulation with Python code from this jupyter notebook:"
    ]
@@ -101,13 +102,6 @@
     "agent = controller.agents[0]"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "If at some point things are not going as expected (e.g. the agent doesn't move the way it should in the simulator), follow the steps explaine in Session 1 or in the [troubleshooting tutorial](../tutorials/troubleshooting.ipynb)."
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -223,9 +217,9 @@
     "def square(x):\n",
     "    return x * x\n",
     "\n",
-    "print(square(3))\n",
+    "print('The square of 3 is', square(3))\n",
     "\n",
-    "print(square(5))"
+    "print('The square of 5 is', square(5))"
    ]
   },
   {
@@ -277,14 +271,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Each time you execute the cell above, you should see the proximeter activation changing because the agent is moving. However, you should avoid setting motor values while a behavior is running since this could conflict with the behavior also setting those values. When a behavior is attached, it runs indefinitely until you explicitly detach it. To do so, you have to execute:"
+    "Each time you execute the cell above, you should see the proximeter activation changing because the agent is moving. However, you should avoid setting motor values while a behavior is running since this could conflict with the behavior also setting those values. When a behavior is attached, it runs indefinitely until you explicitly detach it, as we will explain below."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "At anytime, you can also check what behaviors are attached to the agent with the following command. You don't have to worry about the `Attached behaviors` and `Started behaviors` yet, as we will see this with more detail at the end of the notebook. For the moment you just have to know that the behaviors executing in the simulation are the ones listed in the `Started behaviors` list."
+    "At anytime, you can also check what behaviors are attached to the agent with the following command. "
    ]
   },
   {
@@ -300,7 +294,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "You can detach the behavior of an agent by using the `detach_behavior` method. You have to pass the name of the behavior as a string to the function to make it work. This is done by adding \"\" around the name of the behavior. For example, to detach the `slow_down` behavior, you have to execute:"
+    "You don't have to worry about the difference between `Attached behaviors` and `Started behaviors` yet, as we will see this with more detail at the end of the notebook. For the moment you just have to know that the behaviors executing in the simulation are the ones listed in the `Started behaviors` list."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can detach the behavior of an agent by using the `detach_behavior` method. You have to pass the name of the behavior you want to detach as a string, which has to correspond to the name of the behavior function we have defined above. This is done by adding \"\" around the name of the behavior. For example, to detach the `slow_down` behavior, you have to execute:"
    ]
   },
   {
@@ -325,7 +326,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Note that the agent has no behaviors attached anymore, but will continue moving using the last motor speeds that were set by the behavior. You can set both motor speeds to 0 by executing:"
+    "Now the agent doesn't have any behavior attached to it, but will continue moving using the last motor speeds that were set by the behavior. You can set both motor speeds to 0 by executing:"
    ]
   },
   {
@@ -341,7 +342,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "You can also stop the behavior and stop the motors of the agent in the same line. To demonstrate this, let's first attach the behavior again by executing:"
+    "You can also stop the behavior and stop the motors of the agent in the same line. To demonstrate this, let's re-attach the behavior again by executing:"
    ]
   },
   {
@@ -373,7 +374,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The stop_motors argument will automatically execute agent.stop_motors() before detaching the behavior. If you don't want the motors to stop when detaching the behavior, you can set stop_motors to False."
+    "The stop_motors argument will automatically execute `agent.stop_motors()` after detaching the behavior. If you don't want the motors to stop when detaching the behavior, you can set stop_motors to False."
    ]
   },
   {
@@ -396,14 +397,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We recommend to not change the default interval unless the simulator becomes slow. This should not be the case for now, but it might be when we learn to program more complex simulation. "
+    "We recommend to not change the default interval unless the simulator becomes slow. This should not be the case for now, but it might be when we learn to program more complex simulations. "
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "You can check how many step of the simulation is currently executed per second with:"
+    "You can check how many steps of the simulation is currently executed per second with:"
    ]
   },
   {
@@ -419,7 +420,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now let's detach the behavior of the agent and stop its motors before proceeding to the next section. You can do it with the `detach_all_behaviors` method:"
+    "Now let's detach the behavior of the agent and stop its motors before proceeding to the next section. You can do it with the `detach_all_behaviors` method, which simply detach all attached behaviors (this way we don't have to indicate the behavior name):"
    ]
   },
   {
@@ -442,7 +443,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Let's now practice a bit. Remember the Braitenberg Vehicle examples we have seen in [this slide](https://docs.google.com/presentation/d/1s6ibk_ACiJb9CERJ_8L_b4KFu9d04ZG_htUbb_YSYT4/edit#slide=id.g31e1b425a3_0_0). Those vehicles are very similar to the agents in the simulator. \n",
+    "Let's now practice a bit. Remember the Braitenberg Vehicle examples we have seen in [this slide](https://docs.google.com/presentation/d/1s6ibk_ACiJb9CERJ_8L_b4KFu9d04ZG_htUbb_YSYT4/edit#slide=id.g31e1b425a3_0_0) (if we haven't seen it yet, inform a professor before continuing the session). Those vehicles are very similar to the agents in the simulator. \n",
     "- A Braintenber Vehicle is equipped with two sensors that are activated according to the proximity of a source. With the agent, each proximeter sensor returns a value between 0 and 1 that is inversely proportional to the distance from the closest obstacle it perceives (the closer the obstacle, the highest to proximeter activation). Sensor values are accessed with `agent.sensors()`\n",
     "- A Braintenber Vehicle is equipped with two wheels. An agent in the simulator is also equipped with two whells, whose rotating speeds are controlled through the activation of each motor independently with a value between 0 and 1 (where 1 means maximum speed). E.g. setting the left wheel at full speed is achieved with `agent.left_motor = 1`, while stopping the right wheel is achieved with `agent.right_motor = 0`.\n",
     "- A behavior associates sensor activations to motor activations. In the Braitenberg Vehicles, this is achieved through connections that are either excitatory (the activity of the sensor increases the activity of the motor it is connected to) or inhibitory (the activity of the sensor decreases the activity of the motor it is connected to). In the agent, we have seen above that we can define a behavior as a function that (1) read the sensor activities (2) perform some computation and (3) use the result of that computation to set the motor speed. \n",
@@ -509,7 +510,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Note that this behavior will make the robot move only if at least one if its sensor detects an object (ojects are represented as squares in the interface). If no object is with the agent's field of view, try to move either the agent or some objects (see the [web interface tutorial](../tutorials/web_interface_tutorial.md) for how to move entities in the interface)."
+    "Note that this behavior will make the robot move only if at least one if its sensor detects an object (ojects are represented as squares in the interface). If no object is within the agent's field of view, try to move either the agent or some objects (see the [web interface tutorial](../tutorials/web_interface_tutorial.md) for how to move entities in the interface)."
    ]
   },
   {
@@ -539,9 +540,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": true
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "# you answer here"
@@ -636,7 +635,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now the agent is \"aware\" of the `slow_down` behavior, but does not execute it. You can check it in the interface: the agent does not move. To execute the behavior you need to explicitely start it:"
+    "Now the agent is \"equipped\" with the `slow_down` behavior, but does not execute it. You can check it in the interface: the agent does not move. To execute the behavior you need to explicitely start it:"
    ]
   },
   {
@@ -707,7 +706,7 @@
     "print(\"\\nstep 1:\")\n",
     "agent.print_behaviors() # This will print \"No behavior attached\"\n",
     "\n",
-    "# Write just below this line the code that attaches and start the slow_down behavior\n",
+    "# Write just below this line the code that attaches and starts the slow_down behavior\n",
     "# you answer here\n",
     "print(\"\\nstep 2:\")\n",
     "agent.print_behaviors() # This will print \"Attached behaviors: ['slow_down'], Started behaviors: ['slow_down']\"\n",
@@ -812,9 +811,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "An alternative way is to stop and detach all the behaviors running on the agent. This avoids having to specify the name of the behavior (`slown_down` in the cell above) and also stops systematically the behavior before detaching it:\n",
-    "\n",
-    "+ stop motors (should me make it a default arg with this function ? )"
+    "An alternative way is to stop and detach all the behaviors running on the agent. This avoids having to specify the name of the behavior (`slown_down` in the cell above) and also stops systematically the behavior before detaching it:"
    ]
   },
   {
@@ -830,7 +827,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "That's it for this practical session. You can now close the session:"
+    "That's it for this practical session. You can now close the session (always do this after having completed a notebook):"
    ]
   },
   {
@@ -853,7 +850,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "venv",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -867,9 +864,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.12"
+   "version": "3.10.14"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 1
+ "nbformat_minor": 4
 }