Merge branch 'main' of github.com:clement-moulin-frier/vivarium

.gitignore

@@ -171,4 +171,4 @@ outputs
 test.py 
 Results/
 
-*/*/frames/
+*/*/frames_*/

README.md

@@ -1,6 +1,11 @@
 # 🌱 Vivarium
 
-**Vivarium** is framework for multi-agents simulations in Jax. It enables creating simple agents with two motors and two sensors, inspired by [Braitenberg Vehicles ](https://en.wikipedia.org/wiki/Braitenberg_vehicle), in a 2D rigid-body physics world. The physics engine is written in [Jax-MD](https://github.com/jax-md/jax-md). With Vivarium, you can run predefined or custom simulations, and interact with them in real time using a Web Interface or Jupyter notebooks. See our tutorials to get started with the project. 
+**Vivarium** is framework for for building and running multi-agents simulations using Jax. It allows you to design simple agents equipped with two motors and two sensors, inspired by [Braitenberg Vehicles ](https://en.wikipedia.org/wiki/Braitenberg_vehicle), operating in a 2D rigid-body physics environment powered by [Jax-MD](https://github.com/jax-md/jax-md).
+
+### **Key Features**:
+- **Predefined and Custom Simulations**: Quickly start with built-in scenes or create your own with customizable parameters.
+- **Real-Time Interaction**: Observe and control simulations dynamically using a web interface or programmatically through Jupyter Notebooks.
+- **Educational Resources**: Learn multi-agent simulation concepts with a series of interactive educational sessions.
 
 ![Vivarium demo](images/simulation.gif)
 
@@ -10,15 +15,18 @@ See a preliminary demo of the project on [this video](https://youtu.be/dnO-wo6Ns
 
 1- Clone the repository:
 
+Before following the next instructions, make sure you have Python installed with a version between 3.10 and 3.12. 
+
 ```bash
-git clone [email protected]:clement-moulin-frier/vivarium.git
+git clone [email protected]:flowersteam/vivarium.git
 cd vivarium/
 ```
 2- (Optional) Create and activate a virtual environment:
 
 ```bash
-python -m venv myvenv
-source myvenv/bin/activate
+python -m venv env_vivarium
+source env_vivarium/bin/activate #(for Linux users)
+env_vivarium\Scripts\Activate.ps1 #(for Windows users)
 ```
 
 3- Install the dependencies:
@@ -28,61 +36,75 @@ pip install -r requirements.txt
 pip install -e . 
 ```
 
+If your are a UPF student, continue from [here](notebooks/sessions/README.md).
+
 ## 🚀 Usage
 
-### Run the simulation in a server 🖥️
+Vivarium can be used in three main ways:  
+1. **Run a simulation server.**  
+2. **Interact with the simulation via a web interface.**  
+3. **Control the simulation programmatically in Jupyter Notebooks.**
+
+
+### 1. Run the simulation in a server 🖥️
 
 To run the simulation in a server, use the following command:
 
 ```bash
 python3 scripts/run_server.py
 ```
 
-We use [Hydra](https://hydra.cc/docs/intro/) to manage simulations data. By default, the simulation will use the parameters specified in the `default.yaml` scene file located in the `conf/scene` directory.
+By default, the simulation will use the configuration specified in the `default.yaml` scene file, located in the `conf/scene` directory. This system enables you to create custom scene files to define the initial parameters of your simulations with [Hydra](https://hydra.cc/docs/intro/).
 
 #### Using custom scene files 🌄
 
-You can customize the initial simulation parameters by creating your own scene files in YAML format and placing them in the `conf/scene` directory. Scene files can specify parameters such as the number of objects, their size, or the colors, positions, and behaviors of agents for example.
+You can customize the initial simulation parameters by creating your own scene files in YAML format and placing them in this `conf/scene` directory. Scene files can specify parameters such as the number of objects, their size, or the colors, positions, and behaviors of agents for example. See Tutorial [Create a custom Scene](notebooks/tutorials/create_custom_scene_tutorial.md) for more information.
 
 To use a custom scene file in your simulation, pass the `scene` option followed by the name of the scene file (without the `.yaml` extension) to the `run_server.py` script. For example, to run the `prey_predator_large` scene, use the following command:
 
 ```bash
 python3 scripts/run_server.py scene=prey_predator_large
 ```
 
-Any parameters not specified in the custom scene file will be inherited from the `default.yaml` scene.
+### 2. Interact via the web interface 🌐
 
-### Interact with it from a web interface 🌐
-
-When the server is started, you can launch a web interface from another terminal to observe the simulation and interact with it:
+Once the server is running, start the web interface:
 
 ```bash
 panel serve scripts/run_interface.py --autoreload
 ```
 
-Once this command will have completed, it will output a URL looking like `http://localhost:5006/run_interface`. Just click on it, and it will open the web interface in your browser. From there you can start the simulation and play with it.
+Once this command will have completed, it will output a URL looking like `http://localhost:5006/run_interface`. Just click on it, and it will open the web interface in your browser. From here, you can observe and interact with the simulation. We recommend starting with the [Web Interface Tutorial](notebooks/tutorials/web_interface_tutorial.md) to get a better understanding of the interface and its functionalities.
+
 
+### 3. Control simulations from Jupyter Notebooks 📓
 
-### Interact with it from a jupyter notebook 📓
+You can control the simulator programmatically using Jupyter Notebooks. This allows you to manage agent behaviors, internal states, and environmental dynamics (e.g., spawning resources or interaction mechanisms). With this approach, there's no need to manually start the server or interfac. Everything can be initiated directly from the provided commands within the notebooks. 
 
-You can also choose to control the simulator programmatically in Jupyter Notebook. We first recommend you to do the first tutorials listed below. Then you can select a notebook in the `notebooks/sessions/ `[directory](notebooks/sessions/) and start playing with it ! If you choose to do so, you don't need to start the server and the interface manually. Instead, you can start and stop them with a custom command you can find in the notebooks.
+To get started, we recommend completing the [web interface tutorial](notebooks/tutorials/web_interface_tutorial.md) first. You can then start controlling the simulation from a Jupyter Notebook by following the [quickstart tutorial](notebooks/tutorials/quickstart_tutorial.ipynb).
 
 ## 📚 Tutorials
 
-To help you get started and explore the project, we provide a set of Jupyter notebook tutorials located in the `notebooks/` [directory](notebooks/README.md). These tutorials cover various aspects of the project, from using the graphical interface to interacting with simulations and understanding the backend.
+To help you get started and explore the project, we provide a set of Jupyter notebook tutorials located in the `notebooks/tutorials` [directory](notebooks/tutorials/README.md). These tutorials cover various aspects of the project, from using the graphical interface to interacting with simulations and understanding the backend.
 
 - **Web Interface Tutorial**: Begin with the [web interface tutorial](notebooks/tutorials/web_interface_tutorial.md) to gain a basic understanding of the project and learn how to use the graphical interface.
 - **Quickstart Tutorial**: To learn how to interact with a simulation from a Jupyter notebook, follow the [quickstart tutorial](notebooks/tutorials/quickstart_tutorial.ipynb). This tutorial will guide you through creating, running, and manipulating simulations within a notebook environment.
 - **Create a custom Scene**: If you want to create your own simulations with custom parameters, check out the [create a custom scene tutorial](notebooks/tutorials/create_custom_scene_tutorial.md). This tutorial will show you how to create and use custom scene files to define the initial parameters of your simulations. 
 - **Simulator tutorial**: For a deeper understanding of the simulator backend and its capabilities, check out the [simulator tutorial](notebooks/tutorials/simulator_tutorial.ipynb). This tutorial provides insights into the underlying mechanics of the simulator and demonstrates how to leverage its features for advanced use cases
 
+## 🎓 Educational sessions 
+
+We offer a series of educational Jupyter Notebooks designed to teach the fundamentals of multi-agent simulation. These six sessions range from assigning basic agent behaviors to building complex eco-evolutionary environments and logging data for advanced projects.You can find these sessions in the `notebooks/sessions` [directory](notebooks/sessions/README.md). They cover topics such as:
+- **Assigning reactive behaviors to agents**
+- **Controlling the environmental dynamics**
+- **Logging and analyzing simulation data**
+
 ## 🛠 Development
 
 ### gRPC Configuration 🔄
 
 The projecte uses gRPC to communicate between server and clients. If you made any changes in the .proto file, you will need to recompile the gRPC files. Here is the command line instruction to do so:
 
-
 ```bash
 python -m grpc_tools.protoc -I./vivarium/simulator/grpc_server/protos --python_out=./vivarium/simulator/grpc_server/ --pyi_out=./vivarium/simulator/grpc_server/ --grpc_python_out=./vivarium/simulator/grpc_server/ ./vivarium/simulator/grpc_server/protos/simulator.proto
 ```

conf/scene/default.yaml

@@ -1,4 +1,4 @@
-# Default scene is a prey predator one. This file shows how to init a simulation with multiple entities, as well as selective sensing for agents
+# Default scene attributes
 seed: 0
 n_dims: 2
 box_size: 100

conf/scene/quickstart.yaml

@@ -5,22 +5,32 @@ prox_dist_max: 60
 # Entity data definitions
 entities_data:
   EntitySubTypes:
-    - AGENTS
-    - OBJECTS
+    - agents
+    - small_objects
+    - big_objects
 
   Entities:
-    AGENTS:
+    agents:
       type: AGENT
       num: 3
       color: blue
+      diameter: 10
       selective_behaviors:
         aggr:
           beh: MANUAL
           sensed: 
-            - AGENTS
-            - OBJECTS
+            - agents
+            - small_objects
+            - big_objects
 
-    OBJECTS:
+    small_objects:
       type: OBJECT
       num: 8
+      diameter: 5
+      color: orange
+
+    big_objects:
+      type: OBJECT
+      num: 4
+      diameter: 15
       color: red

conf/scene/session_1.yaml

@@ -5,22 +5,17 @@ prox_dist_max: 60
 # Entity data definitions
 entities_data:
   EntitySubTypes:
-    - AGENTS
-    - OBJECTS
+    - agents
+    - objects
 
   Entities:
-    AGENTS:
+    agents:
       type: AGENT
       num: 1
+      existing: 1
       color: blue
-      selective_behaviors:
-        aggr:
-          beh: MANUAL
-          sensed: 
-            - AGENTS
-            - OBJECTS
 
-    OBJECTS:
+    objects:
       type: OBJECT
       num: 8
       color: red

conf/scene/session_2.yaml

@@ -5,23 +5,18 @@ prox_dist_max: 60
 # Entity data definitions
 entities_data:
   EntitySubTypes:
-    - AGENTS
-    - OBJECTS
+    - agents
+    - objects
 
   Entities:
-    AGENTS:
+    agents:
       type: AGENT
       num: 1
       color: blue
       diameter: 10
-      selective_behaviors:
-        aggr:
-          beh: MANUAL
-          sensed: 
-            - AGENTS
-            - OBJECTS
+      prox_dist_max: 80.0
 
-    OBJECTS:
+    objects:
       type: OBJECT
       num: 13
       color: orange

conf/scene/session_3.yaml

@@ -6,24 +6,17 @@ prox_dist_max: 60
 # Entity data definitions
 entities_data:
   EntitySubTypes:
-    - robots
+    - agents
     - resources
     - obstacles
 
   Entities:
-    robots:
+    agents:
       type: AGENT
       num: 2
       existing: 1
       color: blue
       diameter: 10
-      selective_behaviors:
-        aggr:
-          beh: MANUAL
-          sensed: 
-            - robots
-            - resources
-            - obstacles
 
     resources:
       type: OBJECT

conf/scene/session_4.yaml

@@ -7,25 +7,17 @@ prox_dist_max: 60
 entities_data:
   EntitySubTypes:
   ## Care : make sure to order entities in a good order (first the agents and then the objects) ...
-    - robots
+    - agents
     - resources
     - s_obstacles
     - b_obstacles
 
   Entities:
-    robots:
+    agents:
       type: AGENT
       num: 3
       color: blue
       diameter: 10
-      selective_behaviors:
-        aggr:
-          beh: MANUAL
-          sensed: 
-            - robots
-            - resources
-            - s_obstacles
-            - b_obstacles
 
     resources:
       type: OBJECT

conf/scene/session_5.yaml → conf/scene/session_6.yaml

@@ -7,26 +7,18 @@ prox_dist_max: 60
 entities_data:
   EntitySubTypes:
   ## Care : make sure to order entities in a good order (first the agents and then the objects) ...
-    - robots
+    - agents
     - resources
     - s_obstacles
     - b_obstacles
 
   Entities:
-    robots:
+    agents:
       type: AGENT
       num: 10
       existing: 4
       color: blue
       diameter: 10
-      selective_behaviors:
-        aggr:
-          beh: MANUAL
-          sensed: 
-            - robots
-            - resources
-            - s_obstacles
-            - b_obstacles
 
     resources:
       type: OBJECT

linux_install.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+# clone the project repository and navigate to it  
+git clone https://github.com/flowersteam/vivarium.git
+cd vivarium/
+
+# install venv module if not already done
+sudo apt install -y python3-venv
+
+# create a virtual environment
+python3 -m venv env_vivarium
+
+# activate the virtual environment
+source env_vivarium/bin/activate
+
+# install the required packages
+pip install -r requirements.txt
+pip install -e .