Differences

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

--- potential_files [2013/02/28 13:24] – created daniel
+++ potfiles:main [2018/09/24 17:29] (current) – daniel
@@ Line 1: / Line 1: @@
-{{TOC_right}}
+~~NOTOC~~
-The interactions currently supported by ''potfit'' are either defined in terms of tabulated functions or given by analytic parameters. Typical functions are central pair potentials, which depend on the distance of two atoms and the two atom types involved. For tabulated potentials such functions are given with steps which are equidistant in the distance, which is the fundamental difference to [http://imd.itap.physik.uni-stuttgart.de/ IMD], where those functions are tabulated with steps equidistant in the square of the distance. For EAM interactions one also needs functions which depend on one atom type and the host electron density at the position of that atom. Such functions are tabulated with steps equidistant in the electron density. For analytic potentials only the parameters and the analytic form have to be given.
+====== Potential files ======
+----
+The interactions supported by //potfit// are defined in terms of tabulated functions, given by analytic parameters or with the KIM model name. Typical functions are central pair potentials, which depend on the distance of two atoms and the two atom types involved. Support for three-body potential has been added to //potfit// to support a wider range of interatomic potentials.
-=== Potential File Header ===
+Each potential file consists of a header and a body, just like the configurations. While the header format is the same for all supported potentials the body format is fundamentally different for tabulated, analytic and KIM potentials.
-The header is comparable to headers in [http://imd.itap.physik.uni-stuttgart.de/ IMD]. It specifies in which format the current file is, and how many data columns the tabulated function has for each argument. The number of data columns depends on the potential model used. The header has the following format:
+For potentials implemented in //potfit// the number of potentials and parameters required for each interaction is given on the bottom of each interaction page. For KIM potentials please see the [[potfiles:format5|KIM format]] page for details.
- ## this is just a comment line
+====  Potential File Header  ====
- #F 3 n
- #T <TYPE>
- #C Mg Zn
- #I 0 1 .... n entries (this line is optional)
- #G 2 3 .... n entries (this line is optional)
- ## this is another comment line
- #E this is the very last header line
-Header lines start with the hash character '#'. If the second character is 'F', then the format specifier 0, 3 or 4 (to distinguish from IMD potential files, format types 1 or 2) and the number n of data columns of the  functions are read from the rest of the line. The very last header line must have a character 'E' at the second position. Header lines with a second character different from 'C', 'F', 'E', 'T' or 'G' are treated as comments, but it is recommended that such lines start with two '#' characters.
+The header format is very similar to headers in [[http://imd.itap.physik.uni-stuttgart.de/|IMD]]. It specifies the format of the potential file and some other properties which are shared between the different potential representations. It has the following format:
-The line starting with #T specifies the type of potential this file contains. This is very helpful if you are dealing with different potentials. <TYPE> can be PAIR, EAM, ADP or ELSTAT.
+<code potfit>
+#F <format> <count>
+#T <interaction name>
+#C <element 0> <element 1> ...
+#I 0 1 ... n entries
+#G 2 3 ... n entries
+#E
+</code>
-The line I defines whether a whole potential function should be kept constant during a force matching run. Each digit corresponds to one function table, so there should be n digits in total. A value of '0' allows ''potfit'' to change the corresponding potential function, a value of '1' keeps it fixed. This is useful for example if a third component is to be added to a binary system and only the additional potentials are to be allowed to change.
+Header lines have to start with the number sign ''#''. Comments start with two number signs.
-The line G specifies whether the gradient of the interpolation splines should be treated as fixed or as an additional degree of freedom. Each digit corresponds to one function table, so there should be n digits in total. The information is bit-coded, '0' declares both lower and upper gradient fixed, '1' allows adjusting the gradient at the upper end, '2' at the lower end, and '3' at both ends. This does not apply to analytic potentials.
+The second character can be any of the following specifiers. Lines with unknown specifiers will be treated like comments, but it is recommended that such lines start with two ''#'' characters.
-The line C specifies the chemical elements the potentials belong to. Currently this line is not read for potentials, it is only given in the output to facilitate the handling of potential files. In addition there will also be a comment on how the potentials are ordered, for the ternary system AlPdMn a header for an EAM-potential could look like the following:
+Not all specifiers all mandatory, some of them are optional.
- #F 0 12
+== #F ==
- #C Al Pd Mn
- ## Al-Al Al-Pd Al-Mn Pd-Pd Pd-Mn Mn-Mn Al Pd Mn Al Pd Mn
- #I 0 0 0 0 0 0 0 0 0 0 0 0
- #E
-The order of the different potential functions for a specific potential can be found on the corresponding potential page.
+The mandatory format specifier ''#F'' needs to be the first non-comment line in the potential file.
+It requires two arguments, the format itself and the number of potential functions present in the file.
+Valid formats are:
+  * [[potfiles:format0|Format 0]] - analytic potentials
+  * [[potfiles:format3|Format 3]] - tabulated potentials with fixed spacing
+  * [[potfiles:format4|Format 4]] - tabulated potentials with variable spacing
+  * [[potfiles:format5|Format 5]] - KIM potentials
-=== Format 0 ===
+The value for the number of potential functions needs to be the correct value for the selected potential type.
+If the number of atom types in the parameter file is 2 and the potential is ''pair'', this value needs to be 3 because ''pair'' potentials require $n*(n+1) / 2$ potential functions. (KIM potentials do ignore this number)
-The potential format 0 is used for analytical potentials exclusively. All of the above apply here, except for the G line.
+== #T ==
-Every analytic potential has to be specified as follows:
+The optional interaction type specifier ''#T'' has one argument, the capitalized interaction name. This is helpful when dealing with multiple potential files for the same system. If the value is not present in the starting potential, //potfit// will add it to all potential files which are output.
- type identifier
+Even though this line is optional, a mismatch in the string and the compiled //potfit// binary will lead to a runtime error. A //potfit// binary compiled for ''PAIR'' potentials will only accept potential files which don't have a ''#T'' line or the interaction type set to ''PAIR''.
- cutoff value
- # rmin 1.0
- p_1 value min max
- p_2 value min max
- ...
-The type keyword has to be followed by the [[Analytic potentials/Functions|unique identifier]] for your potential. You can also enable the smooth cutoff option by adding a <tt>_sc</tt> at the end. After the <tt>cutoff</tt> keyword the cutoff radius for this potential has to be given. This is independent for every potential and can thus be different for different potentials. The next line starting with # is a comment which is written by ''potfit''. It indicates the minimum neighbor distance for this interaction. Following these lines, the values for the analytic parameters have to be specified. Each line starts with an identifier for that parameter followed by the starting value, the minimum and maximum value for that parameter. The order of these parameters is fixed, for the implemented analytic functions the order can be found [[Analytic potentials/Functions|here]].
+== #C ==
-A sample format 0 potential file for a binary system with an EAM potential is available [[Media:Format_0.pot.txt|here]].
+The optional line ''#C'' specifies the chemical elements the potentials belong to. This needs to match the
+order of chemical elements in the configuration file. In output files //potfit// will write a comment on how the potentials are ordered. For the ternary system AlPdMn this looks like this:
-=== Format 3 ===
+<code potfit>
+#C Al Pd Mn
+## Al-Al Al-Pd Al-Mn Pd-Pd Pd-Mn Mn-Mn Al Pd Mn Al Pd Mn
+</code>
-In a potential file in format 3, each data column has its own range and spacing. Sampling points are equidistant in the atomic distance r or (when using EAM-type interactions) electron density n. If we have n data columns, the file starts with n lines of the form
+== #I ==
- x_begin x_end steps
+The optional line ''#I'' defines whether a whole potential function should be kept constant during a force
+matching run. Each argument corresponds to one function, so there need to be as much digits as there are potential functions. A value of ''0'' allows //potfit// to change the corresponding potential function, a value of ''1'' keeps it fixed. This is useful for example if a third component is to be added to a binary system
+and only the additional potentials are to be allowed to change. If this line is omitted all potential functions will be optimized.
-specifying the start, end, and the number of function values in each data set. n data columns. The argument x is either the atom distance, or the host electron density. These n lines are then followed by n blocks with the function values, one for each atom type pair or atom type. The spacing of function values is computed from the begin, end, and number of function values of the corresponding table and can be different for the different data columns.
+== #G ==
-If the 'G' header line is specified, each data block must be preceded by two values specifying the gradient of the function at the lower and upper boundaries. A value of 10^30 or higher triggers the usage of natural splines (curvature 0 at boundaries). You should not make the gradient variable at boundaries where natural splines are specified. This will lead to undesired results.
+The optional line ''#G'' specifies whether the gradient of the interpolation splines should be treated as fixed
+or as an additional degree of freedom. Each argument corresponds to one potential function, so there should be
+n arguments in total. The information is bit-coded, ''0'' declares both lower and upper gradient fixed,
+''1'' allows adjusting the gradient at the upper end, ''2'' at the lower end, and ''3'' at both ends.
+This does not apply to analytic potentials.
-A sample format 3 potential file for a binary system for an EAM potential is available [[Media:Format_3g.pot.txt|with]] or [[Media:Format_3.pot.txt|without]] the #G header line.
+== #E ==
-=== Format 4 ===
+The last line of the header must have the ''#E'' specifier, which indicates the end of the header part.
-As with potential files in format 3 each data column has its own spacing. But with potential format 4 the requirement that the sampling points be equidistant is dropped. Arbitrarily spaced sampling points are possible, but the sampling points have to be given in order.
+----
-Preceding the data columns is a header with one line per column, containing the number of sampling points in the corresponding column. Seperated by blank lines then the data columns follow. Each of the columns has the form
+The order of the different potential functions for a specific potential can be found on the
+corresponding potential page.
- r_0     f(r_0)
- r_1     f(r_1)
- ...
- r_steps f(r_steps)
-Please note that <math>r_0 < r_1 < \ldots < r_{steps}\,</math> is required. The order of the columns is the same as with format 3.
-A sample format 4 potential file for a binary system (EAM potential) is available [[Media:Format_4g.pot.txt|here]] (with the #G header line).