From d30c98aed27319870245020275ef87bd3a308602 Mon Sep 17 00:00:00 2001 From: Cory Date: Mon, 4 Dec 2023 13:28:33 +0100 Subject: [PATCH] Update README --- README.md | 139 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 103 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 1b277fb..5a7aac9 100644 --- a/README.md +++ b/README.md @@ -9,48 +9,79 @@ ### Operating systems - Linux - - Has been tested on [Fedora 38](https://fedoraproject.org/) - - Will most likely work on other Linux distributions + - Has been tested on [Fedora 38](https://fedoraproject.org/) + - Will most likely work on other Linux distributions - MacOS - - Might work, but hasn't been tested + - Might work, but hasn't been tested - Windows - - Will most likely not work + - Will most likely not work ### Tools - Profiling - - [gprof](https://ftp.gnu.org/old-gnu/Manuals/gprof-2.9.1/html_mono/gprof.html) - - [scalasca](https://www.scalasca.org/) - - [score-p](https://www.vi-hps.org/projects/score-p) + - [score-p](https://www.vi-hps.org/projects/score-p) ### Libraries - Python - - [matplotlib](https://matplotlib.org/) - - [numpy](https://numpy.org/) + + - [matplotlib](https://matplotlib.org/) + - [numpy](https://numpy.org/) - C++ - - [Openmp](https://www.openmp.org/) - - [OpenMPI](https://www.open-mpi.org/) - - [Armadillo](https://arma.sourceforge.net/) - + - [Openmp](https://www.openmp.org/) + - [OpenMPI](https://www.open-mpi.org/) + - [Armadillo](https://arma.sourceforge.net/) ## Compiling -Compiling is as easy as running this command while being inside the src directory: +The commands shown here should be run from the root of this project. + +### Normal binaries + +Compiling regular binaries is as easy as running this command: ```shell make ``` +The binaries will then be inside the **./bin** directory. + +### Profiling binaries + +If you want to profile the programs (specifically the MPI program), then run this command + +```shell + make profile +``` + +The binaries will then be inside the **./prof** directory. + +### Debugging binaries + +If you want to debug the code, then use this command: + +```shell + make debug +``` + +The binaries will then be inside the **./debug** directory. + ## Running programs ### C++ binaries -To run **main** or **test_suite**, just run this command while being inside src: +To run any of the programs, just use the following command: ```shell - ./ + .// +``` + +If you need help with any of the programs, you can use the **-h** or **--help** +flag to show you how to use the programs. Here is an example: + +```shell + ./bin/main --help ``` ### Python scripts @@ -68,62 +99,98 @@ This recursively install all the packages that are listed in **requirements.txt* #### Running scripts -For the Python scripts, run them from the src directory like this: +For the Python scripts, run them from the root of the project: ```shell - python scripts/ + python python_scripts/ ``` If you have any problems running the scripts, you might have to run this instead: ```shell - python3 scripts/ + python3 python_scripts/ ``` ### Batch system -For the **phase_transition_mpi** program, there are scripts in the **src/jobs** +For the **phase_transition_mpi** program, there are scripts in the **./slurm_scripts** directory that come along with it. This is to be able to run it on a -batch system using Slurm if you have access to one. -This is the recommended way to use this program as it takes approximately 90 +batch system using Slurm if you have access to one. +The only program that should be executed by the user is the **./slurm_scripts/execute.script** +script. You can see how to use this script by doing: + +```shell + ./slurm_scripts/execute.script --help +``` + +This is the recommended way to use this program as it takes approximately 90 minutes to complete when using 8 processes where each process has 10 threads. If you happen to have such a system available to you, then you should clone -this repo on that system, then compile it by running: +this repo on that system, then compile the MPI program like this: ```shell - make phase_transition_mpi + make bin/phase_transition_mpi ``` -You might have to load the Armadillo library using the **module** system before compiling. - -After compiling, you can schedule it by running: +After compiling, you can schedule it by using the **./slurm_scripts/execute.script**: ```shell - sbatch jobs/ + ./slurm_scripts/execute.script ``` ## Performance -This section aims to give an idea to the time it takes for the program to -run so that you know a bit what to expect if you decide to run it for -yourself. +This section aims to give an idea to the time it takes for the phase transition +program to run so that you know a bit what to expect if you decide to run it +for yourself. ### CPU -The times mentioned here are times achieved on a computer with these +The times mentioned here are times achieved on a computer with these specifications: - CPU model - - Intel i7-9850H + - Intel i7-9850H - Threads - - 12 + - 12 - Clock speed - - 4.6GHz + - 4.6GHz ### Times +Note that all times here are recorded using the OpenMP implementation of the +MCMC algorithm. + +| lattice size | points | samples | burn-in time | time (seconds) | +| ------------ | ------ | ------- | ------------ | -------------- | +| 20 | 20 | 100000 | 0 | 3.20 | +| 20 | 40 | 100000 | 0 | 6.17 | +| 20 | 80 | 100000 | 0 | 12.11 | + +| lattice size | points | samples | burn-in time | time (seconds) | +| ------------ | ------ | ------- | ------------ | -------------- | +| 20 | 20 | 100000 | 0 | 3.20 | +| 40 | 20 | 100000 | 0 | 11.91 | +| 80 | 20 | 100000 | 0 | 47.88 | + +| lattice size | points | samples | burn-in time | time (seconds) | +| ------------ | ------ | -------- | ------------ | -------------- | +| 20 | 20 | 100000 | 0 | 3.20 | +| 20 | 20 | 1000000 | 0 | 29.95 | +| 20 | 20 | 10000000 | 0 | 305.849 | + +| lattice size | points | samples | burn-in time | time (seconds) | +| ------------ | ------ | ------- | ------------ | -------------- | +| 20 | 20 | 100000 | 0 | 3.20 | +| 20 | 20 | 100000 | 5000 | 4.93 | +| 20 | 20 | 100000 | 10000 | 6.58 | + +We can see that changing the number of points, samples and burn-in time +changes the time in a linear fashion, while changing the size of the lattice +changes the time in a square fashion. + ## Credits -The Doxygen theme used here is +The Doxygen theme used here is [doxygen-awesome-css](https://github.com/jothepro/doxygen-awesome-css).