Merge pull request #11 from logos-co/documentation

Documentation into master

README.md

@@ -12,42 +12,45 @@ In order to build the image, simply run:
 `docker build -t desired_name_of_docker_image .`
 
 In order to tell the container what to do, you need to specify the options in a configuration file, as json.
-More information in:
-
 
 Supported parameters:
 - Run parameters `--run` or `-r`
-  - `both` (default) (to-do)
+  - `both` (will be default) (to-do)
   - `simulation`
-  - `plotter` (to-do)
+  - `plotter`
 - Simulation type `--protocol` or `-p` (to-do)
   - `snow-family` (default, not changeable)
 - Configuration file `--configuration-file` or `-cf`
   - <configuration_file_name.json>
 
-In order to receive the information, plots, and whatever is done inside the container, a shared folder is 
-provided inside this repository. Before running the container, 
+In order to share the information, plots, and so on between the host and the container, a shared folder as example is
+given in this repository. But any path would work for this.
 
-### Example of execution:
+### Explanation of commands:
 
 `docker run --rm -v </your/path/to/SimulationsFramework/shared>:/app/shared <desired_name_of_docker_image> 
 -r <simulation> -cf <configuration_file_name.json>`
 
 The parameters inside `< >` can be changed. Where:
 
-- `docker run --rm` will launch a docker container, and after it finishes, it will automatically destroy itself.
-- `-v </your/path/to/SimulationsFramework/shared>:/app/shared` is the mount folder that will be used to share data 
-between the container and the host. In order to make things easier, the folder inside this repo can be used for that.
-Still, any desired folder can be put here, as long as it is in absolute path. `/app/shared` is a internal framework
+- `docker run --rm` will launch a docker container, and after it finishes, it will automatically destroy itself. The 
+data generated will be saved in the mount folder.
+- `-v </your/path/to/desired/folder>:/app/shared` is the mount folder that will be used to share data 
+between the container and the host. `/app/shared` is a internal framework
 location, so this needs to remain unchanged.
-- `<desired_name_of_docker_image>` is the docker image name previously created.
-- `-r <simulation>` is the type of execution we want. It can be only simulation `simulation`, only plotting `plotter`,
-or simulation and plot `both`. This last option is as default, so if this is the case, it is something that needs to
-be specified.
+- `<desired_name_of_docker_image>` is the docker image name previously created with the `build` command.
+- `-r <simulation>` is the type of execution we want. It can be only simulation with `simulation`, only plotting with 
+`plotter`, or simulation and plot `both` (to-do). 
 - `-cf <configuration_file_name.json>` is the configuration file where we set up what we want to do in the execution. 
-This file needs to be in our shared host folder. 
+This file is **assumed to be in our shared host folder**, so the full path is not needed. If we want the file in a 
+sub-folder like `shared/test_1/config_example.json`, you need to add the relative path from `shared`. In this
+example, it would be `-cf test_1/config_example.json`
 
-So, an example of a command would be:
+### Example of use:
+
+So, assuming we are in the root of this repository, an example of use would be:
+
+`docker build -t simulation-framework .`
 
 `docker run --rm -v /mnt/d/Projects/SimulationsFramework/shared:/app/shared simulation-framework 
 -r simulation -cf config_example.json`

shared/README.md

@@ -0,0 +1,158 @@
+# Structure
+
+The configuration file is divided in 3 main blocks,
+- `arguments`
+- `simulation`
+- `plotting`
+
+These blocks will be explained below. Also, an example of a configuration file is given under the `shared` folder.
+
+## `arguments` block
+___
+Here we can establish the parameters related with the results of the simulation.
+
+
+### `output-format`
+
+**Description**: Format of the resulting data of the simulation. This will be used to set the name of the files created 
+by the simulation in the manner output-file + "_seedUsed." + output-format.
+
+**Possible values**:
+  - `csv`
+  - `parquet`
+  - `json`
+
+**Type**: *string*
+
+**Required**: *No*
+
+**Default value**: `parquet`
+
+
+
+**Example**:
+```json
+{
+  "output-format": "csv"
+}
+```
+### `output-file`
+
+**Description**: Name of the file that will contain the results. It will be created inside the host shared folder. 
+This will be used to set the name of the files created by the simulation in the manner output-file + "_seedUsed." + 
+output-format.
+
+If an [output folder](#output-folder) is given, the files will be created inside that folder.
+
+**Type**: *string*
+
+**Required**: *Yes*
+
+**Example**:
+```json
+{
+  "output-file": "test"
+}
+```
+
+### `output-folder`
+
+**Description**: Folder to save the results and/or plots of the execution. It will be created inside the host shared 
+folder. 
+
+Note /!\: *If a folder will the same name exists, it will be deleted with all it's content.*
+
+**Type**: *string*
+
+**Example**:
+```json
+{
+  "output-folder": "results"
+}
+```
+
+### `number-of-simulations`
+
+**Description**: Number of simulations that will be done under the same configuration. Each simulation will be different,
+as a different seed will be used per simulation.
+
+**Type**: *integer*
+
+**Required**: *Yes*
+
+**Example**:
+```json
+{
+    "number-of-simulations": 100
+}
+```
+
+### Full [arguments](#arguments) example:
+
+```json
+{
+    "output-format": "csv",
+    "output-file": "test",
+    "output-folder": "folder",
+    "number-of-simulations": 3
+}
+```
+___
+## `simulation`
+
+Here we will set the simulation parameters, depending on the simulation we want to do. These parameters are explained in
+their own repository.
+
+
+- [Snow family](https://github.com/logos-co/consensus-research/tree/main/simulations/snow-family#simulationsettings) (default)
+
+___
+## Plotting (to-do)
+
+Plotting part of the configuration file. These plots are being done with [Seaborn](https://seaborn.pydata.org/).
+
+First example:
+
+**Description**: Scatter plot. 
+
+**Possible values**: Any value will be mapped to the [scatterplot](https://seaborn.pydata.org/generated/seaborn.scatterplot.html) method.
+
+**Type**: *dict*
+
+**Example**:
+```json
+{
+  "scatterplot": {
+    "plot_options": {
+      "x": "id",
+      "y": "vote"
+    },
+    "save_options": {
+      "name": "test2.png"
+    }
+  }
+}
+```
+
+
+
+TEMPLATE:
+
+**Description**: 
+
+**Possible values**:
+  - ``
+  - ``
+
+**Type**: **
+
+**Required**: **
+
+**Default value**: ``
+
+**Example**:
+```json
+{
+
+}
+```

src/utilities/files/schemas/arguments_schema.json

@@ -13,10 +13,13 @@
     "output-file": {
       "type": "string"
     },
+    "output-folder": {
+      "type": "string"
+    },
     "number-of-simulations" : {
       "type": "number"
     }
   },
-  "required": ["output-format", "output-file", "number-of-simulations"],
-  "aditionalProperties": false
+  "required": ["output-file", "number-of-simulations"],
+  "additionalProperties": false
 }

src/utilities/files/schemas/plotter_schema.json

@@ -62,5 +62,5 @@
       ]
     }
   },
-  "aditionalProperties": false
+  "additionalProperties": false
 }