ML AB: Difference between revisions

From VASP Wiki
No edit summary
No edit summary
 
(36 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This file is used within the machine learning force field method. It contains the ab initio data from previous calculations: Bravais matrices, atom positions, energies, forces and stress tensors (the charge is also written out but only optionally used) . It is used for continuation runs ({{TAG|ML_ISTART}}=1 or {{TAG|ML_ISTART}}=2). The updated data is written to {{TAG|ML_ABN}}. Essentially the {{TAG|ML_AB}} and the {{TAG|ML_ABN}} files are the same and for continuation runs the {{TAG|ML_ABN}} file is just copied to {{TAG|ML_AB}}.
{{DISPLAYTITLE:ML_AB}}
This file is used as input (with file name {{FILE|ML_AB}}) and output ({{FILE|ML_ABN}}) within the machine learning force field method. It contains the collection of ab initio data from previous calculations: Bravais matrices, atom positions, energies, forces, and stress tensors. Depending on the mode of operation it is used in the following ways:


Here is a sample output how this file should look like:
* '''{{TAGO|ML_MODE|train}}, starting from scratch:''' A complete {{FILE|ML_ABN}} file containing all ab initio data and the list of current local reference configurations is written whenever a learning step is performed (check the line <code>STATUS</code> in the log file {{FILE|ML_LOGFILE}} for entries <code>learning</code> and <code>critical</code>).
* '''{{TAGO|ML_MODE|train}}, continuation run:''' Same {{FILE|ML_ABN}} output as above. In addition, upon start-up, the user-provided {{FILE|ML_AB}} file is read and an initial machine-learned force field is generated from the contained data.
* '''{{TAGO|ML_MODE|select}}, reselection of local reference configurations:''' Same {{FILE|ML_ABN}} output as for {{TAGO|ML_MODE|train}}. The {{FILE|ML_AB}} file is read and the contained structures are fed sequentially to the on-the-fly training algorithm. The list of local reference configurations in the {{FILE|ML_AB}} file is ignored, however, a dummy section must still be present (see below).
{{NB|tip|The {{FILE|ML_AB}} file is not required for {{TAGO|ML_MODE|run}} (prediction only) because all necessary data (e.g. descriptors of local reference configurations) are already stored in the {{FILE|ML_FF}} file.}}
An {{FILE|ML_ABN}} output file from {{TAGO|ML_MODE|train, select}} can always be reused as input for {{TAGO|ML_MODE|train, select}} by just renaming (copying) it to {{FILE|ML_AB}}.
 
== Example ==
 
As an example, here is a shortened version of an actual {{FILE|ML_AB}} file:
<pre>
  1.0 Version
  1.0 Version
**************************************************
**************************************************
      The number of configurations
    The number of configurations
--------------------------------------------------
--------------------------------------------------
          10
        299
**************************************************
**************************************************
      The maximum number of atom type
    The maximum number of atom type
--------------------------------------------------
--------------------------------------------------
        1
      5
**************************************************
**************************************************
      The atom types in the data file
    The atom types in the data file
--------------------------------------------------
--------------------------------------------------
      Si
    Pb I  C
  **************************************************
    N H
      The maximum number of atoms per system
**************************************************
--------------------------------------------------
    The maximum number of atoms per system
              64
--------------------------------------------------
**************************************************
            96
      The maximum number of atoms per atom type
**************************************************
--------------------------------------------------
    The maximum number of atoms per atom type
              64
--------------------------------------------------
**************************************************
            48
      Reference atomic energy (eV)
**************************************************
--------------------------------------------------
    Reference atomic energy (eV)
   -0.785951000000000
--------------------------------------------------
**************************************************
   -72.5297190000000      -35.4081430000000      -2.39269120000000
      Atomic mass
  -4.60003440000000      -1.12020270000000
--------------------------------------------------
**************************************************
    28.0850000000000
    Atomic mass
**************************************************
--------------------------------------------------
      The numbers of basis sets per atom type
  20.0000000000000        20.0000000000000        12.0110000000000
--------------------------------------------------
  14.0010000000000        8.00000000000000
        10
**************************************************
**************************************************
    The numbers of basis sets per atom type
      Basis set for Si
--------------------------------------------------
--------------------------------------------------
      130  1202  128
          1     53
      125  790
          2     3
**************************************************
          3     19
    Basis set for Pb
          4     62
--------------------------------------------------
          5     51
          1      1
          6     41
        100     8
          7    49
          1      3
          8      3
        100      4
          9    64
          1      5
          10    56
          1      6
**************************************************
...
      Configuration num.     1
...
==================================================
...
      System name
**************************************************
--------------------------------------------------
     Basis set for I
      Si_liquid
--------------------------------------------------
==================================================
          1      9
      The number of atom types
          1    10
  --------------------------------------------------
        100    32
        1
        100    31
==================================================
          1    13
      The number of atoms
        100    29
--------------------------------------------------
          1    15
          64
          1    16
  **************************************************
...
      Atom types and atom numbers
...
--------------------------------------------------
  ...
      Si     64
**************************************************
  ==================================================
    Basis set for C
      Primitive lattice vectors (ang.)
--------------------------------------------------
--------------------------------------------------
        100    39
  11.0072130000000        0.000000000000000E+000 0.000000000000000E+000
        101    40
  0.000000000000000E+000  11.0072130000000        0.000000000000000E+000
        104    40
  0.000000000000000E+000  0.000000000000000E+000  10.1908520000000
        101    39
==================================================
        101    38
      Wycoff positions (Cartesian)
        108    40
--------------------------------------------------
        101    37
    0.69872000000000        2.47436000000000        7.82749000000000
...
    6.37825000000000        1.01296000000000        3.70012000000000
...
    5.47749000000000        3.63097000000000        7.54054000000000
  ...
    4.52326000000000        10.2439400000000        5.06801000000000
**************************************************
    ...                    ...                    ...
    Basis set for N
    ...                    ...                    ...
--------------------------------------------------
==================================================
          1     41
      Total energy (eV)
        100    47
--------------------------------------------------
          1    43
  -302.800146000000
          1    44
==================================================
        100    45
      Forces (eV ang.^-1)
          1    46
--------------------------------------------------
  ...
  0.256099000000000      -0.510102000000000      0.652442000000000
...
  -0.538669000000000      7.069000000000000E-002  3.899200000000000E-002
...
  0.189456000000000      0.566218000000000      2.230000000000000E-004
**************************************************
  -1.485015000000000      0.755044000000000      0.261758000000000
    Basis set for H
  -0.285376000000000      -0.341509000000000      -1.00031200000000
--------------------------------------------------
  ...                    ...                    ...
        101    96
  ...                    ...                    ...
        108    96
==================================================
        101    95
      Stress (kbar)
        101    94
--------------------------------------------------
        108    95
      XX YY ZZ
        101    93
--------------------------------------------------
        101    92
  -26.3822000000000      -7.00984000000000      -31.6619300000000
...
--------------------------------------------------
  ...
       XY YZ ZX
...
  --------------------------------------------------
**************************************************
    4.95694000000000       2.44523000000000       6.77740000000000
    Configuration num.      1
 
==================================================
   ...
    System name
   ...
--------------------------------------------------
**************************************************
    Optimal
      Configuration num.      2
==================================================
==================================================
    The number of atom types
--------------------------------------------------
      5
==================================================
    The number of atoms
--------------------------------------------------
        96
**************************************************
    Atom types and atom numbers
--------------------------------------------------
    Pb      8
    I      24
    C      8
    N      8
    H      48
==================================================
    CTIFOR
--------------------------------------------------
  7.2153124269575984E-003
==================================================
    Primitive lattice vectors (ang.)
--------------------------------------------------
  12.6230002000000      0.000000000000000E+000  0.000000000000000E+000
  0.000000000000000E+000  12.6230002000000       0.000000000000000E+000
  0.000000000000000E+000 0.000000000000000E+000  12.6322002000000
==================================================
    Atomic positions (ang.)
--------------------------------------------------
  3.53104385888580       2.84086367297985       2.90622172474177
  9.81419124013876        2.65432768009571        3.05638374363947
   3.26003769786731        9.08189602171279        2.78238128942769
   9.68338433877730        9.01798419847282        3.33422943250601
  3.97567522985842        2.30549969401587        9.43194287333753
  10.2367187113626        2.60925731212548        9.47119538915201
  3.14970369394084        8.58643640964228        9.24921780934012
  9.89456550951183        9.28033187172892        9.29623786496524
  10.2580847101708        12.3062955711284        3.18366035907868
  3.82895321819843        12.3181255490181        2.42031967883849
...
...
...
==================================================
    Total energy (eV)
--------------------------------------------------
  -1844.06244866897
==================================================
    Forces (eV ang.^-1)
--------------------------------------------------
  2.660349497586850E-002 -4.547882666592111E-003  0.190783123263071
  0.130884508367191      0.299290099652476      1.596358887670635E-002
  3.408685056302496E-002 -4.091615555857331E-002  0.178271772476586
-8.681206662816165E-002 -2.646077052932483E-002 -0.627496783708147
-2.387963973365542E-002  0.272206550808848      -0.188554040851596
-0.349175317569579      0.372666466514608      9.810640873955712E-002
  0.508292852334109      2.851700722091148E-002 -0.297636066674050
-0.477466544993604      -0.767209034380190      0.537092981997701
  1.081052495208487E-002 -0.454162570762754      -2.885905409516716E-002
  5.233785861238309E-002 -4.907001101287316E-002  0.357709899123724
...
...
...
==================================================
    Stress (kbar)
--------------------------------------------------
    XX YY ZZ
--------------------------------------------------
  -12.6559383536223      -8.82753684858342      -13.1791695209263
--------------------------------------------------
    XY YZ ZX
--------------------------------------------------
  -1.91691819690402        2.12274173946129      0.103818583636094
**************************************************
    Configuration num.      2
==================================================
  ...
  ...
  ...
  ...
  ...
  ...
</pre>


== General format remarks ==


{{NB|important|All element-dependent quantities must follow the order of the element entries given in the header entry named <code>The atom types in the data file</code>.}}
*All element-type-dependent information is limited to 3 entries per line. For more than 3 types or multiples of 3, the entries are written over multiple lines.
*The order of the entries for the header and also the data is fixed.
*The ledger lines cannot be omitted. <code>*****</code> and <code>-----</code> lines for the header. <code>*****</code>, <code>-----</code> and <code>=====</code> lines for the data.


Some general remarks:
== Header specification==
*All element type dependent information is limited to 3 entries per line. For more than 3 types or multiples of 3 the entries are written over multiple lines.
*All element dependent quantities must follow the order of the element entries of the line <code>The atom types in the data file</code>.
*The order of the entries for the header and also the data is fixed.


Header:
*<code>1.0 Version</code>: In the very beginning of the header this entry specifies to the version of the {{FILE|ML_AB}} file. If in the future the contents of the file will be changed or extended the version number will ensure I/O compatibility. If not stated otherwise use <code>1.0 Version</code>.
*<code>The number of configurations</code>: Total number of training configurations.
*<code>The number of configurations</code>: Total number of training structures stored in this {{FILE|ML_AB}} file.
*<code>The maximum number of atom type</code>: Union of the types of all configurations.
*<code>The maximum number of atom type</code>: Total number of unique types listed in all structures (e.g. if the file contains some ab initio data for H<sub>2</sub>O, some data for MgO and some data for NaCl, then the total number of types is 5).
*<code>The atom types in the data file</code>: Listing of all atom types (two characters for each type as in VASP) appearing in all structures. Multiple lines for more than 3 element types. Maximum 3 entries per line.  
*<code>The atom types in the data file</code>: Listing of all atom types (two characters for each type as in {{VASP}}) appearing in all structures. Multiple lines for more than 3 element types. Maximum 3 entries per line.  
*<code>The maximum number of atoms per system</code>: The largest number of atoms within one structure among all training structures.
*<code>The maximum number of atoms per system</code>: The largest number of atoms within one structure among all training structures.
*<code>The maximum number of atoms per atom type</code>: The largest number of atoms per element within one structure among all elements within all training structures.
*<code>The maximum number of atoms per atom type</code>: The largest number of atoms per element within one structure among all elements within all training structures.
*<code>Reference atomic energy (eV)>: Reference atomic energies used in the calculation for each element type. Multiple lines for more than 3 element types. Maximum 3 entries per line. This entry is only important for <code>ML_ISCALE_TOTEN=1</code>.
*<code>Reference atomic energy (eV)</code>: Reference atomic energies used in the calculation for each element type. Multiple lines for more than 3 element types. Maximum 3 entries per line. This entry is only important for {{TAGO|ML_ISCALE_TOTEN|1}}.
*<code>Atomic mass</code>: Atomic mass of each element type. Multiple lines for more than 3 element types. Maximum 3 entries per line.
*<code>Atomic mass</code>: Atomic mass of each element type (in u). Multiple lines for more than 3 element types. Maximum 3 entries per line.
*<code>The numbers of basis sets per atom type</code>: Number of local reference configurations for each type.  
*<code>The numbers of basis sets per atom type</code>: Number of local reference configurations for each type. Multiple lines for more than 3 element types. Maximum 3 entries per line.
*<code>Basis set for X</code>: List of local reference configurations for each type. This line is followed by a block with two columns. The first column shows from which training structure the local reference configuration is taken. The second column shows the number of the atom in that training structure that is chosen as a local reference configuration. This whole block (together with the title line) is repeated for each element type in the force field.
*<code>Basis set for X</code>: List of local reference configurations for each type. This line is followed by a block with two columns. The first column denotes from which training structure the local reference configuration is taken. The second column is the index of the atom in the given training structure that is chosen as a local reference configuration. This whole block (together with the title line) is repeated for each element type in the force field. For {{TAGO|ML_MODE|select}} this section is ignored and a new list of local reference configurations will be written to {{FILE|ML_ABN}}. However, upon reading in the {{FILE|ML_AB}} file a dummy line (e.g. only one line with <code>1 1</code>) for each type still needs to be present (also set <code>The numbers of basis sets per atom type</code> to 1 in this case).
{{NB|warning|The maximum number of the training structures {{TAGO|ML_MCONF}} and the maximum number of the local reference configurations {{TAGO|ML_MB}} in the {{FILE|INCAR}} file have to be set larger than the entries <code>The number of configurations</code> and <code>The numbers of basis sets per atom type</code> in the {{FILE|ML_AB}} file, respectively.}}


Training structures:
== Training structure data format ==
*<code>Configuration num.      n</code>: The data is stored for each configuration of the training data. The training structures have to be numbered consecutively starting with 1.
 
*<code>System name</code>: Name of the structure. The length of the system names are limited to 40 characters (same as for the structure names in the [[POSCAR]] file).
*<code>Configuration num.      n</code>: Denotes the beginning of a structure in the training data. Training structures have to be numbered consecutively starting with 1.
*<code>The number of atom types</code>: The number of atom types in the structure. This has to be at least a subset of element types of <code>The atom types in the data file</code> in the header and can maximally have all element types of the header.
*<code>System name</code>: Name of the structure, taken from the {{FILE|POSCAR}} file which was used to start the {{TAGO|ML_MODE|train}} run. Copied from the input {{FILE|ML_AB}} file in case of {{TAGO|ML_MODE|select}}. The length of system names is limited to 40 characters.
*<code>The number of atom types</code>: The number of atom types in the structure. Because the list of types in this structure has to be a subset of all types appearing in the {{FILE|ML_AB}} this number must be smaller or equal to the number given in the header section <code>The atom types in the data file</code>.
*<code>The number of atoms</code>: Number of atoms in the structure.
*<code>The number of atoms</code>: Number of atoms in the structure.
*<code>Atom types and atom numbers</code>: Atom types and number of atoms per type in the structure. Each type is written on a separate line.
*<code>Atom types and atom numbers</code>: Atom types and the number of atoms per type in the structure. Each type is written on a separate line.
*Optional <code>CTIFOR</code>: Value of {{TAG|ML_CTIFOR}} used for the sampling of the structure. This line is optional and may not occur in your file. It is important, that either none of the training structures contain this entry or all of them contain it. It is not permitted to have mixed entries.  
*<code>CTIFOR</code> (''optional''): Value of {{TAGO|ML_CTIFOR}} used while sampling this structure. Depending on {{TAGO|ML_ICRITERIA}} the value may change between structures. This line is always present if the {{FILE|ML_ABN}} file was created by {{VASP}} with {{TAGO|ML_MODE|train}}. Then, also continuation and re-selection runs with {{TAGO|ML_MODE|train, select}} will write out current <code>CTIFOR</code> values in {{FILE|ML_ABN}} files. On the other hand, if {{FILE|ML_AB}} files are created from external training data this section may be omitted. In this case {{TAGO|ML_MODE|train, select}} runs will also not include <code>CTIFOR</code> sections. {{NB|warning|Training structures with a value for <code>CTIFOR</code> and without must not be combined. Either <code>CTIFOR</code> is provided for all structures or none of them.|:}}
*<code>Primitive lattice vectors (ang.)</code>: Bravais matrix of the structure. The units are in Angstrom.
*<code>Primitive lattice vectors (ang.)</code>: Bravais matrix of the structure, one line corresponds to one lattice vector. The unit of length units is Angstrom.
*<code>Wycoff positions (Cartesian)</code>: Ionic positions in Cartesian coordinates. The units are in Angstrom.
*<code>Atomic positions (ang.)</code>: Ionic positions in Cartesian coordinates (given in Angstrom). Note that the order of atoms needs to correspond to the atom types list in <code>Atom types and atom numbers</code>.
*<code>Total energy (eV)</code>: Total energy (in eV) of the structure.
*<code>Total energy (eV)</code>: Total energy (in eV) of the structure.
*<code>Forces (eV ang.^-1)</code>: Forces (in eV/Angstrom) for each atom in the structure.
*<code>Forces (eV ang.^-1)</code>: Forces (in eV/Angstrom) for each atom in the structure.
*<code>Stress (kbar)</code>: 6 entries for the stress tensor (in kB) of the structure.
*<code>Stress (kbar)</code>: 6 entries for the stress tensor (in kb) of the structure.
 
== Merging different ML_AB files ==
 
Multiple {{FILE|ML_AB}} files may be merged by hand, keeping the following restrictions and tips in mind:
*The training structure data can be simply concatenated, i.e., by just adding more structure sections starting with <code>Configuration num.      n</code> at the end of the file. However, the structure numbering needs to be updated in such a way that they are enumerated continuously starting from 1.
*We strongly advise to group structures with the same number of elements and atoms per element in the training data together, otherwise the code will automatically reorder the data, such that those are sticking together. If one relies on the automatic reordering it will not be possible to easily "diff" the input {{FILE|ML_AB}} file and its corresponding {{FILE|ML_ABN}} output file.
*The header must be adjusted to reflect the combined number of element types, the maximum number of atoms, etc.
*The lists of local reference configurations cannot be easily merged (renumbering would be required). Instead, it is recommended to recalculate them using {{TAGO|ML_MODE|select}}. However, to start with a valid {{FILE|ML_AB}} file first manually set <code>The numbers of basis sets per atom type</code> to 1 for each species. Also, set the block <code>Basis set for X</code> with dummy value <code>1 1</code> for each species. After running with {{TAGO|ML_MODE|select}} the output {{FILE|ML_ABN}} will contain the selected new local reference configurations for the combined training data. {{NB|tip|If calculations for {{TAGO|ML_MODE|select}} are too time consuming using the default settings it is useful to increase {{TAGO|ML_MCONF_NEW}} to values around 10-16 and set {{TAGO|ML_CDOUB|4}}. This often accelerates the calculations by a factor of 2-4.|:}}


'''Important''': The maximum size of the training structures {{TAG|ML_MCONF}} and the maximum size for the local configurations {{TAG|ML_MB}} in the {{TAG|INCAR}} file have to be set larger than the entries ''The number of configurations'' and ''The numbers of basis sets per atom type'' in the {{TAG|ML_AB}} file.
----
----
[[Category:Files]][[Category:Machine-learned force fields]][[Category:Input files]]
[[Category:Files]][[Category:Machine-learned force fields]][[Category:Input files]]

Latest revision as of 08:32, 20 October 2023

This file is used as input (with file name ML_AB) and output (ML_ABN) within the machine learning force field method. It contains the collection of ab initio data from previous calculations: Bravais matrices, atom positions, energies, forces, and stress tensors. Depending on the mode of operation it is used in the following ways:

  • ML_MODE = train, starting from scratch: A complete ML_ABN file containing all ab initio data and the list of current local reference configurations is written whenever a learning step is performed (check the line STATUS in the log file ML_LOGFILE for entries learning and critical).
  • ML_MODE = train, continuation run: Same ML_ABN output as above. In addition, upon start-up, the user-provided ML_AB file is read and an initial machine-learned force field is generated from the contained data.
  • ML_MODE = select, reselection of local reference configurations: Same ML_ABN output as for ML_MODE = train. The ML_AB file is read and the contained structures are fed sequentially to the on-the-fly training algorithm. The list of local reference configurations in the ML_AB file is ignored, however, a dummy section must still be present (see below).
Tip: The ML_AB file is not required for ML_MODE = run (prediction only) because all necessary data (e.g. descriptors of local reference configurations) are already stored in the ML_FF file.

An ML_ABN output file from ML_MODE = train, select can always be reused as input for ML_MODE = train, select by just renaming (copying) it to ML_AB.

Example

As an example, here is a shortened version of an actual ML_AB file:

 1.0 Version
**************************************************
     The number of configurations
--------------------------------------------------
        299
**************************************************
     The maximum number of atom type
--------------------------------------------------
       5
**************************************************
     The atom types in the data file
--------------------------------------------------
     Pb I  C
     N  H
**************************************************
     The maximum number of atoms per system
--------------------------------------------------
             96
**************************************************
     The maximum number of atoms per atom type
--------------------------------------------------
             48
**************************************************
     Reference atomic energy (eV)
--------------------------------------------------
  -72.5297190000000       -35.4081430000000       -2.39269120000000
  -4.60003440000000       -1.12020270000000
**************************************************
     Atomic mass
--------------------------------------------------
   20.0000000000000        20.0000000000000        12.0110000000000
   14.0010000000000        8.00000000000000
**************************************************
     The numbers of basis sets per atom type
--------------------------------------------------
       130  1202   128
       125   790
**************************************************
     Basis set for Pb
--------------------------------------------------
          1      1
        100      8
          1      3
        100      4
          1      5
          1      6
 ...
 ...
 ...
**************************************************
     Basis set for I
--------------------------------------------------
          1      9
          1     10
        100     32
        100     31
          1     13
        100     29
          1     15
          1     16
 ...
 ...
 ...
**************************************************
     Basis set for C
--------------------------------------------------
        100     39
        101     40
        104     40
        101     39
        101     38
        108     40
        101     37
 ...
 ...
 ...
**************************************************
     Basis set for N
--------------------------------------------------
          1     41
        100     47
          1     43
          1     44
        100     45
          1     46
 ...
 ...
 ...
**************************************************
     Basis set for H
--------------------------------------------------
        101     96
        108     96
        101     95
        101     94
        108     95
        101     93
        101     92
 ...
 ...
 ...
**************************************************
     Configuration num.      1
==================================================
     System name
--------------------------------------------------
     Optimal
==================================================
     The number of atom types
--------------------------------------------------
       5
==================================================
     The number of atoms
--------------------------------------------------
         96
**************************************************
     Atom types and atom numbers
--------------------------------------------------
     Pb      8
     I      24
     C       8
     N       8
     H      48
==================================================
     CTIFOR
--------------------------------------------------
   7.2153124269575984E-003
==================================================
     Primitive lattice vectors (ang.)
--------------------------------------------------
   12.6230002000000       0.000000000000000E+000  0.000000000000000E+000
  0.000000000000000E+000   12.6230002000000       0.000000000000000E+000
  0.000000000000000E+000  0.000000000000000E+000   12.6322002000000
==================================================
     Atomic positions (ang.)
--------------------------------------------------
   3.53104385888580        2.84086367297985        2.90622172474177
   9.81419124013876        2.65432768009571        3.05638374363947
   3.26003769786731        9.08189602171279        2.78238128942769
   9.68338433877730        9.01798419847282        3.33422943250601
   3.97567522985842        2.30549969401587        9.43194287333753
   10.2367187113626        2.60925731212548        9.47119538915201
   3.14970369394084        8.58643640964228        9.24921780934012
   9.89456550951183        9.28033187172892        9.29623786496524
   10.2580847101708        12.3062955711284        3.18366035907868
   3.82895321819843        12.3181255490181        2.42031967883849
 ...
 ...
 ...
==================================================
     Total energy (eV)
--------------------------------------------------
  -1844.06244866897
==================================================
     Forces (eV ang.^-1)
--------------------------------------------------
  2.660349497586850E-002 -4.547882666592111E-003  0.190783123263071
  0.130884508367191       0.299290099652476       1.596358887670635E-002
  3.408685056302496E-002 -4.091615555857331E-002  0.178271772476586
 -8.681206662816165E-002 -2.646077052932483E-002 -0.627496783708147
 -2.387963973365542E-002  0.272206550808848      -0.188554040851596
 -0.349175317569579       0.372666466514608       9.810640873955712E-002
  0.508292852334109       2.851700722091148E-002 -0.297636066674050
 -0.477466544993604      -0.767209034380190       0.537092981997701
  1.081052495208487E-002 -0.454162570762754      -2.885905409516716E-002
  5.233785861238309E-002 -4.907001101287316E-002  0.357709899123724
 ...
 ...
 ...
==================================================
     Stress (kbar)
--------------------------------------------------
     XX YY ZZ
--------------------------------------------------
  -12.6559383536223       -8.82753684858342       -13.1791695209263
--------------------------------------------------
     XY YZ ZX
--------------------------------------------------
  -1.91691819690402        2.12274173946129       0.103818583636094
**************************************************
     Configuration num.      2
==================================================
 ...
 ...
 ...

General format remarks

Important: All element-dependent quantities must follow the order of the element entries given in the header entry named The atom types in the data file.
  • All element-type-dependent information is limited to 3 entries per line. For more than 3 types or multiples of 3, the entries are written over multiple lines.
  • The order of the entries for the header and also the data is fixed.
  • The ledger lines cannot be omitted. ***** and ----- lines for the header. *****, ----- and ===== lines for the data.

Header specification

  • 1.0 Version: In the very beginning of the header this entry specifies to the version of the ML_AB file. If in the future the contents of the file will be changed or extended the version number will ensure I/O compatibility. If not stated otherwise use 1.0 Version.
  • The number of configurations: Total number of training structures stored in this ML_AB file.
  • The maximum number of atom type: Total number of unique types listed in all structures (e.g. if the file contains some ab initio data for H2O, some data for MgO and some data for NaCl, then the total number of types is 5).
  • The atom types in the data file: Listing of all atom types (two characters for each type as in VASP) appearing in all structures. Multiple lines for more than 3 element types. Maximum 3 entries per line.
  • The maximum number of atoms per system: The largest number of atoms within one structure among all training structures.
  • The maximum number of atoms per atom type: The largest number of atoms per element within one structure among all elements within all training structures.
  • Reference atomic energy (eV): Reference atomic energies used in the calculation for each element type. Multiple lines for more than 3 element types. Maximum 3 entries per line. This entry is only important for ML_ISCALE_TOTEN = 1.
  • Atomic mass: Atomic mass of each element type (in u). Multiple lines for more than 3 element types. Maximum 3 entries per line.
  • The numbers of basis sets per atom type: Number of local reference configurations for each type. Multiple lines for more than 3 element types. Maximum 3 entries per line.
  • Basis set for X: List of local reference configurations for each type. This line is followed by a block with two columns. The first column denotes from which training structure the local reference configuration is taken. The second column is the index of the atom in the given training structure that is chosen as a local reference configuration. This whole block (together with the title line) is repeated for each element type in the force field. For ML_MODE = select this section is ignored and a new list of local reference configurations will be written to ML_ABN. However, upon reading in the ML_AB file a dummy line (e.g. only one line with 1 1) for each type still needs to be present (also set The numbers of basis sets per atom type to 1 in this case).
Warning: The maximum number of the training structures ML_MCONF and the maximum number of the local reference configurations ML_MB in the INCAR file have to be set larger than the entries The number of configurations and The numbers of basis sets per atom type in the ML_AB file, respectively.

Training structure data format

  • Configuration num. n: Denotes the beginning of a structure in the training data. Training structures have to be numbered consecutively starting with 1.
  • System name: Name of the structure, taken from the POSCAR file which was used to start the ML_MODE = train run. Copied from the input ML_AB file in case of ML_MODE = select. The length of system names is limited to 40 characters.
  • The number of atom types: The number of atom types in the structure. Because the list of types in this structure has to be a subset of all types appearing in the ML_AB this number must be smaller or equal to the number given in the header section The atom types in the data file.
  • The number of atoms: Number of atoms in the structure.
  • Atom types and atom numbers: Atom types and the number of atoms per type in the structure. Each type is written on a separate line.
  • CTIFOR (optional): Value of ML_CTIFOR used while sampling this structure. Depending on ML_ICRITERIA the value may change between structures. This line is always present if the ML_ABN file was created by VASP with ML_MODE = train. Then, also continuation and re-selection runs with ML_MODE = train, select will write out current CTIFOR values in ML_ABN files. On the other hand, if ML_AB files are created from external training data this section may be omitted. In this case ML_MODE = train, select runs will also not include CTIFOR sections.
Warning: Training structures with a value for CTIFOR and without must not be combined. Either CTIFOR is provided for all structures or none of them.
  • Primitive lattice vectors (ang.): Bravais matrix of the structure, one line corresponds to one lattice vector. The unit of length units is Angstrom.
  • Atomic positions (ang.): Ionic positions in Cartesian coordinates (given in Angstrom). Note that the order of atoms needs to correspond to the atom types list in Atom types and atom numbers.
  • Total energy (eV): Total energy (in eV) of the structure.
  • Forces (eV ang.^-1): Forces (in eV/Angstrom) for each atom in the structure.
  • Stress (kbar): 6 entries for the stress tensor (in kb) of the structure.

Merging different ML_AB files

Multiple ML_AB files may be merged by hand, keeping the following restrictions and tips in mind:

  • The training structure data can be simply concatenated, i.e., by just adding more structure sections starting with Configuration num. n at the end of the file. However, the structure numbering needs to be updated in such a way that they are enumerated continuously starting from 1.
  • We strongly advise to group structures with the same number of elements and atoms per element in the training data together, otherwise the code will automatically reorder the data, such that those are sticking together. If one relies on the automatic reordering it will not be possible to easily "diff" the input ML_AB file and its corresponding ML_ABN output file.
  • The header must be adjusted to reflect the combined number of element types, the maximum number of atoms, etc.
  • The lists of local reference configurations cannot be easily merged (renumbering would be required). Instead, it is recommended to recalculate them using ML_MODE = select. However, to start with a valid ML_AB file first manually set The numbers of basis sets per atom type to 1 for each species. Also, set the block Basis set for X with dummy value 1 1 for each species. After running with ML_MODE = select the output ML_ABN will contain the selected new local reference configurations for the combined training data.
Tip: If calculations for ML_MODE = select are too time consuming using the default settings it is useful to increase ML_MCONF_NEW to values around 10-16 and set ML_CDOUB = 4. This often accelerates the calculations by a factor of 2-4.