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
Dev Documentation Main	Here
Fortran Dev Documentation	Here
Python Dev Documentation	You are here

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:

# 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.

This documentation was generated from commit ece8004