Added first documentation
This commit is contained in:
Alberto Soutullo Rendo
parent
bb28328509
commit
71e19fd747
37
README.md
37
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`
|
||||
|
|
|
|||
|
|
@ -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
|
||||
{
|
||||
|
||||
}
|
||||
```
|
||||
Loading…
Reference in New Issue