---
# System prepended metadata

title: Python Developer Documentation Main Page

---

# Python Developer Documentation Main Page

![](https://i.imgur.com/FXzNrNN.png)

This is the homepage for the Developer Documentation of the Python frontend of _Dice_, _DicePy_. On this site, you will find definitions for all of the functions that we use in the Input Generator and Visualisation sections of _DicePy_, as well as instructions for integrating support for a new problem into the code (see below).

### Links

| 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 | You are here |

---


<!-- ### Adding a new problem in Dice MC

Users can consider modifying the input generator in order to generate a different `params.txt` file. An example of what this may look like is this:

---
```
p_system 	= 'MY_PROBLEM'
run_equil 	= .FALSE.
run_restart 	= .FALSE.
write_restart 	= .FALSE.
write_chains 	= .TRUE.
write_log 	= .TRUE.
/
&PARAMETERS
QHO%steps 	= 1e7
QHO%burn_step 	= 1e4
QHO%thin_step 	= 10
QHO%rcut 	= 3.0
QHO%sigma 	= 5.5
QHO%alpha 	= 0.1, 1.0, 20
/
```

New settings can be output to the `params.txt` file by integrating the options into the `dice_write.py` file, providing the  -->

### Adding a new problem to Dice QMC

There are two main components to _DicePy_: the Input Generator and the Visualisation library. We will handle these sections separately.

#### Input Generator

The Input Generator `DicePy.dice_inputs` incorporates three other modules:

* `DicePy.dice_defaults` lists the default variables needed throughout the Input Generator, made to match the defaults in the Fortran backend code.
* `DicePy.dice_check` is used to check existing _params.txt_ files for any errors, to prevent further errors when running the Fortran backend code.
* `DicePy.dice_write` is used to write new _params.txt_ files, which are made by the Input Generator

##### `DicePy.dice_defaults`

Implementation of a new problem into `DicePy.dice_defaults` is perhaps the simplest of the three. Aside from implementing the new system into the `systems` list at the top of the module, the user will need to extend the lists for the globally shared parameters such as `d_vqmc_steps` and `d_sigma`, and add in new variables for problem-specific parameters such as in the `Parameters for QHO` and the `Parameters for H2plus` sections. 

The user will also need to add in a new `porder` list. These lists specify the order that parameter tags should be iterated through when checking an input file, in order to be consistent with files made by the Input Generator.

##### `DicePy.dice_check`

`DicePy.dice_check` makes use of a number of inner checking routines to ensure that values in a user's _params.txt_ are valid. When adding a new problem these do not need to be changed, but they will still be utilised within the `check_inputs` function. Most of this function can remain the same, but there are a couple of problem-specific sections that will need to be added to. 

The first section starts from the comment `# Check p_system of PARAMETERS namelist`. This section checks for the presence of the PARAMETERS namelist, and populates it if it is found to be empty. A `elif p_system=="your_system":` section will need to be added to the end here that automatically populates the PARAMETERS namelist with the values you just defined in `DicePy.dice_defaults`.

The second section also requires a similar extension to an existing `elif` statement, which checks through the system-specific variables supplied in the user's _params.txt_ and determines if they are of the correct type (boolean, float, etc.) using the aforementioned inner checking routines. Of note here are:

* `isvalid()`, which checks if a given `tag`'s `values` match one of the expected `options` from a predefined list.
* `check_float()`, which checks if a given `tag`'s value(s) are floats, and replaces them with the `tag`'s default values if not.
* `check_grid()`, which does the same as above but for a grid-type parameter, ie. a `(start, stop, num)` set of numbers to run a linear spacing function on, similar to numpy's `linspace`.

##### `DicePy.dice_write`

`DicePy.dice_write` makes use of a similar set of checking functions to the above, but also contains a set of querying functions. These prompt the user for a response in a variety of places throughout the Input Generator, and are made to be extensible to new problems being added. Of note here are:

* `isint()` and `isfloat()`, which check if the string `s` that they are passed is an integer or a float, respectively. These are used consistently throughout the writer to ensure that the user is providing the correct kind of input and not, for example, passing a float to the variable for the total number of VQMC steps, which should always be an integer.
* `query_default()`, which queries if a user wishes to use the `default` value for a `param`, as described in `DicePy.dice_defaults`.
* `query_step()`, which asks the user for a positive integer ie. a 'step' value, and `query_posfloat()`, which does the same for positive floats.
* `query_grid()`, which constructs a `(start, stop, num)` grid to be linearly spaced once in the Fortran backend, while checking that values in the grid are of the correct type to avoid errors.

The majority of the module is located in the `query_params()` function, which runs the user through the entirety of input generation using the above routines. Much of this function is not specific to a new problem and can be left as-is, but there are sections that check the value of the `sys` variable that will need to be constructed for a new problem. These might take a form similar to the following:

```python
# my_new_problem
elif sys=='f':

    # Query method of solving new problem
    tag = 'solve_method'
    print('')
    print('Which method would you like to use for solving my_new_problem?')
    print('a) Method 1')
    print('b) Method 2')
    response = input('Your response ("a" or "b"): ')
    # Check response
    options = ['a','b']
    while not (response in options):
        print('Error: Invalid response, please enter "a" or "b", without quotes.')
        response = input('Your response: ')
    # Record response
    settings = ['.TRUE.','.FALSE.']
    params[tag] = settings[options.index(response)]

    # Parameter information - my_new_param
    print('')
    print('Parameter "my_new param" is a very cool.')
    print('')

    if auto=='a':

        # Query start value parameter my_new_param
        tag='my_new_param'
        prompt='Enter starting guess value for my_new_param.
        temp = query_posfloat(prompt,tag,d_c)
        if temp!='':
            params[tag] = str(temp)   

        # Parameter information - my_new_grid
        print('')
        print('Quantity of interest "my_new_grid" is also very cool.')
        print('')

        # Check if user wants defaults
        tag = 'my_new_grid'
        use_def = query_default(tag, d_my_new_grid_problem)

        # If not defaults, query grid
        if use_def == 'n':
            mini, maxi, num = query_grid(tag)
            params[tag] = '{:}, {:}, {:}'.format(mini, maxi, num)
```

##### `DicePy.dice_inputs`

This module just contains the `dice_inputs()` function, which is simply a caller for the other modules. No extra work should be needed here.

---

#### Visualisation

DicePy reads in results using the `DicePy.dice_visualise` module, and is able to visualise the results generated by the main program. Writing additional visualisation options for different problems can be by simply adding a function to plot the positions sampled by the Markov chain, and a function which plots the energies and their uncertainties against the variational parameter. 

For example, for the QHO problem:
* `QHOEnergyPlot()` reads `results_file` and plots the energies against variational alpha values specified in the problem, as well as the uncertainties in the energies. The sliceby option allows one to plot only a section of the graph by typing the indices of the slice you are interested in.
* `QHOWfnPlot()` reads a file containing the Markov chains and plots the distribution of the QHO wave functions, also showing the energies of these positions as well. It can also plots an analytical solution for the wave function as well, if desired. 

Plots may want to take advantage of  the `plotly` or `matplotlib` libraries which have been used for the other functions in the module, but users can also decide to use other libraries as well when writing these functions.