potfit wiki

open source force-matching

User Tools

Site Tools

models:adding_analytic_functions

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
models:adding_analytic_functions [2019/02/23 09:51] – ↷ Page moved from adding_analytic_functions to models:adding_analytic_functions danielmodels:adding_analytic_functions [2019/06/20 11:00] (current) – Major update daniel
Line 3: Line 3:
 ---- ----
  
-This howto describes how you can add your own analytic potential function to //potfit//.+This page 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|Quick Guide]]. If you think you need a detailed explanation skip the Quick Guide and go directly +First you should choose a unique name for your potential and use it throughout the 
-to [[#Detailed Guide|Section 2]]. +program to avoid any naming conflicts. In this case we simply call it "my_function".
- +
-====== Quick Guide ====== +
- +
-==== Templates ==== +
- +
-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 +
- +
-<code>/* template for new potential function called newpot */</code> +
- +
-and ending with +
- +
-<code>/* end of template */</code>+
  
 ==== Things you need to adjust ==== ==== Things you need to adjust ====
  
-To add a new potential you only have to edit 2 files: +To add a new potential you have to edit the following two files in the src/ directory: 
-  * functions.h    +  * functions.itm 
-  * functions.c  +  * functions_impl.c
  
-=== functions.h ===+=== functions.itm ===
  
-The part of functions.h you have to edit is after the first block of declarations. +This file is used to declare your new potential function. The only thing you have 
-You should choose a unique name for your potential and use it throughout the +do is add a new line anywhere which uses the FUNCTION macro. The macro takes two arguments, 
-program to avoid naming conflicts. In this case we simply call it "example". +the first one being the name of your function and the second one being the number of 
-To add the declaration for your potential use something like:+parameters the function requires.
  
-<code c>void example_value(double, double *, double *);</code>+For our example function "my_function", which takes 3 arguments, we would add this
  
-=== functions.c ===+<code c>FUNCTION(my_function, 3);</code>
  
-In functions.c you have to make two changes. First you have to add your potential function to the internal function table. +Please note that there are **no** quotes around the function name!
-This is done in the ''apot_init'' function with the ''add_pot'' macro:+
  
-<code c>add_pot(example, 2);</code>+=== functions_impl.c ===
  
-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.+The actual definition of your potential function goes into this file. 
 +Just add it at the very end of the file if you are not sure where you should put it.
  
-Then you have to add your potential function. +The name of the function is the same as from the FUNCTION macro but with "_value" added at the end. 
-It might look like this:+For our example function "my_function" it might look like this:
 <code c> <code c>
-void example_value(double r, double *p, double *f) {+void my_function_value(const double r, const double* p, double* f) {
   *f = r * p[[0]] + p[[1]] * sin(r);   *f = r * p[[0]] + p[[1]] * sin(r);
 } }
Line 55: Line 41:
 The parameters passed to this function are: The parameters passed to this function are:
  
-  * ''double r'' this is the distance for which the potential functions is evaluated    +  * ''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.    +  * ''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  +  * ''f'': this is used to return the function value  
  
 ---- ----
Line 63: Line 49:
 ====== Detailed Guide ====== ====== Detailed Guide ======
  
-This howto will guide you through the process of adding a new analytic potential to +If you are not too familiar with C programming here are some more details which should help you 
-the //potfit// program. If you have any questions please see [[#If_you_still_need_help|Section 3]] for help. +with the process of adding a new analytic potential to //potfit//.
- +
-===== Step 1 - Editing the file ''functions.h'' ===== +
- +
-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: +
-<code c> +
-/* template for new potential function called newpot */ +
-  +
-/* "newpot" potential */ +
-void  newpot_value(double, double *, double *); +
- +
-/* end of template */ +
-</code> +
-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: +
-<code c> +
-/* 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 */ +
-</code> +
-Don't forget to save the file before you close it. +
- +
-===== Step 2 - Editing the file ''functions.c'' ===== +
- +
-Now you have to open the file functions.c. This time you have to edit +
-the file at 2 different places. +
- +
-==== functions.c - part I ==== +
-First scroll down until you find the function +
-<code c> +
-void apot_init(void) +
-</code> +
-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: +
-<code c> +
-add_pot(example, 3); +
-</code> +
-Replace ''example'' with your unique potential identifier and 3 with the number of parameters required by the potential. +
- +
-==== functions.c - part II ==== +
- +
-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:+Copy the following template to the bottom of the functions_impl.c file:
 <code c> <code c>
 /**************************************************************** /****************************************************************
  *  *
- * example potential+ * my_function potential
  *  *
  ****************************************************************/  ****************************************************************/
  
-void example_value(double r, double *p, double *f)+void my_function_value(const double r, const double* p, double* f)
 { {
   *f = r + p[[0]] + p[[1]];   *f = r + p[[0]] + p[[1]];
Line 168: Line 91:
 Suppose we have a potential like Suppose we have a potential like
  
-$$\Phi(r) = \gamma*\exp\left(\frac{-r}{\alpha}\right)*\cos\left(\beta*r\right)$$+$$\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 Then our potential function could look like this, assuming the potential file from above is used
 <code c> <code c>
-void example_value(double r, double *p, double *f)+void example_value(const double r, const double* p, double* f)
 { {
   *f = p[[2]] * exp(-r / p[[0]]) * cos(p[[1]] * r);   *f = p[[2]] * exp(-r / p[[0]]) * cos(p[[1]] * r);
Line 178: Line 101:
 </code> </code>
  
-===== Step 3 - recompiling the program =====+===== Recompiling the program =====
  
-If you are finished with all of the above it's time +If you are finished with all of the above it's time to recompile //potfit// by  
-to recompile //potfit//. First you should issue a ''make clean'' +simply calling './waf' from the root directoy.
-followed by ''make potfit_apot_pair''.+
  
-If you encounter any errors be sure to check the syntax of +If you encounter any errors be sure to check the syntax of the lines you changed. 
-the lines you changed.+Usually the compiler will give you some hint what is wrong or where you have to look.
  
-===== Step 4 - testing the program =====+===== Testing the program =====
  
 In order to test the changes you made, you can set the parameter In order to test the changes you made, you can set the parameter
Line 196: Line 118:
 compare it to your references. compare it to your references.
  
-====== If you still need help ======+===== If you still need help =====
  
 If you still need help with adding analytic potentials to //potfit//, feel free If you still need help with adding analytic potentials to //potfit//, feel free
-to contact the authors via the mailinglist provided [[Mailinglist|here]].+to contact the authors as described [[::Contact|here]].
  
models/adding_analytic_functions.1550911876.txt.gz · Last modified: 2019/02/23 09:51 by daniel