diff --git a/README.md b/README.md index 10aaa22..086ba0b 100755 --- a/README.md +++ b/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` - -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 :/app/shared -r -cf ` 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 :/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 :/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. -- `` is the docker image name previously created. -- `-r ` 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. +- `` is the docker image name previously created with the `build` command. +- `-r ` 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 ` 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` diff --git a/shared/README.md b/shared/README.md new file mode 100755 index 0000000..c6b61dc --- /dev/null +++ b/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 +{ + +} +``` \ No newline at end of file