diff --git a/util/README.md b/util/README.md new file mode 100644 index 0000000..031566b --- /dev/null +++ b/util/README.md @@ -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 :* specify the number of atoms per unit cell (the number of neighbors per atom is this value minus 1), the default is 8. +*-n :* timesteps to run the simulation, the default is 200. +*-nx :* number of unit cells in the x dimension, the default is 4. +*-ny :* number of unit cells in the y dimension, the default is 4. +*-nz :* 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 :* 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 :* output file (.txt) for the results, the default is *run_results.txt*. +*-r :* 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.