Adding Multi-Dimensional Potential Functions

There are four ways to add multi-dimensional potential functions to Quantics, depending on the form of the data or the functionality required by a routine. In order of ease of implementation (easiest first) these are:

1. Spline Fits To Data

If the data is in the form of energy values in au on a grid in up to 3D then Quantics can provide a potential surfaces using spline fits. For more information see the separate HowTo on Spline Fits .

2. User Defined Surfaces

For a stand-alone routine that returns the value of the potential at a grid point, there is an interface using the libusrf.so dynamic library. The interface to quantics allows functions to be added without recompiling the package.

Copy the file $QUANTICS_DIR/source/opfuncs/usersrf.f90 to a directory containing the new potential routines and edit it to provide the interface to the new routines. Three routines must be changed

udefsrf : Define the labels to specify the potentials. See Adding New Labels for details.
uvpoint : Add the call to the potential function See Calling the routine for details.
usersrfinfo : Add text to be written to the log file. See Logging the routine for details.

After this has been done compile the usersrf.F90 and new routines together to make a shared library libusrf.so . Either replace the library with this name in $QUANTICS_DIR/bin/dyn_libs or set the variable LD_LIBRARY_PATH to search the new directory first. A sample Makefile is provided here .

3. Surfaces Library

For a stand-alone routine that returns the value of the potential at a grid point, the function could also be placed in the directory $QUANTICS_DIR/source/surfaces and interfaced to the package by editing the routine $QUANTICS_DIR/source/surfaces/funcsrflib.f90 This effectively adds the function to the Quantics package and be added to the repository.

defsrflib : Define the labels to specify the potentials. See Adding New Labels for details.
vlibpoint : Add the call to the potential function See Calling the routine for details.
srflibinfo : Add text to be written to the log file. See Logging the routine for details.

After editing and adding the function, it is necessary to recompile the library and the full package by typing

compile -a libsrf
compile quantics

4. Quantics Function Library

For more complicated routines that require functionality from the Quantics package (e.g. other function modules) then the routine needs to be added to $QUANTICS_DIR/source/opfuncs and interfaced to the package by editing the routine $QUANTICS_DIR/source/opfuncs/funcsrf.f90 This requires greater knowledge of the package. The 3 routines

defsrf : Define the labels to specify the potentials. See Adding New Labels for details.
vpoint : Add the call to the potential function See Calling the routine for details.
surfinfo : Add text to be written to the log file. See Logging the routine for details.

must be edited as well as the package Makefile in the $QUANTCS_DIR/install directory, adding the new routines to the opfuncs.a function archive specified in the variable OPFUNCS. After editing the package needs to be recompiled using

compile quantics

1D Functions

----------------------

In all cases the interface works by providing information in three places. The basic idea is that a potential is defined in the HAMILTONIAN-SECTION of the .op file by a label that will be translated by Quantics into indices that point to the routine. For example, a 3D function may be defined in an operator by

Hamiltonian-section
modes | x | y | z
1.0   |1&2&3 V
end-Hamiltonian-section

labels-section
V = newsrf
end-labels-section

Details are given in the Hamiltonian Documentation , but in brief a potential V(x,y,z) is being defined (the 1&2&3 refer to the modes covered by the function V) and in the labels-section this potential is called newsrf.

In the following sections details are given as to how to add the interface for the user defined surface library, but the procedure is the same for the other libraries. See the file $QUANTICS_DIR/source/opfuncs/usersrf.f90 for the structure.

Adding New Labels

After reading the operator, Quantics searches the function libraries for the label newsrf and when it finds it assigns 2 numbers

ifile: an integer defining the routine the function is in
hopilab: an integer defining which function it is in the routine.

These need to be defined in the routine udefsrf in the if-block replacing mysrf with newsrf. This assigns a value of hopilab=1. The variable ifile=203 is then also assigned so that Quantics knows to look in the subroutine uvpoint to find the call to the newsrf function. Further functions, such as mysrf1, can then be defined incrementing hopilab by 1 each time.

Calling the routine

When Quantics needs to calculate the potential using the newsrf routine at a grid point the specification in udefsrf means it knows to look in the subroutine uvpoint for the function no. 1. The call to the routine needs to be added in the select-block, replacing the call to mysrf with the call to newsrf. the vector gpoint contains the grid point coordinates in au in the order specified in the primitive-basis-section of the input file. Thus if the 3 DOF in the example were defined as

primitive-basis-section
x fft 51 -5 5
y fft 51 -5 5
z fft 51 -5 5
end-primitive-basis-section

gpoint(1) is the x-coordinate, gpoint(2) the y-coordinate and gpoint(3) the z-coordinate.

Further functions are simply added as subsequent calls in the select-block with case numbers matching the hopilab parameter specified in udefsrf.

NB: Before the call coordinate transformations can be made if e.g. the calculation is in Jacobi coordinates and the potential function in binding coordinates.

Logging the routine

The final information to be added is not mandatory but useful, namely some text that is written to the log file to ensure the correct routine is called, the coordinates are in the desired order, and any appropriate referencing information. This is added in usersurfinfo in the select-block, editing the dummy text for MYSRF.

Potentials