Quick start - Revision history

Miguel Caro at 07:36, 24 July 2021

2021-07-24T07:36:47Z

Miguel Caro at 06:59, 15 May 2021

2021-05-15T06:59:53Z

Miguel Caro at 06:47, 15 May 2021

2021-05-15T06:47:29Z

Miguel Caro: /* Fitting a GAP potential */

2020-08-25T14:45:13Z

Fitting a GAP potential

Miguel Caro: /* Building a database */

2020-08-25T14:34:02Z

Building a database

Miguel Caro: /* Optional */

2020-08-25T14:31:19Z

Optional

Miguel Caro: /* Installing QUIP/GAP */

2020-07-02T07:18:48Z

Installing QUIP/GAP

Miguel Caro at 20:50, 1 July 2020

2020-07-01T20:50:09Z

Miguel Caro: /* Installing TurboGAP (optional step) */

2020-07-01T20:46:00Z

Installing TurboGAP (optional step)

Miguel Caro: /* Building a database */

2020-07-01T20:44:05Z

Building a database

← Older revision		Revision as of 07:36, 24 July 2021
Line 1:		Line 1:
−	This is a quick start guide to fitting GAP potentials using an atomic database and some combination of descriptors. You can do this with QUIP/GAP alone, or add '''TurboGAP''' support for faster and more accurate many-body descriptors of the SOAP type. You can run some of these potentials with TurboGAP, provided that you only use <code>distance_2b</code>, <code>angle_3b</code> or <code>soap_turbo</code> descriptors. In addition, you can also use your GAP to run molecular dynamics simulations on LAMMPS with the QUIP-LAMMPS interface, although some advanced functionality like van der Waals corrections is not currently supported on LAMMPS.	+	This is a quick start guide to fitting and using GAP potentials using an atomic database and some combination of descriptors. You can do this with QUIP/GAP alone, or add '''TurboGAP''' support for faster and more accurate many-body descriptors of the SOAP type. You can run some of these potentials with TurboGAP, provided that you only use <code>distance_2b</code>, <code>angle_3b</code> or <code>soap_turbo</code> descriptors. In addition, you can also use your GAP to run molecular dynamics simulations on LAMMPS with the QUIP-LAMMPS interface, although some advanced functionality like van der Waals corrections is not currently supported on LAMMPS.

	== Prerequisites ==		== Prerequisites ==

@@ Line 1: / Line 1: @@
-This is a quick start guide to fitting GAP potentials using an atomic database and some combination of descriptors. You can do this with QUIP/GAP alone, or add '''TurboGAP''' support for faster and more accurate many-body descriptors of the SOAP type. You can run some of these potentials with TurboGAP, provided that you only use <code>distance_2b</code>, <code>angle_3b</code> or <code>soap_turbo</code> descriptors. In addition, you can also use your GAP to run molecular dynamics simulations on LAMMPS with the QUIP-LAMMPS interface, although some advanced functionality like van er Waals corrections is not currently supported on LAMMPS.
+This is a quick start guide to fitting GAP potentials using an atomic database and some combination of descriptors. You can do this with QUIP/GAP alone, or add '''TurboGAP''' support for faster and more accurate many-body descriptors of the SOAP type. You can run some of these potentials with TurboGAP, provided that you only use <code>distance_2b</code>, <code>angle_3b</code> or <code>soap_turbo</code> descriptors. In addition, you can also use your GAP to run molecular dynamics simulations on LAMMPS with the QUIP-LAMMPS interface, although some advanced functionality like van der Waals corrections is not currently supported on LAMMPS.
 == Prerequisites ==
@@ Line 15: / Line 15: @@
 * The Atomic Simulation Environment (ASE) is not required but it is always a useful addition to an atomistic toolset, and particularly useful to generate the XYZ database files used by QUIP/GAP.
-* A TurboGAP installation if you want to use Miguel Caro's SOAP-type many-body descriptors, which are faster and more accurate than the default SOAP descriptors. In addition, TurboGAP supports SOAP compression (making it even faster). TurboGAP cannot (currently) be used on its own to training a GAP: it is used as a library in combination with QUIP/GAP. TurboGAP is free for non-commercial research. TurboGAP can also be used to run parallel MD calculations, but the number of available implementations of integrators, thermostats, barostats, etc., is way below what LAMMPS can offer (see next point), as is the efficiency and scalability of the parallel implementation. That said, for specific problems with the right balance between computation and communication, TurboGAP can run GAP-based MD significantly faster than LAMMPS (about an order of magnitude faster).
+* A '''TurboGAP''' installation if you want to use <code>soap_turbo</code> many-body descriptors, which are faster and more accurate than the default SOAP descriptors. In addition, '''TurboGAP''' supports SOAP compression (making it even faster). '''TurboGAP''' cannot (currently) be used on its own to training a GAP: it is used as a library in combination with QUIP/GAP. '''TurboGAP''' is free for non-commercial research. '''TurboGAP''' can also be used to run parallel MD calculations, but the number of available implementations of integrators, thermostats, barostats, etc., is way below what LAMMPS can offer (see next point), as is the efficiency and scalability of the parallel implementation. That said, for specific problems with the right balance between computation and communication, '''TurboGAP''' can run GAP-based MD significantly faster than LAMMPS (about an order of magnitude faster).
-* A LAMMPS installation, if you want to use your GAP potentials to run large-scaling molecular dynamics simulations. A custom installation of LAMMPS with QUIP support is required (more details below).
+* A LAMMPS installation, if you want to use your GAP potentials to run large-scaling molecular dynamics simulations. A custom installation of LAMMPS with QUIP support is required (more details below). At the moment some advanced functionality like van der Waals corrections is not available through the LAMMPS interface.
 == Building a database ==
@@ Line 105: / Line 105: @@
 </syntaxhighlight>
-We have given a label ("<code>config_type</code>") to structures generated in different ways because this will allow us to provide per-configuration regularization parameters, a nice feature and very useful of QUIP/GAP. Importantly, you should put all of the individual XYZ files into a single "database" XYZ file, which is easily achieved by concatenating all of them. For example, given the files generated above, you could do (adjusting the ranges as needed):
+We have given a label ("<code>config_type</code>") to structures generated in different ways because this will allow us to provide per-configuration regularization parameters, a nice feature, and very useful, of QUIP/GAP. Importantly, you should put all of the individual XYZ files into a single "database" XYZ file, which is easily achieved by concatenating all of them. For example, given the files generated above, you could do (adjusting the ranges as needed):
 <syntaxhighlight lang="bash" line="line">
@@ Line 127: / Line 127: @@
 # Clone the turbogap development repo
-git clone https://github.com/mcaroba/turbogap.git turbogap_dev
+git clone --recursive https://github.com/mcaroba/turbogap.git turbogap_dev
 # cd and make the code (you may want to edit the Makefile, load compiler modules, etc., depending on the specifics of your system)
@@ Line 134: / Line 134: @@
 </syntaxhighlight>
-This should have built the '''TurboGAP''' binaries and libraries.
+This should have built the '''TurboGAP''' binaries and libraries. The git <code>--recursive</code> flag will take care of cloning also the GAP_turbo source code.
 == Installing QUIP/GAP ==
-To install '''QUIP''' and '''GAP''' (they are two separate packages with two separate licenses) you first need to get '''QUIP''' from [http://www.libatoms.org/Home/Software libAtoms] or clone the git repo (it is probably best/safest to get the development version to make sure all functionality is available):
+To install '''QUIP''' and '''GAP''' (they are two separate packages with two separate licenses) you need to get '''QUIP''' from [http://www.libatoms.org/Home/Software libAtoms] or clone the git repo (it is probably best/safest to get the development version to make sure all functionality is available):
 <syntaxhighlight lang="shell" line="line">
@@ Line 146: / Line 146: @@
 # Clone the QUIP development repo
-git clone https://github.com/libAtoms/QUIP.git quip_dev
+git clone --recursive https://github.com/libAtoms/QUIP.git quip_dev
-# cd into the src directory
+# cd into the quip directory
-cd quip_dev/src
+cd quip_dev
 </syntaxhighlight>
-In the <code>src</code> directory, you need to put a copy of '''GAP'''. There are two ways of getting GAP for non-commercial research. One (applicable to most people) is through [http://www.libatoms.org/Home/Software libAtoms], where you need to agree to the license terms before being able to download the code. The other one is through the (private) Github repo. At the time of writing this guide, '''TurboGAP''' support through the <code>soap_turbo</code> descriptor is only available via the Github repo.
+The git <code>--recursive</code> flag will take care of cloning also the GAP source code.
-) If you download '''GAP''' the usual way, just put a copy of the package inside the <code>quip_dev/src</code> directory.
+Now you are ready to build QUIP/GAP. First, you need to select your architecture. For a list of possible architectures, do <code>ls arch</code>. If you want to use QUIP/GAP together with '''TurboGAP''', make sure that your chosen compiler is compatible (e.g., you use <code>gfortran</code> to build both codes). The architecture is selected by exporting the <code>QUIP_ARCH</code> environment variable. After that, you <code>make config</code>. You'll be asked whether or not to install a bunch of functionality. Don't get crazy with your ENTER key, you need to select "y" (yes) for GAP (the default is "n") and, if you're planning to use '''TurboGAP''' functionality, you need to provide QUIP with the '''TurboGAP''' root directory, <code>/myapps/turbogap/turbogap_dev</code> in the example above. Optionally, if you want to build '''LAMMPS''' with '''QUIP''' functionality, you need to make the '''QUIP''' library. Example:
 <syntaxhighlight lang="shell" line="line">

← Older revision		Revision as of 06:47, 15 May 2021
Line 1:		Line 1:
−	This is a quick start guide to fitting GAP potentials using an atomic database and some combination of descriptors. You can do this with QUIP/GAP alone, or add TurboGAP support for faster and more accurate many-body descriptors of the SOAP type. In addition, you can also use your GAP to run molecular dynamics simulations on LAMMPS.	+	This is a quick start guide to fitting GAP potentials using an atomic database and some combination of descriptors. You can do this with QUIP/GAP alone, or add '''TurboGAP''' support for faster and more accurate many-body descriptors of the SOAP type. You can run some of these potentials with TurboGAP, provided that you only use <code>distance_2b</code>, <code>angle_3b</code> or <code>soap_turbo</code> descriptors. In addition, you can also use your GAP to run molecular dynamics simulations on LAMMPS with the QUIP-LAMMPS interface, although some advanced functionality like van er Waals corrections is not currently supported on LAMMPS.

	== Prerequisites ==		== Prerequisites ==

@@ Line 214: / Line 214: @@
 fi
-gap_fit atoms_filename=../../train_all_mbd.xyz \
+gap_fit atoms_filename=database.xyz \
          gap={ distance_Nb order=2 compact_clusters=T cutoff=5.0 n_sparse=20 covariance_type=ard_se \
                    delta=0.5 theta_uniform=1.0 sparse_method=uniform : \
@@ Line 225: / Line 225: @@
          sparse_jitter=1.0e-8 do_copy_at_file=F sparse_separate_file=T gp_file=crappy_P.xml
 </syntaxhighlight>
 == Testing your potential with QUIP ==

@@ Line 21: / Line 21: @@
 == Building a database ==
-The most essential requirement to train a ML potential, be it GAP or something else, is training data. For QUIP, a database of atomic configurations is an extended XYZ file with atomic structures (i.e., atomic coordinates), accompanied by energies, forces and/or virials. A single XYZ file, e.g., <code>database.xyz</code>, contains a concatenation of individual atomic structures. What kinds of configurations are contained here and how well they span the regions of configuration that are relevant for our potential will be absolutely critical in determining the accuracy of our trained GAP.
+The most essential requirement to train a ML potential, be it GAP or something else, is training data. For QUIP, a database of atomic configurations is an extended XYZ file with atomic structures (i.e., atomic coordinates), accompanied by energies, forces and/or virials. A single XYZ file, e.g., <code>database.xyz</code>, contains a concatenation of individual atomic structures. What kinds of configurations are contained here and how well they span the regions of configuration space that are relevant to our potential will be absolutely critical in determining the accuracy of our trained GAP.
-Good databases contain a combination of crystalline and distorted structures, dimer, trimers, surfaces, liquids, etc. Our "training set" may contain ''a lot'' of structures, of the order of thousands of simulation boxes and hundreds of thousands of unique atomic environments. Not all of these will be used for the kernel-ridge regression during production, only the ''sparse set'' will be used for that; however, the full training set will be used to find the optimal regression coefficients.
+Good databases for general-purpose interatomic potentials contain a combination of crystalline and distorted structures, dimer, trimers, surfaces, liquids, etc. Specific-purpose interatomic potentials can, on the other hand, focus on particular structures. Our "training set" may contain ''a lot'' of structures, of the order of thousands of simulation boxes and hundreds of thousands of unique atomic environments. Not all of these will be used for the kernel-ridge regression during production, only the ''sparse set'' will be used for that; however, the full training set will be used to find the optimal regression coefficients.
-As an example, let us use GPAW, in combination with ASE, to compute energies and forces for a bunch of phosphorus structures. Note that this is just to get to grips with the workflow; you can generate the training data with another DFT code (although ASE is always handy for parsing the output of the calculation). E.g., if you use VASP, you can import the <code>OUTCAR</code> with ASE (<code>atoms = read("OUTCAR")</code>) and the energy, forces, etc., will be imported to the ASE <code>Atoms()</code> object.
+As an example, let us use GPAW, in combination with ASE, to compute energies and forces for a bunch of elemental phosphorus structures. Note that this is just to get to grips with the workflow; you can generate the training data with another DFT code (although ASE is always handy for parsing the output of the calculation). E.g., if you use VASP, you can import the <code>OUTCAR</code> with ASE (<code>atoms = read("OUTCAR")</code>) and the energy, forces, etc., will be imported to the ASE <code>Atoms()</code> object.
 But let us get back to generating a (rather crappy) database of P structures with GPAW. The code below will compute the energy for an isolated atom, assign it label "isolated_atom" and write it to file; then, for 20 configurations corresponding to the P<sub>2</sub> dissociation curve; then, 50 very stupidly constructed bulk configurations in periodic boundary conditions. Note that we are using an LCAO basis set since we want to do this fast, and we are not leaving a lot of vacuum around the non-periodic structure. If you hope to publish your database, you should fix this and other problems with this example.

@@ Line 165: / Line 165: @@
 </syntaxhighlight>
-After you have a copy of '''GAP''' ins <code>src</code>, cd one directory up and get ready to build QUIP/GAP. First, you need to select your architecture. For a list of possible architectures, do <code>ls arch</code>. If you want to use QUIP/GAP together with '''TurboGAP''', make sure that your chosen compiler is compatible (e.g., you use <code>gfortran</code> to build both codes). The architecture is selected by exporting the <code>QUIP_ARCH</code> environment variable. After that, you <code>make config</code>. You'll be asked whether or not to install a bunch of functionality. Don't get crazy with your ENTER key, you need to select "y" (yes) for GAP (the default is "n") and, if you're planning to use '''TurboGAP''' functionality, you need to provide QUIP with the '''TurboGAP''' root directory, <code>/myapps/turbogap/turbogap_dev</code> in the example above. Example:
+After you have a copy of '''GAP''' ins <code>src</code>, cd one directory up and get ready to build QUIP/GAP. First, you need to select your architecture. For a list of possible architectures, do <code>ls arch</code>. If you want to use QUIP/GAP together with '''TurboGAP''', make sure that your chosen compiler is compatible (e.g., you use <code>gfortran</code> to build both codes). The architecture is selected by exporting the <code>QUIP_ARCH</code> environment variable. After that, you <code>make config</code>. You'll be asked whether or not to install a bunch of functionality. Don't get crazy with your ENTER key, you need to select "y" (yes) for GAP (the default is "n") and, if you're planning to use '''TurboGAP''' functionality, you need to provide QUIP with the '''TurboGAP''' root directory, <code>/myapps/turbogap/turbogap_dev</code> in the example above. Optionally, if you want to build '''LAMMPS''' with '''QUIP''' functionality, you need to make the '''QUIP''' library. Example:
 <syntaxhighlight lang="shell" line="line">
@@ Line 179: / Line 179: @@
 # Build the code
 make
 </syntaxhighlight>

@@ Line 31: / Line 31: @@
 But let us get back to generating a (rather crappy) database of P structures with GPAW. The code below will compute the energy for an isolated atom, assign it label "isolated_atom" and write it to file; then, for 20 configurations corresponding to the P<sub>2</sub> dissociation curve; then, 50 very stupidly constructed bulk configurations in periodic boundary conditions. Note that we are using an LCAO basis set since we want to do this fast, and we are not leaving a lot of vacuum around the non-periodic structure. If you hope to publish your database, you should fix this and other problems with this example.
-<syntaxhighlight lang="python" line="line" style="border:1px solid blue;margin-left:2em;font-size: 80%">
+<syntaxhighlight lang="python" line="line">
 import numpy as np
 from ase import Atoms
@@ Line 109: / Line 109: @@
 We have given a label ("<code>config_type</code>") to structures generated in different ways because this will allow us to provide per-configuration regularization parameters, a nice feature and very useful of QUIP/GAP. Importantly, you should put all of the individual XYZ files into a single "database" XYZ file, which is easily achieved by concatenating all of them. For example, given the files generated above, you could do (adjusting the ranges as needed):
-<syntaxhighlight lang="bash" line="line" style="border:1px solid blue;margin-left:2em;font-size: 80%">
+<syntaxhighlight lang="bash" line="line">
 cat database/isolated_atom.xyz > database.xyz
 for i in $(seq 0 1 19); do cat database/dimer_${i}.xyz >> database.xyz; done
@@ Line 142: / Line 142: @@
 To install '''QUIP''' and '''GAP''' (they are two separate packages with two separate licenses) you first need to get '''QUIP''' from [http://www.libatoms.org/Home/Software libAtoms] or clone the git repo (it is probably best/safest to get the development version to make sure all functionality is available):
-<syntaxhighlight lang="shell" line="line" style="border:1px solid blue">
+<syntaxhighlight lang="shell" line="line">
 # Create and cd into a directory
 mkdir /myapps/quip
@@ Line 160: / Line 160: @@
 ) If you have access to the '''GAP''' repo, clone the <code>turbosoap</code> branch ''while inside the <code>src</code> directory'':
-<syntaxhighlight lang="shell" line="line" style="border:1px solid blue">
+<syntaxhighlight lang="shell" line="line">
 # Clone the QUIP development repo
 git clone -b turbosoap https://github.com/libAtoms/GAP.git
@@ Line 167: / Line 167: @@
 After you have a copy of '''GAP''' ins <code>src</code>, cd one directory up and get ready to build QUIP/GAP. First, you need to select your architecture. For a list of possible architectures, do <code>ls arch</code>. If you want to use QUIP/GAP together with '''TurboGAP''', make sure that your chosen compiler is compatible (e.g., you use <code>gfortran</code> to build both codes). The architecture is selected by exporting the <code>QUIP_ARCH</code> environment variable. After that, you <code>make config</code>. You'll be asked whether or not to install a bunch of functionality. Don't get crazy with your ENTER key, you need to select "y" (yes) for GAP (the default is "n") and, if you're planning to use '''TurboGAP''' functionality, you need to provide QUIP with the '''TurboGAP''' root directory, <code>/myapps/turbogap/turbogap_dev</code> in the example above. Example:
-<syntaxhighlight lang="shell" line="line" style="border:1px solid blue">
+<syntaxhighlight lang="shell" line="line">
 # cd up from the src directory
 cd ..
@@ Line 198: / Line 198: @@
 This is an example <code>gap_fit</code> command using a <code>soap</code> many-body descriptor:
-<syntaxhighlight lang="shell" line="line" style="border:1px solid blue" title="teach_gap.sh">
+<syntaxhighlight lang="shell" line="line">
 # force should be "force" or "DUMMY"