This howto describes how you can add your own analytic potential function to potfit.

If you are familiar with C-programming you can continue with the Quick Guide. If you think you need a detailed explanation skip the Quick Guide and go directly to Section 2.

For your convenience there are templates provided int the source code to create new potentials. Just copy these templates and adjust the names and parameters to your needs. You can find the templates in the sourcecode starting with

/* template for new potential function called newpot */

and ending with

/* end of template */

To add a new potential you only have to edit 2 files:

• functions.h
• functions.c

The part of functions.h you have to edit is after the first block of declarations. You should choose a unique name for your potential and use it throughout the program to avoid naming conflicts. In this case we simply call it “example”. To add the declaration for your potential use something like:

void example_value(double, double *, double *);

In functions.c you have to make two changes. First you have to add your potential function to the internal function table. This is done in the apot_init function with the add_pot macro:

add_pot(example, 2);

The first argument is the name of your potential function (without quotes) and the second argument is the number of parameters your potential function requires.

Then you have to add your potential function. It might look like this:

void example_value(double r, double *p, double *f) {
  *f = r * p[[0]] + p[[1]] * sin(r);
}

The parameters passed to this function are:

• double r this is the distance for which the potential functions is evaluated
• double *p this is the parameter array for the analytic potential. They are passed in the same order as you specify them in your potential file.
• double *f this is used to return the function value

This howto will guide you through the process of adding a new analytic potential to the potfit program. If you have any questions please see Section 3 for help.

First you have to open the file functions.h in the potfit directory with your favorite editor. Scroll down until you see the template provided to create new potential functions:

/* template for new potential function called newpot */
 
/* "newpot" potential */
void  newpot_value(double, double *, double *);
 
/* end of template */

All you have to do is copy the lines 3 and 4 and paste them above the template.

Now you have to rename the potential and adjust the comment. Choose a unique identifier for your potential, consisting of letters, numbers and no special characters ( _ is fine). For now we call our potential “example”.

If you are finished with editing functions.h, it should look like this:

/* example potential */
void  example_value(double, double *, double *);
 
/* template for new potential function called newpot */
 
/* "newpot" potential */
void  newpot_value(double, double *, double *);
 
/* end of template */

Don't forget to save the file before you close it.

Now you have to open the file functions.c. This time you have to edit the file at 2 different places.

First scroll down until you find the function

void apot_init(void)

This function is used to determine the number of parameters of an analytic potential and assign the internal functions used.

To make your potential function available in potfit simply add a new line to this function that looks like this:

add_pot(example, 3);

Replace example with your unique potential identifier and 3 with the number of parameters required by the potential.

This is the last step and then you can use the new potential. Now you actually have to tell the program what your potential looks like. Therefore you have to add a new function that implements your analytic potential. But as always, there is a template provided, you only have to copy it.

Search the file for the following line:

/* template for new function */

Copy and edit the provided template. Then it should look like this:

/****************************************************************
 *
 * example potential
 *
 ****************************************************************/
 
void example_value(double r, double *p, double *f)
{
  *f = r + p[[0]] + p[[1]];
}

Now it's time to implement your potential.

Please only change the lines between { and }. You need to know the following things: *f is the value that is returned in the end. So the line beginning with *f = should be your last line of the function. There are two variables passed to your function, the distance r and the parameter array p. You can access them by simply using r for the distance and p[x] for the parameters, where x is a number (starting with 0). The order in which the parameters are passed to this function is the same that you specify them in your potential file.

Assume you would have the following potential:

 type example
 cutoff 4.000000
 alpha 2 0.000000 10.000000
 beta 0.4 0.000000 10.000000
 gamma 7.1 6.000000 8.000000

Then you could access the parameter called alpha as p[0], beta as p[1] and gamma as p[2]. Please note that this is a zero-based array (i.e. the first parameter is p[0] and not p[1]).

Now here's a little example: Suppose we have a potential like

$$\Phi(r) = \gamma*\exp\left(\frac{-r}{\alpha}\right)*\cos\left(\beta*r\right)$$

Then our potential function could look like this, assuming the potential file from above is used

void example_value(double r, double *p, double *f)
{
  *f = p[[2]] * exp(-r / p[[0]]) * cos(p[[1]] * r);
}

If you are finished with all of the above it's time to recompile potfit. First you should issue a make clean followed by make potfit_apot_pair.

If you encounter any errors be sure to check the syntax of the lines you changed.

In order to test the changes you made, you can set the parameter opt to 0 in your parameter file. Then run potfit once and the potential will only be evaluated and not optimized. After a successful run you can use the plotfile specified in your parameter file to plot your potential and maybe compare it to your references.

If you still need help with adding analytic potentials to potfit, feel free to contact the authors via the mailinglist provided here.