Added first documentation

This commit is contained in:
Alberto Soutullo Rendo 2022-11-29 17:05:08 +01:00
parent bb28328509
commit 71e19fd747
2 changed files with 178 additions and 17 deletions

View File

@ -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`

158
shared/README.md Executable file
View File

@ -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
{
}
```