Updated README; Refactoring project path

.gitignore

@@ -3,3 +3,4 @@ __pycache__
 tmp/*
 src/web_app/cache
 /benchmark/
+src/web_app/images

Dockerfile

@@ -8,9 +8,11 @@ RUN pip install --upgrade pip
 COPY requirements.txt requirements.txt
 RUN pip install -r requirements.txt
 COPY src/ src
+COPY run_webpage.py run_webpage.py
 COPY configuration/ configuration
 COPY resources/ resources
 
-ENV PYTHONPATH "${PYTHONPATH}:src/.:src/web_app/.:src/sim/."
+#ENV PYTHONPATH "${PYTHONPATH}:src/.:src/web_app/.:src/sim/."
 
-CMD ["python", "src/web_app/index.py"]
+#CMD ["python", "src/web_app/index.py"]
+CMD ["python", "run_webpage.py"]

README.md

@@ -1,8 +1,145 @@
 # Simulator Automatic Warehouse
 
-This repository is a thesis project for University of Verona (Università di Verona).\
-\
-This project allows to simulate an automatic warehouse by inserting some information like: height, weight, etc.\
-Furthermore, you can visit a webpage (index.py) to create new simulations in a user-friendly way.\
-\
-The project is "in progress", so the documentation will come soon...
+This repository was created for a thesis project for the University of Verona (Università di Verona).
+
+The project is a simulator of an automatic warehouse. The inspiration came from the [Vertimag][1] of 
+[Ferretto Group][2], an Italian company based in Vicenza. 
+So the logic of the warehouse digitalized is the same of the real Vertimag.
+
+As a case study, the Vertimag present in the [ICE Laboratory][3] was chosen.
+The warehouse you'll find is made for education/research purposes, so it's different from a classic Vertimag 
+that you can find in the industries (see the differences in these photos: [ICELab Vertimag][4] and [Industries Vertimag][1]). 
+However, this does not mean that the project is not valid!
+In fact, the project is used as a base by the researchers at the ICELab to make another simulator using different 
+technologies.
+
+The repository contains a `src` directory where you can find: the **simulator** and the **webpage**.
+
+The simulator is mainly made using [SimPy v4.0.2][5] and simulates 4 actions (you can implement more if you need to). 
+The webpage is made using [Dash v2.15.0][6] (with the support of [Dash Bootstrap Components v1.5.0][7]) and 
+[Plotly v5.17.0][8] to allow the end-user, in this case the thesis advisor, 
+to interact with the simulator in a user-friendly way.
+
+In the future, you need to add unittest.
+
+------------------------------------------------------------------------------------------------------------------------
+
+## How to Install and Run the Project
+
+You can choose to run the project in one of two ways: using [Python v3.12.2][9] or using [Docker][10] 
+and [Docker compose][13].
+
+### Python
+
+Install the requirements using [pip][11]:
+
+```bash
+pip install -r requirements.txt
+```
+
+#### Simulator
+
+To run only the simulator without the webpage, go to the project directory simulator-automatic-warehouse 
+and set the environment variable for the configuration. 
+Each simulation uses a yaml file to set up the automatic warehouse 
+(a full explanation of the config file can be found in 
+[configuration/sample_config.yaml](configuration/sample_config.yaml):
+
+```bash
+export WAREHOUSE_CONFIGURATION_FILE_PATH=configuration/univr/ICE_lab.yaml
+python3.12 run_simulator.py
+```
+
+Or one line:
+
+```bash
+WAREHOUSE_CONFIGURATION_FILE_PATH=configuration/univr/ICE_lab.yaml python3.12 run_simulator.py
+```
+
+The loaded configuration represents the Vertimag in ICELab. 
+You can create another configuration following the json schema 
+([resources/configuration/json_schema.json](resources/configuration/json_schema.json)).
+
+Finally, it's possible to manage the console log using the environment variables:
+ - `NO_CONSOLE_LOG`: If set, console logs are not displayed.
+ - `DEBUG_LOG`: if set, debug logging will be printed to the console.
+ - `FILENAME_DEBUG_LOG`: if set, save the debug log to file (e.g. `sim.log`).
+
+#### Website
+
+To run the website, in addition to the environment variables specified in the [Simulator](#simulator) section,
+you need to specify:
+ - HOST: Host IP used to serve the application.
+ - PORT: Port used to serve the application.
+ - (optional) PROXY: If this application will be served to a different URL via a proxy configured outside of Python, 
+                     you can list it here as a string of the form `{input}::{output}`, for example: 
+                     `http://0.0.0.0:8050::https://my.domain.com` 
+                     so that the startup message will display an accurate URL.
+
+For example, in localhost:
+
+```bash
+export WAREHOUSE_CONFIGURATION_FILE_PATH=configuration/univr/ICE_lab.yaml
+export HOST=127.0.0.1
+export PORT=8050
+python3.12 run_webpage.py
+```
+
+**Note**: 
+the username and password to access at the page can be found in the [`index.py`](src/web_app/index.py) file 
+after the `app` variable declaration. 
+The default, the values are:
+
+```python
+USER_PWD = {
+    "admin": "admin"
+}
+```
+
+But you can specify other users (see the complete documentation: [Dash Authentication][12]).
+
+### Docker
+
+Everything is easier with Docker. Go to the [docker](docker) folder and use docker compose to build:
+
+```bash
+cd docker && docker compose up
+```
+
+If you want to change or add some environment variables, edit [docker-compose.yaml](docker/docker-compose.yaml).
+
+------------------------------------------------------------------------------------------------------------------------
+
+## Benchmarks
+
+Here are some benchmarks run with a private Python library and the following computer specifications:
+ - Intel i7-8750H 
+ - SDRAM DDR4-2666 16GB
+ - MZ-76Q2T0 860 QVO SSD 2TB 2.5"
+ - SSD NVMe M.2 128 GB
+ - NVIDIA GeForce GTX 1050
+
+| Actions   | Time to process | Real-time simulation |
+|-----------|-----------------|----------------------|
+| 10'000    | 1 second        | 1d. 2h. 48m.         |
+| 63'000    | 7.5 seconds     | 1 week               |
+| 267'900   | 25 seconds      | 1 month              |
+| 3'250'120 | 9 minutes       | 1 year               |
+
+<img src="resources/doc/relationship_between_simulated_actions_and_media.svg" alt="Relationship between simulated actions and media">
+
+<img src="resources/doc/standard_deviation.svg" alt="Standard deviation">
+
+[1]: https://www.ferrettogroup.com/index.cfm/en/solutions/vertical-storage-system/vertical-lift-module-vertimag/
+[2]: https://www.ferrettogroup.com/index.cfm/en/
+[3]: https://www.icelab.di.univr.it/
+[4]: https://icewebsitestorage.blob.core.windows.net/icewebsitemediablob/gallery/IMG_0855.JPG
+[5]: https://simpy.readthedocs.io/en/4.0.2/
+[6]: https://dash.plotly.com/
+[7]: https://dash-bootstrap-components.opensource.faculty.ai/
+[8]: https://plotly.com/python/
+[9]: https://www.get-python.org/downloads/release/python-3122/
+[10]: https://docs.docker.com/engine/
+[11]: https://pip.pypa.io/en/stable/getting-started/
+[12]: https://dash.plotly.com/authentication
+[13]: https://docs.docker.com/compose/

run_simulator.py

@@ -0,0 +1,4 @@
+from src.sim.__main__ import run_simulator
+
+if __name__ == '__main__':
+    run_simulator()

run_webpage.py

@@ -0,0 +1,4 @@
+from src.web_app.index import run_webpage
+
+if __name__ == "__main__":
+    run_webpage()

src/sim/__main__.py

@@ -1,7 +1,7 @@
-from sim.warehouse import Warehouse
+from src.sim.warehouse import Warehouse
 
 
-if __name__ == "__main__":
+def run_simulator():
     # debug purpose
     # import random
     # random.seed(None)
@@ -10,7 +10,7 @@
     (warehouse := Warehouse()).run_simulation()
 
     # save the configuration at the end
-    # from sim.utils.save_warehouse_state import save_config
+    # from src.sim.utils.save_warehouse_state import save_config
     # save_config(warehouse.get_simulation().get_warehouse())
 
 

src/sim/drawer.py

@@ -1,8 +1,8 @@
 import copy
 import random
 
-from sim.material import Material
-from sim.warehouse_configuration_singleton import WarehouseConfigurationSingleton
+from src.sim.material import Material
+from src.sim.warehouse_configuration_singleton import WarehouseConfigurationSingleton
 
 
 class Drawer:

src/sim/material.py

@@ -1,6 +1,6 @@
 import random
 import uuid
-from sim.warehouse_configuration_singleton import WarehouseConfigurationSingleton
+from src.sim.warehouse_configuration_singleton import WarehouseConfigurationSingleton
 
 
 class Material: