# Dice User Manual


### **Contents**
* [About](#About)
* [Abbreviations](#[Abbreviations])
* [Code Structure](#Code-Structure)
* [Dependencies](#Dependencies)
* [Python Dependencies](#Python-Dependencies)
* [Fortran Dependencies](#Fortran-Dependencies)
* [Compilation](#Compilation)
* [Running Dice](#Running-Dice)
* [Unit Testing](#Unit-Testing)
* [Running VQMC](#Running-VQMC)
* [Tutorial](#Tutorial)
* [Input Options](#Input-Options)
* [&CONTROL](#ampCONTROL)
* [&PARAMETERS](#ampPARAMETERS)
* [Quantum Harmonic Oscillator Options](#Quantum-Harmonic-Oscillator-Options)
* [Hydrogen Molecular Ion Options](#Hydrogen-Molecular-Ion-Options)
* [Hydrogen Molecule Options](#Hydrogen-Molecule-Options)
* [Further Documentation](#Further-Documentation)
* [Design Document](#Design-Document)
* [Software Specification](#Software-Specification)
* [Work Plan](#Work-Plan)
* [Upcoming Features](#Upcoming-Features)
* [Contributors](#Contributors)
* [Disclaimer](#Disclaimer)
* [Acknowledgement](#Acknowledgement)

---

### **About**
Group A created a piece of software called ***Dice*** to run Variational Quantum Monte Carlo (VQMC) simulations. It is capable of determining the ground state energy and wave functions of the following systems: the quantum harmonic oscillator, the hydrogen ion and the hydrogen molecule. This was achieved with a high-performance parallel backend code, written in Fortran and a Python frontend for input generation and results visualisation. The software release date is on Thursday 27th May 2021.

This document is the User Manual, containing all the information that a user may need to get up and running with ***Dice***, including dependencies, installation instructions, a detailed brekdown of the parameters passable to the program, as well as some helpful tips to get the most out of your VQMC calculations.

The developer documentation of ***Dice*** has been generated using [Doxygen](https://www.doxygen.nl/index.html), and is available at the links below. As a documentation generator, Doxygen extracts information from specially-formatted comments within the code. Documentations are available in the format of HTML files to guide both users and developers of the code.

| Destination | Link |
| ----------- | ---- |
| GitHub | [Here](https://github.com/HetSys/PX915_2021_A) |
| Dev Documentation Main | [Here](https://joegilkes.github.io/PX915-Docs/) |
| Fortran Dev Documentation | [Here](https://joegilkes.github.io/PX915-Docs/fortran/docs/index.html) |
| Python Dev Documentation | [Here](https://joegilkes.github.io/PX915-Docs/python/docs/index.html)

[↑ Back to Contents](#Contents)

---

### **Abbreviations**
|Abbreviation|Original Phrase|
|----|----------|
|FAQ|Frequently Asked Questions|
|MCMC|Markov Chain Monte Carlo|
|MMC|Metropolis Monte Carlo|
|MPI|Message Passing Interface|
|[NetCDF](https://www.unidata.ucar.edu/software/netcdf/)|Network Common Data Form|
|QHO|Quantum Harmonic Oscillator|
|QMC*|Quantum Monte Carlo|
|VQMC*|Variational Quantum Monte Carlo|

*Note: QMC and VQMC are used interchangeably in this version of the software.

[↑ Back to Contents](#Contents)

---

### **Code Structure**

***Dice*** consists of two main parts - a high-performance parallel backend coded in Fortran, and a Python frontend that handles user-friendly input generation and results analysis. Together, these form a powerful tool for performing VQMC simulations with speed and accuracy.

[↑ Back to Contents](#Contents)

---

### **Dependencies**

Since the code comes in two parts, the Python and Fortran dependencies are specified separately:

#### Python Dependencies

To use the frontend input generation and visualisation scripts, you must be running [Python 3](https://www.python.org/downloads/) (versions from 3.6.6 and above have been tested and confirmed to work) and have the following modules installed:
* Numpy
* Matplotlib
* Pandas
* f90nml
* Plotly
* netCDF4
* (may need more here)

These can all be installed manually through package managers such as Pip or Anaconda, but can more easily be installed through the _requirements.txt_ file in the code repository. This can be done by running `pip install -r requirements.txt` from the terminal while in the root folder of the repository. If you are on a managed system, such as the SCRTP network, you may need to use `pip install --user -r requirements.txt` instead. This will collect all the necessary dependencies for you and install them in the currently active environment.

#### Fortran Dependencies

To compile and use the Fortran backend of ***Dice***, you will need the following:
* An MPI-aware Fortran 2008 compiler (eg. mpif90, mpifort, mpiifort) and corresponding MPI binaries
* netCDF-fortran
* GNU make

The following are known good configurations of modules on the SCRTP network that can be loaded as an environment for the backend code:

| Compiler | MPI | `module` Command |
| -------- | -------- | -------- |
| Intel Fortran/C 17.4 | IMPI 17.3 | `module load intel/2017.4.196-GCC-6.4.0-2.28 impi/2017.3.196 Python/3.6.6 netCDF/4.4.1.1 netCDF-Fortran/4.4.4` |
| GNU Fortran/C 7.3 | OpenMPI 3.1.1 | `module load GCC/7.3.0-2.30 OpenMPI/3.1.1 Python/3.6.6 netCDF/4.6.1 netCDF-Fortran/4.4.4` |

Ensure to use `module purge` before running either of these commands to ensure that your current environment is cleared.

[↑ Back to Contents](#Contents)

---

### **Compilation**

Clone the latest stable version of ***Dice*** from our Github repository (linked above) into a new folder using `git clone https://github.com/HetSys/PX915_2021_A.git`. Ensure your terminal environment has access to the dependencies described above, then edit the Makefile so that the line `FC = [compiler]` contains the name of your MPI-aware Fortran compiler (without the square brackets). If you are using a GNU compiler, this may be either `mpif90` or `mpifort`. If you are using an Intel compiler, this may be either `mpif90` or `mpiifort` (note the extra i), although the former has had trouble linking to the netCDF libraries in our testing, so should probably be avoided.

Now you are ready to compile the code. While in the root directory of the repository, type `make`. This will compile the code with your chosen compiler. If you are recompiling the code, use `make clean` first to reset the repository to a compilable state. These can be combined for ease of use when testing compilation options to `make clean && make`, which will reset the repository and then recompile the code.

[↑ Back to Contents](#Contents)

---

### **Running _Dice_**

#### Unit Testing

Before you start any VQMC calculations with ***Dice***, you should ensure that the code has compiled correctly by running the inbuilt unit tests. These run through all the main functions of the code with predefined inputs and test for the same results as a set of prerun, expected results.

You can run the unit tests by creating a _params.txt_ input file. This can either be done manually in a text editor, or by using the included Python input generator script _scriptname.py_. For first time users, we recommend the latter of the two methods.

Run the input generator by typing `python scriptname.py`. You will be prompted to write or check an input file, for which you should chose to write one, and then you will be presented with the currently available systems to run VQMC on. At the bottom of this list will be the unit tests, under 'Run Test Cases'. Select this option, and the input generator will exit.

There will now be a file called _params.txt_ in ***Dice***'s root directory. This file contains the input parameters for the Fortran backend program that you just compiled. For more information on the layout and contents of _params.txt_, see the **Input Options** section.

Now you can run these unit tests by typing `./Dice`. The code will then run through its unit tests and, if all is well, report successes across the board. If a unit test does fail, check that you compiled the code correctly, and that you haven't modified any of the source files.

#### Running VQMC

In general, there is a workflow for using ***Dice*** for VQMC calculations:


This process is explained thoroughly in the **tutorial**, so it will not be covered in great detail here. However, the basic procedure is as follows:
* Choose a system to work on, and generate an input _params.txt_ in equilibration mode. In this mode, ***Dice*** will generate a set of Markov chains across a defined parameter grid, which will be output to `./equil_out`.
* Run ***Dice*** to generate these files. In the output, an acceptance rate for the Markov chain will be reported at each parameter step. This should be approximately 0.3 in all the cases you are testing, and can be tuned to this value by modifying the chosen system's _sigma_ parameter (see **Input Options**).
* Open these equilibration outputs in the burning/thinning visualisation tool. This tool helps you to determine the optimal number of steps from the Markov chain to burn (ignore while the chain thermalises) and the interval to thin over (so every _thin\_interval_ steps, a new energy is added to the energy chain to reduce correlation between samples).
* Use these optimised burning/thinning values to generate a new input, this time in full VQMC mode.
* Run ***Dice*** again. This time, the Markov chain will be properly thermalised and the samples will be decorrelated. In the case of a QHO run, it will output a set of energies for the parameter array it has been given. In the case of a $H_{2}^{+}$ or $H_{2}$ run, it will optimise the variational parameter to get the lowest energy at each given H-H bond length, and report these energies.
* Analyse the results. ***Dice*** includes Python functions to plot these energies, as well as to visualise the wavefunctions at a given parameter and/or bond length (if you have specified the `write_chains = .TRUE.` option in the input).

Again, for a detailed walkthrough of this process, please use the **tutorial**.

[↑ Back to Contents](#Contents)

---

### **Tutorial**
A good tutorial should:
* enable users to learn on-demand
* be accessible independent of time and location
* be able to stop, repeat and skip sections as needed

Based on these guidelines, Group A created a tutorial hoping to teach the users how to use ***Dice***. The tutorial is the format of a Jupyter Notebook named and it is names *Tutorials_outline.ipynb*. The tutorial can be accessed from the program’s main GitHub repository.

[↑ Back to Contents](#Contents)

---

### **Input Options**

The input file _params.txt_ is made in Fortran's namelist format. It is composed of two sections - &CONTROL and &PARAMETERS. &CONTROL specifies program-wide options for the Fortran backend of ***Dice***, while &PARAMETERS specifies problem-specific options. All available options, as well as their defaults, are listed in the tables below. Sample inputs are also provided as an example in the `sample_inputs` folder of the repository.

#### &CONTROL

| Option | Description | Type | Defaults/\[Available Options\] |
| -------- | -------- | -------- | -------- |
| p_system | The system of interest to run calculations on | character | [QHO\|H2plus\|H2\|Test] |
| run_equil | Whether to run ***Dice*** in equilibration mode or not | logical | .FALSE. |
| run_restart | Whether to restart from available restart files | logical | .FALSE. |
| write_restart | Whether to write restart files | logical | .TRUE. |
| write_chains | Whether to write out optimal Markov chains for visualisation | logical | .FALSE. |
| write_log | Whether to write a log file as the calculation progresses | logical | .FALSE. |

#### &PARAMETERS

##### Quantum Harmonic Oscillator Options

| Option | Description | Type | Defaults/\[Available Options\] |
| ------ | ----------- | ---- | ------------------------------ |
| QHO%steps | Total number of steps for each MMC chain (before burning and thinning) | integer(int32) | 1000000 |
| QHO%burn_step | Number of steps to be burnt from the start of the MMC chain | integer(int32) | 10000 |
| QHO%thin_step | Interval of steps by which the MMC chain is thinned | integer(int32) | 10 |
| QHO%rcut | Maximum initial distance of the MMC chain away from the origin | real(real64) | 3.0 |
| QHO%sigma | Standard deviation for proposed MMC moves | real(real64) | 5.5 |
| QHO%alpha | (Start, Stop, Num) Linearly spaced grid of variational parameter alpha values to obtain energies for | real(real64) | 0.1, 1.0, 10.0 |

##### Hydrogen Molecular Ion Options

| Option | Description | Type | Defaults/\[Available Options\] |
| ------ | ----------- | ---- | ------------------------------ |
| H2plus%steps | Total number of steps for each MMC chain (before burning and thinning) | integer(int32) | 1000000 |
| H2plus%burn_step | Number of steps to be burnt from the start of the MMC chain | integer(int32) | 10000 |
| H2plus%thin_step | Interval of steps by which the MMC chain is thinned | integer(int32) | 10 |
| H2plus%rcut | Maximum initial distance of the MMC chain away from the origin | real(real64) | 3.0 |
| H2plus%sigma | Standard deviation for proposed MMC moves | real(real64) | 1.8 |
| H2plus%auto_params | Whether to use optimise variational parameter values by automatic gradient-descent searching or by linear-spaced grid searching | logical | .FALSE. |
| H2plus%c | Starting guess value of variational parameter c (automatic parameter search) | real(real64) | 0.7 |
| H2plus%c1 | (Start, Stop, Num) Linearly spaced grid of variational parameter c values to obtain best energy for (grid search) | real(real64) | 0.7, 0.75, 10.0 |
| H2plus%bond | (Start, Stop, Num) Linearly spaced grid of H-H bond lengths to find energies for | real(real64) | 1.0, 4.0, 10.0 |
| H2plus%c_fdstep | Finite difference step size to use in calculation of gradient with respect to parameter c | real(real64) | 0.001 |
| H2plus%ham_fdstep | Finite difference step size to use in calculation of laplacian in Hamiltonian | real(real64) | 0.001 |

##### Hydrogen Molecule Options

| Option | Description | Type | Defaults/\[Available Options\] |
| ------ | ----------- | ---- | ------------------------------ |

[↑ Back to Contents](#Contents)

---

### **Further Documentation**

#### **Design Document**
The [Design Document](https://github.com/HetSys/PX915_2021_A/files/6503937/PX915.Group.Project.Design.Document.-.Group.A.pdf) for ***Dice*** explains the following topics in details:
* Code Structure
* Algorithms
* Parallelism methods
* Error Handling
* Documentation
* Collaboration mechanisms

#### **Software Specification**
The [Software Specification](https://github.com/HetSys/PX915_2021_A/files/6503938/PX915.Group.Project.Software.Specification.-.Group.A.pdf) document will discuss ***Dice***'s' *Performance*, *Input*, *Output*, *Engine*, *Analysis* and *Extensions* in details.

#### **Work Plan**
The initial work plan for ***Dice*** can be found in details in [Work Plan Explanation](https://github.com/HetSys/PX915_2021_A/files/6503942/PX915.Group.Project.Workplan.Explanation.-.Group.A.pdf). This document has shown a clear division of labour during the five weeks that Group A will have to work on the project.

[↑ Back to Contents](#Contents)

---

### **Upcoming Features**
New functionalities and performance improvement come with next software updates:
* The input file needed to run ***Dice*** will be generated interactively avoiding tedious formatting for the user
* Introduce troubleshooters and step-by-step instructions for errors that are difficult to explain in a single sentence.
* Introduce the use of progressive disclosure to provide information. The error messages will contain steps hidden by default, and when the users want to learn more about the error, they could click “How to fix it” to explore more.

***Dice*** is updated continuously. Every time Group A fix a bug or add a feature, Group A will release it immediately. Each dated copy of ***Dice*** contains all the features and bug-fixes up to and including that version date. The version date is printed to the screen and logfile every time when a user runs ***Dice***. It is on the first page of the HTML version of the manual. It is also in the file src/version.h and in the ***Dice*** directory name created when a user unpacks a tarball.

* In the HTML documentation pages accessed on the GitHub site, they always describe the most current version of ***Dice***.
* In the HTML documentation pages included in the tarball, they describe the version a user have downloaded.

[↑ Back to Contents](#Contents)

---

### **Contributors**
|Name|Warwick ID|
|----|----------|
|[Omar Adesida](https://warwick.ac.uk/fac/sci/hetsys/people/studentscohort2/omaradesida/)|1606763|
|[Iain Best](https://warwick.ac.uk/fac/sci/hetsys/people/studentscohort2/iainbest)|2082383|
|[Joe Gilkes](https://warwick.ac.uk/fac/sci/hetsys/people/studentscohort2/josephgilkes)|1707205|
|[Tadashi Matsumoto](https://warwick.ac.uk/fac/sci/hetsys/people/studentscohort2/tadashimatsumoto)|1607993|
|[Lakshmi Shenoy](https://warwick.ac.uk/fac/sci/hetsys/people/studentscohort2/lakshmishenoy)|2083012|
|[James Targett](https://warwick.ac.uk/fac/sci/hetsys/people/studentscohort2/jamestargett)|1712327|

Group Project Supervisor: [Dr. James Kermode](https://warwick.ac.uk/fac/sci/eng/staff/jrk/)

[↑ Back to Contents](#Contents)

---

### **Disclaimer**
***Dice*** is completed to fulfill the module assessment criteria of PX915 Modelling of Heterogeneous Systems Group Project and Peer-to-peer Project Evaluation. Hence it shall not be used for any commercial purpose.

The contributors declare no conflict of interest.

[↑ Back to Contents](#Contents)

---

### **Acknowledgement**
Group A would like to show our gratitude to [Engineering and Physical Sciences Research Council (EPSRC)](https://epsrc.ukri.org/) and [Centre for Doctoral Training in Modelling of Heterogeneous Systems (HetSys)](https://warwick.ac.uk/fac/sci/hetsys/) for sponsoring us throughout this project. The funding has relieved us from financial hardship which allowed us to solely focus on the project.

Group A would like to thank the [Department of Physics](https://warwick.ac.uk/fac/sci/physics/), the [School of Engineering](https://warwick.ac.uk/fac/sci/eng/), and the [Research Software Engineering (RSE)](https://warwick.ac.uk/research/rtp/sc/rse/) Group for providing thorough guidance for the entire duration of the project. Their invaluable expertise has greatly assisted and encouraged us when we were formulating our methodologies. Their insightful feedback during the project has pushed us to sharpen our thinking and lead our work to a much higher level.

Group A would like to thank our Group project supervisor, [Dr James Kermode](https://warwick.ac.uk/fac/sci/eng/staff/jrk/), for providing wise counsel on a regular basis which positively impacted the project's outcome.

Group A would like to acknowledge all the useful software tips from [HetSys student cohort one](https://warwick.ac.uk/fac/sci/hetsys/people/ab101/). These tips have greatly improved our efficiency which made it possible to complete the project within time.

In addition, Group A would like to thank our families and friends for their unconditional support and sympathetic ears. They have always been there for us by offering pleasant distractions to rest our mind outside of the project.

[↑ Back to Contents](#Contents)

---