Add README.md for utilities

Signed-off-by: Rafael Ravedutti <rafaelravedutti@gmail.com>
This commit is contained in:
Rafael Ravedutti 2021-06-11 16:38:53 +02:00
parent 91661a79e6
commit 977bc68699

35
util/README.md Normal file
View File

@ -0,0 +1,35 @@
# Utility tools for MD-Bench
**mdBench.c:** Single file version for MD-Bench, used mostly for teaching purposes.
**run_stub.sh:** Bash script to run the MD-Bench stubbed force calculation for different configurations and evaluate the performance.
The configuration parameters are:
*-a <numbers>:* specify the number of atoms per unit cell (the number of neighbors per atom is this value minus 1), the default is 8.
*-n <numbers>:* timesteps to run the simulation, the default is 200.
*-nx <numbers>:* number of unit cells in the x dimension, the default is 4.
*-ny <numbers>:* number of unit cells in the y dimension, the default is 4.
*-nz <numbers>:* number of unit cells in the z dimension, the default is 2.
Notice that these parameters can also be specified as lists, which executes the stubbed force calculation several times varying the specific parameter to each element of the list.
All combinations of parameters are executed!
For example, the following command:
```bash
bash run_stub.sh -a "8 16" -nx "4 8" -ny 8 -nz 4
```
Will execute the stubbed force calculation for the following 4 configurations:
```bash
1> 8 atoms per unit cell on a 4x8x4 grid of unit cells, 200 timesteps
2> 16 atoms per unit cell on a 4x8x4 grid of unit cells, 200 timesteps
3> 8 atoms per unit cell on a 8x8x4 grid of unit cells, 200 timesteps
4> 16 atoms per unit cell on a 8x8x4 grid of unit cells, 200 timesteps
```
The following parameters are also available:
*-f <frequency>:* CPU frequency in GHz (assure your CPU frequency is fixed by disabling Turbo mode), more performance metrics such as cycles per iteration are displayed if this option is defined.
*-o <file>:* output file (.txt) for the results, the default is *run_results.txt*.
*-r <runs>:* number of runs for each configuration (only the values for the best run are displayed), the default is 3.
**plot_run_stub_data.py:** Python script to plot the data generated by the *run_stub.sh* script. Just provide the name of the .txt file as a parameter and this script generates a corresponding PDF with the same file name.