Quantum ESPRESSO Properties
***************************

Property calculations for the Quantum ESPRESSO engine can be requested
from two different sections: the **AMS driver Properties block** and
the **Quantum ESPRESSO engine Properties block**.


The AMS Driver Properties Block
===============================

The **AMS driver Properties block** contains properties that are
either common to other engines or have a numerical equivalent
calculated using finite differences. It's important to distinguish the
Quantum ESPRESSO solution, often referred to as the "analytical"
solution, from the numerical versions available at the AMS level. For
properties such as "NormalModes" and "Phonons", you can enforce the
numerical calculation within AMS by specifying
"NormalModes%Hessian=Numerical" or "Phonons%Method=Numerical". If the
numerical calculation is not explicitly requested, AMS will default to
the analytical solution provided by the QuantumEspresso engine.

   Properties
      NormalModes Yes/No
      Raman Yes/No
      Gradients Yes/No
      Phonons Yes/No
      StressTensor Yes/No
      PESPointCharacter Yes/No
   End

"Properties"
   Type:
      Block

   Description:
      Configures which AMS level properties to calculate for
      SinglePoint calculations or other important geometries (e.g. at
      the end of an optimization).

   "NormalModes"
      Type:
         Bool

      Default value:
         No

      GUI name:
         Frequencies

      Description:
         Calculate the frequencies and normal modes of vibration, as
         well as the corresponding IR intensities, if the engine
         supports these calculations natively or can calculate dipole
         moments.

   "Raman"
      Type:
         Bool

      Default value:
         No

      Description:
         Requests calculation of Raman intensities for vibrational
         normal modes.

   "Gradients"
      Type:
         Bool

      Default value:
         No

      GUI name:
         Nuclear gradients

      Description:
         Calculate the nuclear gradients.

   "Phonons"
      Type:
         Bool

      Default value:
         No

      Description:
         Calculate the phonons (for periodic systems).

   "StressTensor"
      Type:
         Bool

      Default value:
         No

      GUI name:
         Stress tensor

      Description:
         Calculate the stress tensor.

   "PESPointCharacter"
      Type:
         Bool

      Default value:
         No

      GUI name:
         Characterize PES point

      Description:
         Determine whether the sampled PES point is a minimum or
         saddle point. Note that for large systems this does not
         entail the calculation of the full Hessian and can therefore
         be used to quickly confirm the success of a geometry
         optimization or transition state search.

At the AMS level, you can request the calculation of the phonons
density of states (DOS) and/or the band structure:

   Phonons
      BandStructure Yes/No
      DOS Yes/No
      Method [Auto | Analytical | Numerical]
   End

"Phonons"
   Type:
      Block

   Description:
      Configures the phonons calculation.

   "BandStructure"
      Type:
         Bool

      Default value:
         Yes

      GUI name:
         Calculate phonons band structure

      Description:
         Calculates and saves the phonon band structure for
         visualization. Further configuration options for analytical
         calculations may be available in the engine-specific settings
         ("Phonons%BandStructure").

   "DOS"
      Type:
         Bool

      Default value:
         Yes

      GUI name:
         Calculate phonon DOS

      Description:
         Calculates and saves the phonon density of states (DOS) for
         visualization. Further configuration options for analytical
         calculations may be available in the engine-specific settings
         ("Phonons%DOS").

   "Method"
      Type:
         Multiple Choice

      Default value:
         Auto

      Options:
         [Auto, Analytical, Numerical]

      Description:
         Determines how phonons are calculated. "Auto" selects the
         analytical method if supported by the engine, otherwise it
         defaults to numerical calculation. Configure numerical
         parameters in the "NumericalPhonons" section. Engine-specific
         options for analytical phonon calculations may be available
         in "Engine%Phonons".


The QuantumEspresso Engine Properties Block
===========================================

The **QuantumEspresso engine Properties block** contains properties
specific to the engine, namely the Electronic BandStructure, DOS, and
WorkFunction. These properties do not have equivalents at the AMS
level.

   Engine QuantumEspresso
      ...
      Properties
         BandStructure Yes/No
         DOS Yes/No
         ForceStopAfterError Yes/No
         MagneticAnisotropyEnergy Yes/No
         WorkFunction Yes/No
      End
   EndEngine

"Properties"
   Type:
      Block

   Description:
      Configures which QE level properties to calculate for
      SinglePoint calculations or other important geometries (e.g. at
      the end of an optimization).

   "BandStructure"
      Type:
         Bool

      Default value:
         No

      GUI name:
         Calculate band structure

      Description:
         If true, the band structure is calculated and saved for
         visualization. To configure the parameters of the
         calculation, please modify the options in the the section
         'BandStructure'.

   "DOS"
      Type:
         Bool

      Default value:
         No

      GUI name:
         Calculate DOS

      Description:
         If true, the Density-Of-States (DOS) is calculated and saved
         for visualization. To configure the parameters of the
         calculation, please modify the options in the the section
         'DOS'.

   "ForceStopAfterError"
      Type:
         Bool

      Default value:
         No

      Description:
         If set to true, and a Quantum Espresso property calculation
         fails, the entire job will stop, preventing any subsequent
         property calculations from running. If set to false
         (default), other property calculations will proceed even if
         one fails.

   "MagneticAnisotropyEnergy"
      Type:
         Bool

      Default value:
         No

      GUI name:
         Calculate MAE

      Description:
         If true, the Magnetic Anisotropy Energy (MAE) is calculated
         and saved for visualization. To configure the parameters of
         the calculation, please modify the options in the the section
         'MagneticAnisotropyEnergy'.

   "WorkFunction"
      Type:
         Bool

      Default value:
         No

      GUI name:
         Calculate work function

      Description:
         If true, the work function is calculated and saved for
         visualization. To configure the parameters of the
         calculation, please modify the options in the the section
         'WorkFunction'.


Properties Configuration Blocks
===============================

Each property described above has its own section with specific
parameters, including those requested at the AMS level. The general
structure is sketched below. Please note that the "Phonons" section is
special because it contains two nested subsections:
"Phonons%BandStructure" and "Phonons%DOS". Be careful not to confuse
these with their electronic section counterparts "BandStructure" and
"DOS".

   Engine QuantumEspresso
      ...
      BandStructure
         ...
      End
      DOS
         ...
      End
      MagneticAnisotropyEnergy
         ...
      End
      NormalModes
         ...
      End
      Phonons
         ...
         BandStructure
            ...
         End
         DOS
            ...
         End
      End
      WorkFunction
         ...
      End
   EndEngine


Electronic Band Structure
=========================

This section configures the parameters for calculating the Band
Structure. This involves using the following utilities:

* "kpath": This tool generates an automated high-symmetry k-path in
  the Brillouin zone. This is not a QE utility.

* pw.x (with calculation=bands): This QE utility performs electronic
  structure calculations, particularly for bands.

* bands.x: Another QE utility, which calculates the band structure.

The calculation sequence follows the order: "kpath ->
pw.x(calculation=nscf) -> bands.x".

Tip:

  Before calculating the band structure, make sure that the crystal
  unit cell corresponds to the **primitive** unit cell!

   BandStructure
      KPathFinderConvention [Setyawan-Curtarolo | Hinuma]
      K_Points header # Non-standard block. See details.
         ...
      End
      K_PointsLabels string
      K_PointsStep float
      UseSymmetry Yes/No
      nbnd integer
   End

"BandStructure"
   "KPathFinderConvention"
      Type:
         Multiple Choice

      Default value:
         Setyawan-Curtarolo

      Options:
         [Setyawan-Curtarolo, Hinuma]

      Description:
         This option determines how the path through the Brillouin
         zone is generated when using the automatic k-point mode.
         Available options:                      • "Setyawan-
         Curtarolo" (default for 1D and 2D lattices): Uses our built-
         in KPath program to find a path through high-symmetry points
         based on the method by Setyawan and Curtarolo
         (https://doi.org/10.1016/j.commatsci.2010.05.010). For 2D
         lattices, the path is derived from the intersection of the 3D
         Brillouin zone with a plane. For 1D lattices, the path is
         simply "GAMMA-Z".                      • "Hinuma": Uses the
         external SeeKPath utility to generate the k-path
         (https://github.com/giovannipizzi/seekpath and
         https://doi.org/10.1016/j.commatsci.2016.10.015).

   "K_Points"
      Type:
         Non-standard block

      Description:
         Specify the k-points to use. Choose a header appropriate for
         your system. Supported values: "tpiba", "automatic",
         "crystal", "gamma", "tpiba_b", "crystal_b", "tpiba_c",
         "crystal_c", and "ams_kpath". See the QE documentation for
         details. If omitted, "ams_kpath" will be used for 3D systems,
         and "gamma" otherwise. For most cases, "ams_kpath" (which
         generates a convenient path along high-symmetry k-points in
         the Brillouin zone) is recommended.

   "K_PointsLabels"
      Type:
         String

      Description:
         You can provide labels for your k-points, like
         "L-GAMMA-X-U-GAMMA", separating each label with a hyphen (-)
         or a vertical bar (|). For example, "L-GAMMA-X-U-GAMMA" and
         "L|GAMMA|X|U|GAMMA" are both valid. These labels are optional
         and only used for display purposes when the "K_Points" block
         is specified. This option is used only if the header of the
         "BandStructure%K_Points" block is not "ams_kpath".
         **Important:** These labels do not determine the actual
         k-point coordinates. You must specify the k-point coordinates
         separately within the "K_Points" section.

   "K_PointsStep"
      Type:
         Float

      Default value:
         0.05

      Unit:
         1/Bohr

      Description:
         Step size in reciprocal space for band structure calculation.
         Using a smaller number will produce smoother band curves at
         an increased computational time. This option is used only if
         the header of the "BandStructure%K_Points" block is
         "ams_kpath".

   "UseSymmetry"
      Type:
         Bool

      Default value:
         Yes

      Description:
         If set, only the irreducible wedge of the Wigner-Seitz cell
         is sampled. If not, the whole (inversion-unique) Wigner-Seitz
         cell is sampled. Only available for Setyawan and Curtarolo
         convention (see "KPathFinderConvention").

   "nbnd"
      Type:
         Integer

      GUI name:
         Number of bands

      Description:
         Number of electronic states (bands) to be calculated. Note
         that in spin-polarized calculations the number of k-point,
         not the number of bands per k-point, is doubled.
         Default: 20% more (minimum of 4 additional bands) than the
         number used in the main 'pw.x' calculation, regardless of the
         material's insulating or metallic nature. Notice that this
         default is calculated differently than in standard QE.


Electronic Density of States (DOS, PDOS)
========================================

This section configures the parameters for calculating the electronic
Density of States (DOS). These are the utilities involved:

* pw.x (with "calculation=nscf"): This QE utility conducts electronic
  structure calculations, specifically for the non-self-consistent
  field (nscf) computation.

* dos.x: A QE utility utilized for post-processing electronic
  structure calculations. It analyzes the electronic wavefunctions
  obtained from preceding calculations to determine the density of
  available electronic states at different energy levels.

* projwfc.x: Another QE utility employed for post-processing
  electronic structure calculations. It projects the wavefunctions
  onto atomic orbitals or basis sets, offering insights into the
  composition and character of electronic states.

By default, the calculation sequence follows the order:
"pw.x(calculation=nscf) -> dos.x". However, enabling "DOS%PDOS"
switches the calculation to use "projwfc.x" instead of "dos.x".

   DOS
      DeltaE float
      Emax float
      Emin float
      K_Points header # Non-standard block. See details.
         ...
      End
      K_PointsStep float
      PDOS Yes/No
      degauss float
      nbnd integer
      ngauss [SimpleGaussian | Methfessel-Paxton | ColdSmearing | Fermi-Dirac | Default]
      occupations [Smearing | Tetrahedra | Tetrahedra_lin | Tetrahedra_opt | Fixed | Auto]
      smearing [Gaussian | Methfessel-Paxton | Marzari-Vanderbilt | Fermi-Dirac]
   End

"DOS"
   "DeltaE"
      Type:
         Float

      Default value:
         0.1

      Unit:
         eV

      GUI name:
         Energy step

      Description:
         Energy grid step.

   "Emax"
      Type:
         Float

      Unit:
         eV

      Description:
         Maximum energy for DOS plot. If unspecified, the upper band
         value, plus 3 times the value of the gaussian smearing if
         present, will be used.

   "Emin"
      Type:
         Float

      Unit:
         eV

      Description:
         Minimum energy for DOS plot. If unspecified, the lower band
         value, minus 3 times the value of the gaussian smearing if
         present, will be used.

   "K_Points"
      Type:
         Non-standard block

      Description:
         Specify the k-points to use. Choose a header appropriate for
         your system. Supported values: "tpiba", "automatic",
         "crystal", "gamma", "tpiba_b", "crystal_b", "tpiba_c",
         "crystal_c", and "ams_kpath". See the QE documentation for
         details. If omitted, the k-points specified in the main QE
         calculation will be used. For most cases, "automatic" (which
         generates a Monkhorst-Pack grid) is recommended.

   "K_PointsStep"
      Type:
         Float

      Default value:
         0.05

      Unit:
         1/Bohr

      Description:
         This option is used only if the header of the "DOS%K_Points"
         block is "ams_kpath".

   "PDOS"
      Type:
         Bool

      Default value:
         No

      GUI name:
         Calculate PDOS and Lowdin charges

      Description:
         If true, the partial Density-Of-States (projections on atomic
         basis functions) is calculated and saved for visualization.
         It uses the QE-utility "projwfc.x". To configure the
         parameters of the calculation, please modify the options in
         the the section "PROJWFC_X".

   "degauss"
      Type:
         Float

      Unit:
         Rydberg

      GUI name:
         Broadening width

      Description:
         Gaussian broadening. See more details in sections "DOS_X" or
         "PROJWFC_X".

   "nbnd"
      Type:
         Integer

      GUI name:
         Number of bands

      Description:
         Number of electronic states (bands) to be calculated. Note
         that in spin-polarized calculations the number of k-point,
         not the number of bands per k-point, is doubled.
         Default: 20% more (minimum of 4 additional bands) than the
         number used in the main 'pw.x' calculation, regardless of the
         material's insulating or metallic nature. Notice that this
         default is calculated differently than in standard QE.

   "ngauss"
      Type:
         Multiple Choice

      Default value:
         Default

      Options:
         [SimpleGaussian, Methfessel-Paxton, ColdSmearing, Fermi-
         Dirac, Default]

      GUI name:
         Broadening type

      Description:
         Type of gaussian broadening: Available options are:
         • SimpleGaussian.                      • Methfessel-Paxton:
         Methfessel-Paxton of order 1.                      •
         ColdSmearing: Marzari-Vanderbilt-DeVita-Payne.
         • Fermi-Dirac: Fermi-Dirac function.                      •
         Default: See more details in sections "DOS_X" or "PROJWFC_X".

   "occupations"
      Type:
         Multiple Choice

      Default value:
         Auto

      Options:
         [Smearing, Tetrahedra, Tetrahedra_lin, Tetrahedra_opt, Fixed,
         Auto]

      GUI name:
         Non-SCF Occupations

      Description:
         Available options are:                      • Smearing:
         gaussian smearing for metals; see keywords "smearing" and
         "degauss"                      • Tetrahedra: Tetrahedron
         method, Bloechl's version: P.E. Bloechl, PRB 49, 16223
         (1994). Requires uniform grid of k-points, to be
         automatically generated (see "block K_Points"). Well suited
         for calculation of DOS, less so (because not variational) for
         force/optimization/dynamics calculations.
         • Tetrahedra_lin: Original linear tetrahedron method. To be
         used only as a reference; the optimized tetrahedron method is
         more efficient.                      • Tetrahedra_opt:
         optimized tetrahedron method, see M. Kawamura, PRB 89, 094515
         (2014). Can be used for phonon calculations as well.
         • Fixed: for insulators with a gap.                       •
         Auto: Uses "Tetrahedra" for 3D and 2D systems, and "Fixed"
         for 0D and 1D systems.

   "smearing"
      Type:
         Multiple Choice

      Default value:
         Gaussian

      Options:
         [Gaussian, Methfessel-Paxton, Marzari-Vanderbilt, Fermi-
         Dirac]

      GUI name:
         Smearing

      Description:
         Available options are:                      • Gaussian:
         ordinary Gaussian spreading                      •
         Methfessel-Paxton: first-order spreading (see PRB 40, 3616
         (1989))                      • Marzari-Vanderbilt: cold
         smearing (see PRL 82, 3296 (1999))                      •
         Fermi-Dirac: smearing with Fermi-Dirac function


Magnetic Anisotropy Energy (MAE)
================================

This section configures the parameters for calculating the Magnetic
Anisotropy Energy (MAE). These are the utilities involved:

* pw.x (with "calculation=nscf" and Spin-Orbit Coupling): This QE
  utility invoked multiple times to perform non-self-consistent field
  (NSCF) electronic structure calculations. It evaluates the user-
  defined spin orientations specifically for the implementation of the
  Magnetic Force Theorem.

   MagneticAnisotropyEnergy
      K_Points header # Non-standard block. See details.
         ...
      End
      Pseudopotentials
         Directory string
         Family [Dojo | GBRV | pslibrary-PAW | pslibrary-US | SG15 | SSSP-Efficiency | SSSP-Precision]
         Files
            Label string
            Path string
         End
         FullyRelativistic Yes/No
         Functional [BLYP | LDA | PBE | PBEsol | PW91]
      End
      ReferenceSpecies string
      ReferenceState string
      State
         Label string
         SpinOrientation
            Label string
            Phi float
            Theta float
         End
      End
      conv_thr float
      nosym Yes/No
   End

"MagneticAnisotropyEnergy"
   "K_Points"
      Type:
         Non-standard block

      Description:
         Specify the k-points to use in the non-self-consistent
         calculation (second step in MAE). Choose a header appropriate
         for your system. Supported values: "tpiba", "automatic",
         "crystal", "gamma", "tpiba_b", "crystal_b", "tpiba_c",
         "crystal_c", and "ams_kpath". See the QE documentation for
         details. If omitted, the k-points specified in the main QE
         calculation will be used. For most cases, "automatic" (which
         generates a Monkhorst-Pack grid) is recommended.

   "Pseudopotentials"
      Type:
         Block

      Description:
         Specifies the pseudopotentials to use specifically for the
         NSCF+SOC step in the MAE calculation. If unspecified, the
         main 'Pseudopotentials' block is used by default. In the GUI,
         enabling this override starts from a copy of the current main
         QE pseudopotentials settings. If using 'Files', you must
         manually select a fully-relativistic pseudopotential file
         when required for Spin-Orbit Coupling (SOC).

      "Directory"
         Type:
            String

         Description:
            This key is mutually exclusive with the "Family" and
            "Files" keywords. This key specifies a directory
            containing label.upf files.
            Example:                         .. code-block:: text
            System                         Atoms
            H 0 0 0                         H 0 0 1 QE.Label=H1
            H 0 0 2 QE.Label=H2                         C 0 0 3
            QE.Label=C1                         End
            End                         This will look for the files
            H.upf, H1.upf, H2.upf, C1.upf. If H1.upf does not exist,
            H.upf will be used. If H2.upf does not exist, H.upf will
            be used. If C1.upf does not exist, C.upf will be used.

      "Family"
         Type:
            Multiple Choice

         Default value:
            SSSP-Efficiency

         Options:
            [Dojo, GBRV, pslibrary-PAW, pslibrary-US, SG15, SSSP-
            Efficiency, SSSP-Precision]

         GUI name:
            Pseudopotential family

         Description:
            The pseudopotential family to use. Mutually exclusive with
            the "Files" and "Directory" keywords.

      "Files"
         Type:
            Block

         Recurring:
            True

         Description:
            Selects the pseudopotentials to use for each atomic
            species. This key is mutually exclusive with the "Family"
            and "Directory" keywords.

         "Label"
            Type:
               String

            Description:
               Label for an atom corresponding to the QE.Label, or to
               the element symbol if QE.Label is not set.

         "Path"
            Type:
               String

            Description:
               Path to a .upf file to use as pseudopotential. Relative
               paths are relative to root of the pseudopotential
               library shipped with AMS. Prefix a path with './' to
               make it relative to the starting directory of your job.

      "FullyRelativistic"
         Type:
            Bool

         Default value:
            Yes

         GUI name:
            Pseudopotential fully relativistic

         Description:
            Whether to use fully relativistic pseudopotentials
            (required for spin-orbit calculations).

      "Functional"
         Type:
            Multiple Choice

         Default value:
            PBE

         Options:
            [BLYP, LDA, PBE, PBEsol, PW91]

         GUI name:
            Pseudopotential functional

         Description:
            Exchange-correlation functional that was used to generate
            the pseudopotential. Not all choices are valid for all
            pseudopotential families.                         This
            functional will also be used for the calculation, unless
            the "input_dft" option is set.

   "ReferenceSpecies"
      Type:
         String

      Default value:
      Description:
         Sets the atomic type used as the primary axis for spin
         orientation. This species is placed first in the input to
         ensure its angles define the global magnetic rotation of the
         system. If not specified, the selection is arbitrary and
         based on the alphabetical order of the atomic types.

   "ReferenceState"
      Type:
         String

      Description:
         Specifies the 'Label' of the 'State' block to be used as the
         zero-energy reference. MAE values will be calculated as
         "E_band - E_ref". If left empty, the state with the lowest
         band energy is automatically selected as the reference.

   "State"
      Type:
         Block

      Recurring:
         True

      Description:
         Defines a specific spin configuration (a 'State') for which
         to run one NSCF+SOC calculation. This block can be repeated
         multiple times to define all orientations of interest.

      "Label"
         Type:
            String

         Description:
            A unique user-defined string to identify this state. This
            label is used by the 'ReferenceState' keyword and in the
            output files.

      "SpinOrientation"
         Type:
            Block

         Recurring:
            True

         Description:
            Defines the spin quantization axis (theta, phi) for atoms
            matching the 'Label'. This block can be repeated within a
            'State' to define non-collinear or per-atom spin
            structures.

         "Label"
            Type:
               String

            Description:
               Label for an atom corresponding to the QE.Label, or to
               the element symbol if QE.Label is not set.

         "Phi"
            Type:
               Float

            Description:
               The angle expressed in degrees between the projection
               of the initial magnetization on x-y plane and the
               x-axis for the specified QE.Label.

         "Theta"
            Type:
               Float

            Description:
               The angle expressed in degrees between the initial
               magnetization and the z-axis for the specified
               QE.Label.

   "conv_thr"
      Type:
         Float

      Default value:
         1e-06

      Unit:
         Rydberg

      GUI name:
         Convergence threshold

      Description:
         For the non-self-consistent calculation (second step in MAE),
         "conv_thr" is used to set the default value of the threshold
         (ethr) for iterative diagonalization. If unspecified,
         "Electrons%conv_thr" will be used.

   "nosym"
      Type:
         Bool

      Default value:
         No

      GUI name:
         Disable symmetry (nosym)

      Description:
         Same as "System%nosym" but applies only for the non-self-
         consistent calculation (second step in MAE). If unspecified,
         "System%nosym" will be used


Analytical Normal Modes (IR & Raman Spectra)
============================================

This section configures the parameters for calculating the IR and
Raman spectra. These are the utilities involved:

* ph.x: This QE utility is used to calculate phonon frequencies and
  eigenvectors at a specific q-point, typically the Γ point, in the
  Brillouin zone. This is done using density functional perturbation
  theory (DFPT) to compute the dynamical matrix, which captures the
  interatomic force constants.

* dynmat.x: This QE utility is used to post-process the phonon data,
  obtaining the IR and Raman intensities, frequencies, and vibrational
  modes. This step involves computing the Born effective charges and
  the Raman tensors, which describe the coupling of the vibrational
  modes to the electric field and the change in polarizability,
  respectively.

The calculation sequence follows the order: "ph.x -> dynmat.x".

   NormalModes
      ActiveAtoms integer_list
      ActiveAtomsInRegion string
      asr [no | simple | crystal | one-dim | zero-dim]
      tr2_ph float
      xq1 float
      xq2 float
      xq3 float
   End

"NormalModes"
   "ActiveAtoms"
      Type:
         Integer List

      Description:
         This is a list of atoms to be used in the linear response
         calculation. It can help estimate modes for a molecule
         adsorbed on a surface without requiring a full calculation.
         Please be aware that this is an approximation and may not be
         reliable. If you perform a linear response calculation for a
         specific atom, you should also do so for all symmetry-
         equivalent atoms. This option serves as an interface to the
         "ph.x" option "nat_todo". This is an experimental feature!

   "ActiveAtomsInRegion"
      Type:
         String

      Description:
         Specify the region of atoms to be included in the linear
         response calculation. It can help estimate modes for a
         molecule adsorbed on a surface without requiring a full
         calculation. Please be aware that this is an approximation
         and may not be reliable. If you perform a linear response
         calculation for a specific atom, you should also do so for
         all symmetry-equivalent atoms. This option serves as an
         interface to the "ph.x" option "nat_todo". This is an
         experimental feature!

   "asr"
      Type:
         Multiple Choice

      Default value:
         no

      Options:
         [no, simple, crystal, one-dim, zero-dim]

      Description:
         Indicates the type of Acoustic Sum Rule imposed. Allowed
         values: 'no', 'simple', 'crystal', 'one-dim', 'zero-dim'

   "tr2_ph"
      Type:
         Float

      Default value:
         1e-12

      Description:
         Threshold for self-consistency. It overwrites "PH_X%tr2_ph".

   "xq1"
      Type:
         Float

      Default value:
         0.0

      Description:
         First component of the phonon wavevector (q-point) at which
         the IR spectrum is calculated, in units of 2pi/a0 (a0 =
         lattice parameter). It overwrites "PH_X%xq1".

   "xq2"
      Type:
         Float

      Default value:
         0.0

      Description:
         Second component of the phonon wavevector (q-point) at which
         the IR spectrum is calculated, in units of 2pi/a0 (a0 =
         lattice parameter). It overwrites "PH_X%xq2".

   "xq3"
      Type:
         Float

      Default value:
         0.0

      Description:
         Third component of the phonon wavevector (q-point) at which
         the IR spectrum is calculated, in units of 2pi/a0 (a0 =
         lattice parameter). It overwrites "PH_X%xq3".


Analytical Phonons
==================

This section configures the parameters for calculating the phonons.
These are the utilities involved:

* "kpath": This tool generates an automated high-symmetry k-path in
  the Brillouin zone. This is not a QE utility.

* ph.x: This QE utility is used to calculate the phonon frequencies
  and eigenvectors at a uniform grid of q-points in the Brillouin
  zone. This is the most computationally expensive part. This step
  employs density functional perturbation theory (DFPT) to compute the
  dynamical matrix, which captures the interatomic force constants and
  provides the foundation for phonon analysis.

* q2r.x: This QE utility is used to perform a Fourier transform of the
  interatomic force constants from the q-point grid to real space,
  enabling the calculation of phonon properties in a more convenient
  representation.

* matdyn.x: This QE utility is employed to post-process the phonon
  data, allowing us to extract the phonon DOS and band structure
  (these are two independent calculations). This step involves
  calculating phonon frequencies for arbitrary q-vectors, including
  those along high-symmetry paths, using the interatomic force
  constants obtained from the dynamical matrices.

The calculation sequence follows the order: For the DOS, "ph.x ->
q2r.x -> matdyn.x" and for the band structure, "ph.x -> q2r.x -> kpath
-> matdyn.x".

   Phonons
      BandStructure
         KPathFinderConvention [Setyawan-Curtarolo | Hinuma]
         Q_Points header # Non-standard block. See details.
            ...
         End
         Q_PointsLabels string
         Q_PointsStep float
         UseSymmetry Yes/No
      End
      DOS
         Q_Points header # Non-standard block. See details.
            ...
         End
         degauss float
         deltaE float
         nq1 integer
         nq2 integer
         nq3 integer
      End
      K_Points header # Non-standard block. See details.
         ...
      End
      Q_Points header # Non-standard block. See details.
         ...
      End
      asr [simple | crystal | no]
      k1 integer
      k2 integer
      k3 integer
      nk1 integer
      nk2 integer
      nk3 integer
      nq1 integer
      nq2 integer
      nq3 integer
   End

"Phonons"
   "BandStructure"
      Type:
         Block

      Description:
         This section configures the parameters for calculating the
         Phonons Band Structure.

      "KPathFinderConvention"
         Type:
            Multiple Choice

         Default value:
            Setyawan-Curtarolo

         Options:
            [Setyawan-Curtarolo, Hinuma]

         Description:
            This option determines how the path through the Brillouin
            zone is generated when using the automatic k-point mode.
            Available options:                         • "Setyawan-
            Curtarolo" (default for 1D and 2D lattices): Uses our
            built-in KPath program to find a path through high-
            symmetry points based on the method by Setyawan and
            Curtarolo
            (https://doi.org/10.1016/j.commatsci.2010.05.010). For 2D
            lattices, the path is derived from the intersection of the
            3D Brillouin zone with a plane. For 1D lattices, the path
            is simply "GAMMA-Z".                         • "Hinuma":
            Uses the external SeeKPath utility to generate the k-path
            (https://github.com/giovannipizzi/seekpath and
            https://doi.org/10.1016/j.commatsci.2016.10.015).

      "Q_Points"
         Type:
            Non-standard block

         Description:
            Specify the q-points to use. Available header values are:
            "crystal_b", and "ams_kpath". See the examples and QE
            documentation for details. If omitted, "ams_kpath" is
            used.

      "Q_PointsLabels"
         Type:
            String

         Description:
            You can provide labels for your q-points, like
            "L-GAMMA-X-U-GAMMA", separating each label with a hyphen
            (-) or a vertical bar (|). For example,
            "L-GAMMA-X-U-GAMMA" and "L|GAMMA|X|U|GAMMA" are both
            valid. These labels are optional and only used for display
            purposes when the "Q_Points" block is specified. This
            option is used only if the header of the "Q_Points" block
            is not "ams_kpath". **Important:** These labels do not
            determine the actual k-point coordinates. You must specify
            the q-point coordinates separately within the "Q_Points"
            section.

      "Q_PointsStep"
         Type:
            Float

         Default value:
            0.05

         Unit:
            1/Bohr

         Description:
            This option is used only if the header of the
            "Phonons%BandStructure%Q_Points" block is "ams_kpath".

      "UseSymmetry"
         Type:
            Bool

         Default value:
            Yes

         Description:
            If set, only the irreducible wedge of the Wigner-Seitz
            cell is sampled. If not, the whole (inversion-unique)
            Wigner-Seitz cell is sampled. Only available for Setyawan
            and Curtarolo convention (see "KPathFinderConvention").

   "DOS"
      Type:
         Block

      Description:
         Configures the parameters for calculating the Phonons DOS.

      "Q_Points"
         Type:
            Non-standard block

         Description:
            Specify the q-points to use. Only the header "automatic"
            is allowed. This option is added for consistency, it is
            equivalent to set "nq1", "nq2", and "nq3" independently.

      "degauss"
         Type:
            Float

         Default value:
            0.0

         GUI name:
            Broadening width

         Description:
            DOS broadening in cm-1. Default: 0 - meaning use
            tetrahedra. It overwrites "MATDYN_X%degauss".

      "deltaE"
         Type:
            Float

         Default value:
            1.0

         GUI name:
            Energy step

         Description:
            Energy step, in cm-1, for DOS calculation: from min to max
            phonon energy (default: 1 cm-1). It overwrites
            "MATDYN_X%deltaE".

      "nq1"
         Type:
            Integer

         Default value:
            6

         Description:
            Uniform q-point grid for DOS calculation (includes q=0).
            First direction. It overwrites "MATDYN_X%nk1".

      "nq2"
         Type:
            Integer

         Default value:
            6

         Description:
            Uniform q-point grid for DOS calculation (includes q=0).
            Second direction. It overwrites "MATDYN_X%nk2".

      "nq3"
         Type:
            Integer

         Default value:
            6

         Description:
            Uniform q-point grid for DOS calculation (includes q=0).
            Third direction. It overwrites "MATDYN_X%nk3".

   "K_Points"
      Type:
         Non-standard block

      Description:
         When these block is specified the phonon program ("ph.x")
         runs a pw non-self consistent calculation with a different
         k-point grid thant that used for the charge density. The only
         available header values are "automatic" or "gamma". See the
         examples and QE documentation for details. This parameter is
         equivalent to "nk1, nk2, nk3, k1, k2, k3" in the QE tool
         "ph.x". If omitted, "ph.x" will use the same k-point grid
         used in the main QE calculation.

   "Q_Points"
      Type:
         Non-standard block

      Description:
         Defines the Monkhorst-Pack grid (no offset) for sampling the
         Brillouin zone in the phonon calculation. The grid determines
         the density of q-points at which phonon frequencies will be
         calculated. It is used when DOS or BandStructure phonon
         properties are requested. The only available header values
         are "automatic" or "gamma". See the examples and QE
         documentation for details. This parameter is equivalent to
         "nq1, nq2, nq3" in the QE tool "ph.x". If omitted, only
         "gamma" ("1 1 1 0 0 0") is used.

   "asr"
      Type:
         Multiple Choice

      Default value:
         simple

      Options:
         [simple, crystal, no]

      GUI name:
         Acoustic sum rule

      Description:
         Determines the acoustic sum rule (ASR) treatment. It has
         three options:                      * 'simple':  Applies a
         simplified ASR where the frequencies of the three acoustic
         modes at q=0 are forced to be zero.                      *
         'crystal': Applies the ASR considering the crystal symmetry
         to impose constraints on the frequencies at q=0.
         * 'no':  Does not enforce any ASR. It overwrites "PH_X%asr"
         (setting it to .TRUE. if asr is not 'no'), "Q2R_X%zasr", and
         "MATDYN_X%asr". Notice that the default value is different
         than in standard QE (default 'simple').

   "k1"
      Type:
         Integer

      Default value:
         0

      Description:
         If specified, triggers a non-self-consistent calculation in
         *ph.x* with a separate Monkhorst-Pack k-point grid for
         phonons. This sets the k-point grid offset along the first
         reciprocal lattice vector for that grid.

   "k2"
      Type:
         Integer

      Default value:
         0

      Description:
         If specified, triggers a non-self-consistent calculation in
         *ph.x* with a separate Monkhorst-Pack k-point grid for
         phonons. This sets the k-point grid offset along the second
         reciprocal lattice vector for that grid.

   "k3"
      Type:
         Integer

      Default value:
         0

      Description:
         If specified, triggers a non-self-consistent calculation in
         *ph.x* with a separate Monkhorst-Pack k-point grid for
         phonons. This sets the k-point grid offset along the third
         reciprocal lattice vector for that grid.

   "nk1"
      Type:
         Integer

      Default value:
         0

      Description:
         If specified, triggers a non-self-consistent calculation in
         *ph.x* with a separate Monkhorst-Pack k-point grid for
         phonons. This sets the number of k-points along the first
         reciprocal lattice vector for that grid.

   "nk2"
      Type:
         Integer

      Default value:
         0

      Description:
         If specified, triggers a non-self-consistent calculation in
         *ph.x* with a separate Monkhorst-Pack k-point grid for
         phonons. This sets the number of k-points along the second
         reciprocal lattice vector for that grid.

   "nk3"
      Type:
         Integer

      Default value:
         0

      Description:
         If specified, triggers a non-self-consistent calculation in
         *ph.x* with a separate Monkhorst-Pack k-point grid for
         phonons. This sets the number of k-points along the third
         reciprocal lattice vector for that grid.

   "nq1"
      Type:
         Integer

      Default value:
         1

      Description:
         Sets the number of q-points along the first reciprocal
         lattice vector for the Monkhorst-Pack q-point grid for
         phonons. Default 1. Notice that this default is different
         than in standard QE (default 0).

   "nq2"
      Type:
         Integer

      Default value:
         1

      Description:
         Sets the number of q-points along the second reciprocal
         lattice vector for the Monkhorst-Pack q-point grid for
         phonons. Default 1. Notice that this default is different
         than in standard QE (default 0).

   "nq3"
      Type:
         Integer

      Default value:
         1

      Description:
         Sets the number of q-points along the third reciprocal
         lattice vector for the Monkhorst-Pack q-point grid for
         phonons. Default 1. Notice that this default is different
         than in standard QE (default 0).


Work Function
=============

This section configures the parameters for calculating the Work
Function. This involves using the following QE utilities:

* pp.x: This QE utility calculates the the electrostatic potential
  using the results from the last calculation.

* "average.x": This QE utility performs planar and macroscopic
  averages of the electrostatic potential along a specified direction,
  which are crucial for determining the vacuum level and subsequently
  the work function.

The calculation sequence follows the order: "pp.x -> average.x".

   WorkFunction
      centralize Yes/No
      idir [x | y | z]
      npt integer
   End

"WorkFunction"
   "centralize"
      Type:
         Bool

      Default value:
         Yes

      GUI name:
         Center system

      Description:
         Translates the calculated electrostatic potential along the
         "idir" coordinate, respecting periodic boundary conditions,
         so that the geometric center of the system is at the center
         of the coordinate.

   "idir"
      Type:
         Multiple Choice

      Default value:
         3

      Options:
         [x, y, z]

      GUI name:
         Use plane orthogonal to direction

      Description:
         "1" (or "x"), 2 (or "y") or 3 (or "z"). Planar average is
         done in the plane orthogonal to direction "idir", as defined
         for the crystal cell. The "idir" parameter defaults to the
         value of "System%edir" if it's set. Otherwise, "idir" is set
         to 3.

   "npt"
      Type:
         Integer

      GUI name:
         Number of interpolation points

      Description:
         Number of points used for the final interpolation of the
         planar and macroscopic averages of the electrostatic
         potential. This controls the resolution of the averaged
         potential data. If npt is less than or equal to N_idir (the
         number of FFT grid points along the specified direction), no
         interpolation is performed and the raw FFT data is used. The
         default value is 10 * N_idir, which typically provides
         sufficient resolution for accurate work function
         calculations.
