MD-Bench/util/README.md

# 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, and hence all combinations of parameters will be 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.

**plot_gather_data.py:** Python script to plot the data generated by the gather benchmark. Just provide the name of the .txt file containing the gather output as a parameter and this script generates a corresponding PDF with the same file name. Multiple outputs with different strides can be included in the text file by concatenating the outputs. The script handles output from both standard simple array case and MD variant.

**cache.py:** Python script to run the cache simulator with the data obtained from the memory tracer. Just run it with the tracer output file name as a parameter. The cache specifications can be directly adapted in the script to match those of the target processor of interest.