Aluminum Example
================

Here is the example of Aluminum.
Aluminum has FCC lattice with a single atom per primitive unit cell.
The following ``structure.yml`` file is used in this example:

.. code-block:: yaml
  :caption: structure.yml

  # CrystalFTG
  vec:
    [[ 0.00000000,  1.99208958,  1.99208958],
     [ 1.99208958,  0.00000000,  1.99208958],
     [ 1.99208958,  1.99208958,  0.00000000]]
  atoms:
    - Al: 
        [[ 0.00000000,  0.00000000,  0.00000000]]
  orbitals: p
  supa:
    [[ 1,  0,  0],
     [ 0,  1,  0],
     [ 0,  0,  1]]

This example can be found in the ``examples/compute_id/al/hsbid/order2`` directory of the  ``principia-materia-examples`` repository.

Compute phonon with HS-BID
--------------------------

1. First, we execute the symmetry analysis and create the jobs that need to be calculated with a first principle method.
   These jobs we be saved in the database ``database.db``.

  .. code-block:: bash

      pm-hsbid --config config.yml --create --save-hsbid

  The ``config.yml`` file is defined below:

  .. code-block:: yaml
      :caption: config.yml

      structure: '../../data/structure.yml'
      supa: |
        4 0 0
        0 4 0
        0 0 4
      pg: 'Oh'
      order:  2
      full_symmetry: True
      delta: [ 0.02, 0.03, 0.04]
      fdtype: 'c'
      root_directory: '.'
      database: 'database.db'
      db_type: 'sqlite'
      db_table: 'bid_phonon'

2. In this example, we use VASP to perform first principle calculations. This we need to create the input files for VASP calculations.

  .. code-block:: bash

      pm-jobs --config config.yml --create --engine vasp --save-config jobs_config.yml \
        --job-config-path ../../data/dft_files --root-directory jobs-to-run

  Where ``../../data/dft_files`` stores the template input files including ``INCAR``, ``POTCAR`` and ``KPOINTS``.
  After the input files are generated, we can execute VASP inside the directories of the individual jobs.

3. When the first principle calculations are finished. The following command can parse out the results of the calculations
   and store them into the database we created.

  .. code-block:: bash

      pm-jobs --config jobs_config.yml --retrieve

  The ``jobs_config.yml`` file is generated from the previous step.

4. Finally, we run the post-processing step to solve for the irreducible derivatives and compute dynamic tensors and real space force constant tensors.

  .. code-block:: bash

      pm-hsbid --load-hsbid hsbid.hdf5 --config config.yml \
          --post --save-fi --save-ids --save-dts

Plot phonon band structure and DOS
----------------------------------

1. First we prepare the configuration file ``phonon_config.yml`` to compute phonon band structure and DOS:

  .. code-block:: yaml
      :caption: phonon_config.yml

      band:
        - 0 0 0; 1/2 1/2 0
        - -1/2 1/2 0; 0 0 0
        - 0 0 0; 1/2 0 0
      band_label:
        - $\Gamma$
        - X
        - $\Gamma$
        - L
      mesh: 20 20 20

2. Then we compute phonon band structure and DOS with ``pm-phonon-band-dos`` command.

  .. code-block:: bash

      pm-phonon-band-dos --load-fi fourier_interpolation.hdf5 --config phonon_config.yml \
        --save-band --save-grid --save-dos --save-plot --units THz

3. Finally we can plot the phonon band structure and DOS of Al with the following to get :numref:`fig-exp-al-phonon`.

  .. code-block:: bash

      pm-plot-band --show band_plot_config.yml


.. figure:: ../figures/examples/al/al_phonon_dos.pdf
  :width: 400
  :align: center
  :name: fig-exp-al-phonon

  Phonon band structure and DOS of Al.


Working with Quantum-ESPRESSO
-----------------------------

1. If in this case we are working with Quantum-ESPRESSO (QE) instead of VASP, first we will need to create a template QE input file.

   .. code-block::
      :caption: NaCl.scf.in

       &control
          calculation = 'scf'
          tprnfor = .true.
          tstress = .true.
          pseudo_dir = 'pseudo/'
          restart_mode='from_scratch',
          outdir='tmp'
       /
       &system
          ibrav = 0
          nat = 1
          ntyp = 1
          ecutwfc = 60.0
       /
       &electrons
          diagonalization = 'david'
          conv_thr = 1.0d-8
       /
      ATOMIC_SPECIES
       Al  26.981539 Al.pbe-n-kjpaw_psl.1.0.0.UPF
      ATOMIC_POSITIONS crystal
       Al   0.0000000000000000  0.0000000000000000  0.0000000000000000
      CELL_PARAMETERS angstrom
        0.00000000   1.99208958   1.99208958
        1.99208958   0.00000000   1.99208958
        1.99208958   1.99208958   0.00000000
      K_POINTS automatic
        20 20 20 0 0 0

2. Then we create the input files for QE calculations. In the case of QE the option ``--job-config-path`` expects the path to the above
   template QE input file (The data in ``nat``, ``ATOMIC_POSITIONS``, ``CELL_PARAMETERS`` and ``K_POINTS`` of the template file will
   be replaced with the configurations of the jobs).

  .. code-block:: bash

      pm-jobs --config config.yml --create --engine qe --save-config jobs_config.yml \
        --job-config-path NaCl.scf.in --root-directory jobs-to-run

  After the input files are created the static QE calculations can be executed and the remaining steps are the same as before.