Quick reference (migration guide)
*********************************

The quick reference tables compare how to set up calculations in AMS
and *standalone* Quantum ESPRESSO. This can be useful if you are
already familiar with Quantum ESPRESSO but want to use the AMS
interface.

For details, see AMS driver's tasks and properties or Quantum ESPRESSO
Input, or the complete Examples.


Elements, coordinates, lattice, isotopes, charge, labels
========================================================

One of the H atoms has a special label "H1". Labels can be used to set
atom-specific starting magnetizations or Hubbard U values (not shown
here).

+-----------------+-----------------+
| AMS             | Standalone pw.x |
|=================|=================|
| # AMS Driver    | # pw.x &SYSTEM  |
| System   Atoms  | ibrav = 0   nat |
| H 0. 0. 0.      | = 2   ntyp = 2  |
| QE.Label=H1     | tot_charge =    |
| H 1. 0. 0.      | 0.0 /           |
| mass=2.01   End | CELL_PARAMETERS |
| Lattice     6.  | angstrom   6.   |
| 0. 0.     0. 5. | 0. 0.   0. 5.   |
| 0.     0. 0. 4. | 0.   0. 0. 4.   |
| End   Charge 0  | ATOMIC_SPECIES  |
| End             | H1 1.008 'H_ON  |
|                 | CV_PBE-1.2.upf' |
|                 | H 2.01 'H_ONCV  |
|                 | _PBE-1.2.upf'   |
|                 | ATOMIC_POSITIO  |
|                 | NS angstrom     |
|                 | H1 0. 0. 0.   H |
|                 | 1. 0. 0.        |
+-----------------+-----------------+


Pseudopotentials
================

AMS comes with a library of Quantum ESPRESSO pseudopotentials. The
correct files will automatically be picked up when you specify the
"Family" and "Functional".

To see the available families or to specify your own pseudopotential
files in AMS, see Pseudopotentials.

+-----------------+-----------------+
| AMS             | Standalone pw.x |
|=================|=================|
| Engine          | # pw.x &CONTROL |
| QuantumEspresso | pseudo_dir='/s  |
| Pseudopotentia  | ome/path' /     |
| ls     Family   | ATOMIC_SPECIES  |
| SG15            | H1 1.008 'H_ON  |
| Functional PBE  | CV_PBE-1.2.upf' |
| End EndEngine   | H 2.01 'H_ONCV  |
|                 | _PBE-1.2.upf'   |
+-----------------+-----------------+


k-space sampling
================

Gamma-point (Γ-point) sampling:

+-----------------+-----------------+
| AMS             | Standalone pw.x |
|=================|=================|
| Engine          | # pw.x K_POINTS |
| QuantumEspresso | gamma           |
| K_Points gamma  |                 |
| End EndEngine   |                 |
+-----------------+-----------------+

Monkhorst-Pack grid (4 x 4 x 4, shifted):

+-----------------+-----------------+
| AMS             | Standalone pw.x |
|=================|=================|
| Engine          | # pw.x K_POINTS |
| QuantumEspresso | automatic   4 4 |
| K_Points        | 4 1 1 1         |
| automatic       |                 |
| 4 4 4 1 1 1     |                 |
| End EndEngine   |                 |
+-----------------+-----------------+


Energy cutoff
=============

+-----------------+-----------------+
| AMS             | Standalone pw.x |
|=================|=================|
| Engine          | # pw.x &SYSTEM  |
| QuantumEspresso | ecutwfc = 40 /  |
| System          |                 |
| ecutwfc 40      |                 |
| End EndEngine   |                 |
+-----------------+-----------------+


Forces, stress tensor
=====================

+-----------------+-----------------+
| AMS             | Standalone pw.x |
|=================|=================|
| # AMS Driver    | # pw.x &CONTROL |
| Properties      | tprnfor =       |
| Gradients Yes   | .true.          |
| StressTensor    | tstress =       |
| Yes End         | .true. /        |
+-----------------+-----------------+


Singlepoint
===========

+-----------------+-----------------+
| AMS             | Standalone pw.x |
|=================|=================|
| # AMS Driver    | &CONTROL        |
| Task            | calculation =   |
| SinglePoint     | 'scf' /         |
+-----------------+-----------------+


Geometry optimization
=====================

**Note**: If you use AMS, it will *not* set "calculation='relax'" in
the pw.x input. Instead it will use the internal AMS geometry
optimizer and set "calculation='scf'".

+-----------------+-----------------+
| AMS             | Standalone pw.x |
|=================|=================|
| # AMS Driver    | # pw.x &CONTROL |
| Task GeometryO  | calculation =   |
| ptimization  G  | 'relax'   nstep |
| eometryOptimiz  | = 100 /  &IONS  |
| ation   Method  | ion_dynamics =  |
| FIRE            | 'fire' /        |
| MaxIterations   |                 |
| 100 End         |                 |
+-----------------+-----------------+


Constraints
===========

Keep the position of the first atom fixed and the x-coordinate of the
second atom fixed.

+-----------------+-----------------+
| AMS             | Standalone pw.x |
|=================|=================|
| # AMS Driver    | # pw.x ATOMIC_  |
| Constraints     | POSITIONS       |
| Atom 1          | angstrom   H 0. |
| Coordinate 2 x  | 0. 0. 0 0 0   H |
| End  System     | 1. 0. 0. 0 1 1  |
| Atoms     H 0.  |                 |
| 0. 0.     H 1.  |                 |
| 0. 0.   End End |                 |
+-----------------+-----------------+

For more advanced constraints, see the AMS Driver documentation.


Execution
=========

+-----------------+-----------------+
| AMS             | Standalone pw.x |
|=================|=================|
| #!/bin/sh       | #!/bin/sh  #    |
| export SCM_DIS  | here show how   |
| ABLE_MPI=1  rm  | to find # the   |
| -rf ams.results | same pseudopot  |
| $AMSBIN/ams     | entials # as on |
| <<EOF Task      | the left, # but |
| SinglePoint     | you can set     |
| System   Atoms  | PPDIR manually  |
| H 0. 0. 0.      | PPDIR=`amspack  |
| H 1. 0. 0.      | ages loc qe` P  |
| End   Lattice   | PDIR=$PPDIR/up  |
| 6. 0. 0.     0. | f_files/GGA/PBE |
| 5. 0.     0. 0. | PPDIR=$PPDIR/S  |
| 4.   End End    | R/SG15-1.2/UPFs |
| Engine          | $AMSBIN/startqe |
| QuantumEspresso | pw.x <<EOF      |
| Pseudopotentia  | &CONTROL   pse  |
| ls     Family   | udo_dir='$PPDI  |
| SG15            | R' /  &SYSTEM   |
| Functional PBE  | ibrav = 0   nat |
| End   System    | = 2   ntyp = 1  |
| ecutwfc 40.0    | tot_charge =    |
| ecutrho 160.0   | 0.0   ecutwfc = |
| End   K_Points  | 40   ecutrho =  |
| gamma   End     | 160 /           |
| EndEngine  EOF  | &ELECTRONS /    |
| echo Getting    | ATOMIC_SPECIES  |
| results... #    | H 1.008 'H_ONC  |
| extract energy  | V_PBE-1.2.upf'  |
| at end RKF=qua  | ATOMIC_POSITIO  |
| ntumespresso.r  | NS angstrom   H |
| kf $AMSBIN/akf  | 0. 0. 0.   H 1. |
| \  ams.results  | 0. 0.           |
| /$RKF \  -pv A  | CELL_PARAMETERS |
| MSResults%Ener  | angstrom   6.   |
| gy              | 0. 0.   0. 5.   |
|                 | 0.   0. 0. 4.   |
|                 | K_POINTS gamma  |
|                 | EOF             |
+-----------------+-----------------+
