input_description -distribution {Quantum ESPRESSO} -package PWscf -program pw.x {

    toc {}

    intro {
        @b {Input data format:} { } = optional, [ ] = it depends, | = or
        
        All quantities whose dimensions are not explicitly specified are in
        RYDBERG ATOMIC UNITS. Charge is "number" charge (i.e. not multiplied 
        by e); potentials are in energy units (i.e. they are multiplied by e).
        
        @b BEWARE: TABS, CRLF, ANY OTHER STRANGE CHARACTER, ARE A SOURCES OF TROUBLE 
        @b USE ONLY PLAIN ASCII TEXT FILES (CHECK THE FILE TYPE WITH UNIX COMMAND "file")

        Namelists must appear in the order given below.
        Comment lines in @i namelists can be introduced by a "!", exactly as in 
        fortran code. Comments lines in @i cards can be introduced by 
        either a "!" or a "#" character in the first position of a line.
        Do not start any line in @i cards with a "/" character.
        Leave a space between card names and card options, e.g.
        ATOMIC_POSITIONS (bohr), not ATOMIC_POSITIONS(bohr)

        
        @b {Structure of the input data:}
        ===============================================================================
        
        @b &CONTROL
          ...
        @b /

        @b &SYSTEM
          ...
        @b /

        @b &ELECTRONS
          ...
        @b /

        [ @b &IONS
          ...
         @b / ]

        [ @b &CELL
          ...
         @b / ]

        [ @b &FCP
          ...
         @b / ]

        [ @b &RISM
          ...
         @b / ]

        @b ATOMIC_SPECIES
         X  Mass_X  PseudoPot_X
         Y  Mass_Y  PseudoPot_Y
         Z  Mass_Z  PseudoPot_Z

        @b ATOMIC_POSITIONS { alat | bohr | angstrom | crystal | crystal_sg }
          X 0.0  0.0  0.0  {if_pos(1) if_pos(2) if_pos(3)}
          Y 0.5  0.0  0.0
          Z 0.0  0.2  0.2

        @b K_POINTS { tpiba | automatic | crystal | gamma | tpiba_b | crystal_b | tpiba_c | crystal_c }
        if (gamma)
           nothing to read
        if (automatic)
           nk1, nk2, nk3, k1, k2, k3
        if (not automatic)
           nks
           xk_x, xk_y, xk_z,  wk
        if (tpipa_b or crystal_b in a 'bands' calculation) see Doc/brillouin_zones.pdf

        [ @b CELL_PARAMETERS { alat | bohr | angstrom }
           v1(1) v1(2) v1(3)
           v2(1) v2(2) v2(3)
           v3(1) v3(2) v3(3) ]

        [ @b OCCUPATIONS
           f_inp1(1)  f_inp1(2)  f_inp1(3) ... f_inp1(10)
           f_inp1(11) f_inp1(12) ... f_inp1(nbnd)
         [ f_inp2(1)  f_inp2(2)  f_inp2(3) ... f_inp2(10)
           f_inp2(11) f_inp2(12) ... f_inp2(nbnd) ] ]

        [ @b CONSTRAINTS
           nconstr  { constr_tol }
           constr_type(.)   constr(1,.)   constr(2,.) [ constr(3,.)   constr(4,.) ] { constr_target(.) } ]

        [ @b ATOMIC_VELOCITIES
           label(1)  vx(1) vy(1) vz(1)
           .....
           label(n)  vx(n) vy(n) vz(n) ]

        [ @b ATOMIC_FORCES
           label(1)  Fx(1) Fy(1) Fz(1)
           .....
           label(n)  Fx(n) Fy(n) Fz(n) ]

        [ @b ADDITIONAL_K_POINTS
             see: K_POINTS ]

        [ @b SOLVENTS
           label(1)     Density(1)     Molecule(1)
           label(2)     Density(2)     Molecule(2)
           .....
           label(nsolv) Density(nsolv) Molecule(nsolv) ]
        
        [ @b HUBBARD { atomic | ortho-atomic | norm-atomic | wf | pseudo }
          if (DFT+U)
              U  label(1)-manifold(1) u_val(1)
            [ J0 label(1)-manifold(1) j0_val(1) ]
              .....
              U  label(n)-manifold(n) u_val(n)
            [ J0 label(n)-manifold(n) j0_val(n) ]            
          if (DFT+U+J)
              paramType(1) label(1)-manifold(1) paramValue(1)
              .....
              paramType(n) label(n)-manifold(n) paramValue(n)            
          if (DFT+U+V)
              U  label(I)-manifold(I) u_val(I)
            [ J0 label(I)-manifold(I) j0_val(I) ]
              V  label(I)-manifold(I) label(J)-manifold(J) I J v_val(I,J)
              .....
              U  label(N)-manifold(N) u_val(N)
            [ J0 label(N)-manifold(N) j0_val(N) ]
              V  label(N)-manifold(N) label(M)-manifold(M) N M v_val(N,M)
        ]
        All Hubbard parameters must be specified in eV.
        manifold  = 3d, 2p, 4f...
        paramType = U, J, B, E2, or E3
        Check Doc/Hubbard_input.pdf for more details. 

    }

    #
    # namelist CONTROL
    #

    namelist CONTROL {

        var calculation -type CHARACTER {
            default { 'scf' }
            options {
                info {
                    A string describing the task to be performed. Options are:
                }
                opt -val 'scf' {} 
                opt -val 'nscf' {} 
                opt -val 'bands' {} 
                opt -val 'relax' {} 
                opt -val 'md' {}
                opt -val 'vc-relax' {} 
                opt -val 'vc-md' {}

                info {
                    (vc = variable-cell).
                }
            }
        }
        
        var title -type CHARACTER {
            default {' '}
            info {
                reprinted on output.
            }
        }
        
        var verbosity -type CHARACTER {
            default { 'low' }
            options {
                info {
                    Currently two verbosity levels are implemented:
                }
                opt -val 'high' {}
                opt -val 'low' {}

                info {
                    @b 'debug' and @b 'medium' have the same effect as @b 'high';
                    @b 'default' and @b 'minimal' as @b 'low'
                }
            }
        }
        
        var restart_mode -type CHARACTER {
            default { 'from_scratch' }
            options {
                info { Available options are: }

                opt -val 'from_scratch' {
                    From scratch. This is the normal way to perform a PWscf calculation
                }
                
                opt -val 'restart' {
                    From previous interrupted run. Use this switch only if you want to
                    continue, using the same number of processors and parallelization,
                    an interrupted calculation. Do not use to start a new one, or to
                    perform a non-scf calculations.  Works only if the calculation was
                    cleanly stopped using variable @ref max_seconds, or by user request
                    with an "exit file" (i.e.: create a file "prefix".EXIT, in directory
                    "outdir"; see variables @ref prefix, @ref outdir). The default for
                    @ref startingwfc and @ref startingpot is set to 'file'.
                }
            }   
        }
        
        var wf_collect -type LOGICAL { 
            info { OBSOLETE - NO LONGER IMPLEMENTED }
        }
        

        var nstep -type INTEGER {
            info {
                number of molecular-dynamics or structural optimization steps 
                performed in this run. If set to 0, the code performs a quick
                "dry run", stopping just after initialization. This is useful
                to check for input correctness and to have the summary printed.
                NOTE: in MD calculations, the code will perform "nstep" steps
                even if restarting from a previously interrupted calculation.
            }
            default {
                1  if @ref calculation == 'scf', 'nscf', 'bands';
                50 for the other cases
            }
        }
        
        var iprint -type INTEGER {
            default { write only at convergence }
            info {
                band energies are written every @i iprint iterations
            }
        }
        
        var tstress -type LOGICAL {
            default { .false. }
            info {
                calculate stress. It is set to .TRUE. automatically if
                @ref calculation == 'vc-md' or 'vc-relax'
            }
        }
        
        
        var tprnfor -type LOGICAL {
            info {
                calculate forces. It is set to .TRUE. automatically if
                @ref calculation == 'relax','md','vc-md'
            }
        }
        
        var dt -type REAL { 
            default { 20.D0 }
            info {
                time step for molecular dynamics, in Rydberg atomic units
                (1 a.u.=4.8378 * 10^-17 s : beware, the CP code uses
                 Hartree atomic units, half that much!!!)
            }
        }
        
        var outdir -type CHARACTER { 
            default { 
                value of the ESPRESSO_TMPDIR environment variable if set; 
                current directory ('./') otherwise 
            }
            info {
                input, temporary, output files are found in this directory,
                see also @ref wfcdir
            }
        }

        var wfcdir -type CHARACTER { 
            default { same as @ref outdir }
            info {
                This directory specifies where to store files generated by
                each processor (*.wfc{N}, *.igk{N}, etc.). Useful for
                machines without a parallel file system: set @ref wfcdir to
                a local file system, while @ref outdir should be a parallel
                or network file system, visible to all processors. Beware:
                in order to restart from interrupted runs, or to perform
                further calculations using the produced data files, you
                may need to copy files to @ref outdir. Works only for pw.x.
            }
        }
        
        var prefix -type CHARACTER { 
            default { 'pwscf' }
            info {
                prepended to input/output filenames:
                prefix.wfc, prefix.rho, etc.
            }
        }

        var lkpoint_dir -type LOGICAL { 
            info {
 		OBSOLETE - NO LONGER IMPLEMENTED
            }
        }
                
        var max_seconds -type REAL { 
            default { 1.D+7, or 150 days, i.e. no time limit }
            info {
                Jobs stops after @ref max_seconds CPU time. Use this option 
                in conjunction with option @ref restart_mode if you need to
                split a job too long to complete into shorter jobs that
                fit into your batch queues.
            }       
        }

        var etot_conv_thr -type REAL { 
            default { 1.0D-4 }
            info {
                Convergence threshold on total energy (a.u) for ionic
                minimization: the convergence criterion is satisfied
                when the total energy changes less than @ref etot_conv_thr
                between two consecutive scf steps. Note that @ref etot_conv_thr
                is extensive, like the total energy.
                See also @ref forc_conv_thr - both criteria must be satisfied
            }
        }

        var forc_conv_thr -type REAL { 
            default { 1.0D-3 }
            info {
                Convergence threshold on forces (a.u) for ionic minimization:
                the convergence criterion is satisfied when all components of 
                all forces are smaller than @ref forc_conv_thr.
                See also @ref etot_conv_thr - both criteria must be satisfied
            }
        }
                
        var disk_io -type CHARACTER { 
            default { see below }
            options {
                info {
                    Specifies the amount of disk I/O activity:
                    (only for binary files and xml data file in data directory;
                    other files printed at each molecular dynamics / structural
                    optimization step are not controlled by this option )
                }

                opt -val 'high' {
                    save charge to disk at each SCF step,
                    keep wavefunctions on disk (in "distributed" format),
                    save mixing data as well.
                    Do not use this option unless you have a good reason!
                    It is no longer needed to specify 'high' in order to be able
                    to restart from an interrupted calculation (see @ref restart_mode)
                }

                opt -val 'medium' {
                    save charge to disk at each SCF step,
                    keep wavefunctions on disk only if more than one k-point,
                    per process is present, otherwise keep them in memory;
                    save them to disk only at the end (in "portable" format)
                }

                opt -val 'low' {
                    save charge to disk at each SCF step,
                    keep wavefunctions in memory (for all k-points),
                    save them to disk only at the end (in "portable" format).
                    Reduces I/O but increases memory wrt the previous cases
                }

                opt -val 'nowf' {
                    save to disk only the xml data file,
                    never save wavefunctions and charge density
                }

                opt -val 'none' {
                    do not save anything to disk
                }
            
                info {
                    @b Default is @b 'low' for the scf case, @b 'medium' otherwise.
                    Note that the needed RAM increases as disk I/O decreases

                }
            }
        }

        var pseudo_dir -type CHARACTER { 
            default { 
                value of the $ESPRESSO_PSEUDO environment variable if set; 
                '$HOME/espresso/pseudo/' otherwise 
            }
            info {
                directory containing pseudopotential files
            }
        }

        var tefield -type LOGICAL { 
            default { .FALSE. }
            info {
                If .TRUE. a saw-like potential simulating an electric field
                is added to the bare ionic potential. See variables @ref edir,
                @ref eamp, @ref emaxpos, @ref eopreg for the form and size of
                the added potential.

            }
        }

        var dipfield -type LOGICAL { 
            default { .FALSE. }
            info {
                If .TRUE. and @ref tefield==.TRUE. a dipole correction is also
                added to the bare ionic potential - implements the recipe
                of L. Bengtsson, PRB 59, 12301 (1999). See variables @ref edir,
                @ref emaxpos, @ref eopreg for the form of the correction. Must
                be used ONLY in a slab geometry, for surface calculations,
                with the discontinuity FALLING IN THE EMPTY SPACE.
            }
        }

        var lelfield -type LOGICAL { 
            default { .FALSE. }
            info {
                If .TRUE. a homogeneous finite electric field described
                through the modern theory of the polarization is applied.
                This is different from @ref tefield == .true. !
            }
        }
        
        var nberrycyc -type INTEGER { 
            default { 1 }
            info {
                In the case of a finite electric field  ( @ref lelfield == .TRUE. )
                it defines the number of iterations for converging the
                wavefunctions in the electric field Hamiltonian, for each
                external iteration on the charge density
            }
        }

       var lorbm -type LOGICAL { 
            default { .FALSE. }
            info {
                If @b .TRUE. perform orbital magnetization calculation.
                If finite electric field is applied (@ref lelfield==.true.) only Kubo terms are computed 
                [for details see New J. Phys. 12, 053032 (2010), doi:10.1088/1367-2630/12/5/053032].

                The type of calculation is @b 'nscf' and should be performed on an automatically
                generated uniform grid of k points.

                Works ONLY with norm-conserving pseudopotentials.
            }
        }

        var lberry -type LOGICAL {  
            default { .FALSE. }
            info {
                If .TRUE. perform a Berry phase calculation.
                See the header of PW/src/bp_c_phase.f90 for documentation.
            }
        }
                
        var gdir -type INTEGER {
            info {
               For Berry phase calculation: direction of the k-point
               strings in reciprocal space. Allowed values: 1, 2, 3
               1=first, 2=second, 3=third reciprocal lattice vector
               For calculations with finite electric fields
               (@ref lelfield==.true.) "gdir" is the direction of the field.
            }
        }

        var nppstr -type INTEGER {
            info {
                For Berry phase calculation: number of k-points to be
                calculated along each symmetry-reduced string.
                The same for calculation with finite electric fields
                (@ref lelfield==.true.).
            }
        }
        
        var gate -type LOGICAL {
            default { .FALSE. }
            see { zgate, relaxz, block, block_1, block_2, block_height }
            info {
                In the case of charged cells (@ref tot_charge .ne. 0) setting gate = .TRUE.
                represents the counter charge (i.e. -tot_charge) not by a homogeneous
                background charge but with a charged plate, which is placed at @ref zgate
                (see below). Details of the gate potential can be found in
                T. Brumme, M. Calandra, F. Mauri; PRB 89, 245406 (2014).
                Note, that in systems which are not symmetric with respect to the plate,
                one needs to enable the dipole correction! (@ref dipfield=.true.).
                Currently, symmetry can be used with gate=.true. but carefully check
                that no symmetry is included which maps @i z to -@i z even if in principle one
                could still use them for symmetric systems (i.e. no dipole correction).
                For @ref nosym=.false. verbosity is set to 'high'.
                Note: this option was called "monopole" in v6.0 and 6.1 of pw.x
            }
        }

        var twochem -type LOGICAL {
            default { .FALSE. }
            see { nelec_cond, nbnd_cond, degauss_cond }
            info {
             IF .TRUE. , a two chemical potential calculation for the simulation of
             photoexcited systems is performed, constraining a fraction of the 
             electrons in the conduction manifold. 
             See G. Marini, M. Calandra; PRB 104, 144103 (2021).  
             Note: requires @ref occupations to be set to 'smearing'.
            }
        }



        var lfcp -type LOGICAL {
            default { .FALSE. }
            info {
                If .TRUE. perform a constant bias potential (constant-mu) calculation
                for a system with ESM method. See the header of PW/src/fcp_module.f90 
                for documentation. To perform the calculation, you must set a namelist FCP.

                NB:
                - The total energy displayed in output includes the potentiostat
                  contribution (-mu*N).
                - @ref calculation must be 'relax' or 'md'. 
                - @ref assume_isolated = 'esm' and @ref esm_bc = 'bc2' or 'bc3' must be set
                  in @ref SYSTEM namelist.
                - ESM-RISM is also supported (@ref assume_isolated = 'esm' and @ref esm_bc = 'bc1'
                  and @ref trism = .TRUE.).
                - @ref ignore_wolfe is always .TRUE., for BFGS.
            }
        }

        var trism -type LOGICAL {
            default { .FALSE. }
            info {
                If .TRUE. perform a 3D-RISM-SCF calculation
                [for details see H.Sato et al., JCP 112, 9463 (2000), doi:10.1063/1.481564].
                The solvent's distributions are calculated by 3D-RISM,
                though solute is treated as SCF. The charge density and
                the atomic positions are optimized, simultaneously with
                the solvents. To perform the calculation, you must set
                a namelist @ref RISM and a card @ref SOLVENTS.

                If @ref assume_isolated = 'esm' and @ref esm_bc = 'bc1',
                Laue-RISM is calculated instead of 3D-RISM
                and coupled with ESM method (i.e. ESM-RISM).
                [for details see S.Nishihara and M.Otani, PRB 96, 115429 (2017)].

                The default of @ref mixing_beta is 0.2
                for both 3D-RISM and Laue-RISM.

                For structural relaxation with BFGS,
                @ref ignore_wolfe is always .TRUE. .
            }
        }

    }
    

    #
    # NAMELIST &SYSTEM
    #

    namelist SYSTEM {

        var ibrav -type INTEGER {
            status { REQUIRED }
            info {
                Bravais-lattice index. Optional only if space_group is set.
                If ibrav /= 0, specify EITHER [ @ref celldm(1)-@ref celldm(6) ]
                OR [ @ref A, @ref B, @ref C, @ref cosAB, @ref cosAC, @ref cosBC ]
                but NOT both. The lattice parameter "alat" is set to
                alat = celldm(1) (in a.u.) or alat = A (in Angstrom);
                see below for the other parameters.
                For ibrav=0 specify the lattice vectors in @ref CELL_PARAMETERS,
                optionally the lattice parameter alat = celldm(1) (in a.u.) 
                or = A (in Angstrom). If not specified, the lattice parameter is
                taken from @ref CELL_PARAMETERS 
                IMPORTANT NOTICE 1: 
                with ibrav=0 lattice vectors must be given with a sufficiently large
                number of digits and with the correct symmetry, or else symmetry 
                detection may fail and strange problems may arise in symmetrization.
                IMPORTANT NOTICE 2: 
                do not use celldm(1) or A as a.u. to Ang conversion factor, 
                use the true lattice parameters or nothing, 
                specify units in @ref CELL_PARAMETERS and @ref ATOMIC_POSITIONS
 
              ibrav      structure                   celldm(2)-celldm(6)
                                                   or: b,c,cosbc,cosac,cosab 
                0          free 
                    crystal axis provided in input: see card @ref CELL_PARAMETERS

                1          cubic P (sc) 
                    v1 = a(1,0,0),  v2 = a(0,1,0),  v3 = a(0,0,1)

                2          cubic F (fcc)
                    v1 = (a/2)(-1,0,1),  v2 = (a/2)(0,1,1), v3 = (a/2)(-1,1,0)

                3          cubic I (bcc)
                    v1 = (a/2)(1,1,1),  v2 = (a/2)(-1,1,1),  v3 = (a/2)(-1,-1,1)
               -3          cubic I (bcc), more symmetric axis:
                    v1 = (a/2)(-1,1,1), v2 = (a/2)(1,-1,1),  v3 = (a/2)(1,1,-1)

                4          Hexagonal and Trigonal P        celldm(3)=c/a
                    v1 = a(1,0,0),  v2 = a(-1/2,sqrt(3)/2,0),  v3 = a(0,0,c/a)

                5          Trigonal R, 3fold axis c        celldm(4)=cos(gamma)
                    The crystallographic vectors form a three-fold star around 
                    the z-axis, the primitive cell is a simple rhombohedron:
                    v1 = a(tx,-ty,tz),   v2 = a(0,2ty,tz),   v3 = a(-tx,-ty,tz)
                    where c=cos(gamma) is the cosine of the angle gamma between
                    any pair of crystallographic vectors, tx, ty, tz are:
                      tx=sqrt((1-c)/2), ty=sqrt((1-c)/6), tz=sqrt((1+2c)/3)
               -5          Trigonal R, 3fold axis <111>    celldm(4)=cos(gamma)
                    The crystallographic vectors form a three-fold star around 
                    <111>. Defining a' = a/sqrt(3) :
                    v1 = a' (u,v,v),   v2 = a' (v,u,v),   v3 = a' (v,v,u)
                    where u and v are defined as
                      u = tz - 2*sqrt(2)*ty,  v = tz + sqrt(2)*ty
                    and tx, ty, tz as for case ibrav=5
                    Note: if you prefer x,y,z as axis in the cubic limit,
                          set  u = tz + 2*sqrt(2)*ty,  v = tz - sqrt(2)*ty
                          See also the note in Modules/latgen.f90 
              
                6          Tetragonal P (st)               celldm(3)=c/a
                    v1 = a(1,0,0),  v2 = a(0,1,0),  v3 = a(0,0,c/a)

                7          Tetragonal I (bct)              celldm(3)=c/a
                    v1=(a/2)(1,-1,c/a),  v2=(a/2)(1,1,c/a),  v3=(a/2)(-1,-1,c/a)

                8          Orthorhombic P                  celldm(2)=b/a
                                                           celldm(3)=c/a
                    v1 = (a,0,0),  v2 = (0,b,0), v3 = (0,0,c)

                9          Orthorhombic base-centered(bco) celldm(2)=b/a
                                                           celldm(3)=c/a
                    v1 = (a/2, b/2,0),  v2 = (-a/2,b/2,0),  v3 = (0,0,c)
               -9          as 9, alternate description
                    v1 = (a/2,-b/2,0),  v2 = (a/2, b/2,0),  v3 = (0,0,c)
               91          Orthorhombic one-face base-centered A-type
                                                           celldm(2)=b/a
                                                           celldm(3)=c/a
                    v1 = (a, 0, 0),  v2 = (0,b/2,-c/2),  v3 = (0,b/2,c/2)

               10          Orthorhombic face-centered      celldm(2)=b/a
                                                           celldm(3)=c/a
                    v1 = (a/2,0,c/2),  v2 = (a/2,b/2,0),  v3 = (0,b/2,c/2)

               11          Orthorhombic body-centered      celldm(2)=b/a
                                                           celldm(3)=c/a
                    v1=(a/2,b/2,c/2),  v2=(-a/2,b/2,c/2),  v3=(-a/2,-b/2,c/2)

               12          Monoclinic P, unique axis c     celldm(2)=b/a
                                                           celldm(3)=c/a,
                                                           celldm(4)=cos(ab)
                    v1=(a,0,0), v2=(b*cos(gamma),b*sin(gamma),0),  v3 = (0,0,c)
                    where gamma is the angle between axis a and b. 
              -12          Monoclinic P, unique axis b     celldm(2)=b/a
                                                           celldm(3)=c/a,
                                                           celldm(5)=cos(ac)
                    v1 = (a,0,0), v2 = (0,b,0), v3 = (c*cos(beta),0,c*sin(beta))
                    where beta is the angle between axis a and c

               13          Monoclinic base-centered        celldm(2)=b/a
                           (unique axis c)                 celldm(3)=c/a,
                                                           celldm(4)=cos(gamma)
                    v1 = (  a/2,         0,          -c/2),
                    v2 = (b*cos(gamma), b*sin(gamma), 0  ),
                    v3 = (  a/2,         0,           c/2),
                    where gamma=angle between axis a and b projected on xy plane

              -13          Monoclinic base-centered        celldm(2)=b/a
                           (unique axis b)                 celldm(3)=c/a,
                                                           celldm(5)=cos(beta)
                    v1 = (  a/2,       b/2,             0),
                    v2 = ( -a/2,       b/2,             0),
                    v3 = (c*cos(beta),   0,   c*sin(beta)),
                    where beta=angle between axis a and c projected on xz plane
               IMPORTANT NOTICE: until QE v.6.4.1, axis for ibrav=-13 had a 
               different definition: v1(old) =-v2(now), v2(old) = v1(now)

               14          Triclinic                       celldm(2)= b/a,
                                                           celldm(3)= c/a,
                                                           celldm(4)= cos(bc),
                                                           celldm(5)= cos(ac),
                                                           celldm(6)= cos(ab)
                    v1 = (a, 0, 0),
                    v2 = (b*cos(gamma), b*sin(gamma), 0)
                    v3 = (c*cos(beta),  c*(cos(alpha)-cos(beta)cos(gamma))/sin(gamma),
                         c*sqrt( 1 + 2*cos(alpha)cos(beta)cos(gamma)
                                   - cos(alpha)^2-cos(beta)^2-cos(gamma)^2 )/sin(gamma) )
                    where alpha is the angle between axis b and c
                           beta is the angle between axis a and c
                          gamma is the angle between axis a and b
            }   
        }
        
        group {
            label { Either: }

            dimension celldm -start 1 -end 6 -type REAL {
                see  { ibrav }
                info {
                    Crystallographic constants - see the @ref ibrav variable.
                    Specify either these OR @ref A,@ref B,@ref C,@ref cosAB,@ref cosBC,@ref cosAC NOT both.
                    Only needed values (depending on "ibrav") must be specified
                    alat = @ref celldm(1) is the lattice parameter "a" (in BOHR)
                    If @ref ibrav==0, only @ref celldm(1) is used if present; 
                    cell vectors are read from card @ref CELL_PARAMETERS
                }
            }

            label { Or: }

            vargroup -type REAL {
                var A
                var B
                var C
                var cosAB
                var cosAC
                var cosBC
                see { ibrav }
                info {
                    Traditional crystallographic constants:
                    
                      a,b,c in ANGSTROM               
                      cosAB = cosine of the angle between axis a and b (gamma)
                      cosAC = cosine of the angle between axis a and c (beta)
                      cosBC = cosine of the angle between axis b and c (alpha)

                    The axis are chosen according to the value of @ref ibrav.
                    Specify either these OR @ref celldm but NOT both.
                    Only needed values (depending on @ref ibrav) must be specified.

                    The lattice parameter alat = A (in ANGSTROM ).

                    If @ref ibrav == 0, only A is used if present, and 
                    cell vectors are read from card @ref CELL_PARAMETERS.
                }
            }
        }
                                                   
        var nat -type INTEGER {
            status { REQUIRED }
            info {
                number of atoms in the unit cell (ALL atoms, except if 
                space_group is set, in which case, INEQUIVALENT atoms)
            }
        }
        
        var ntyp -type INTEGER {
            status { REQUIRED }     
            info {
                number of types of atoms in the unit cell
            }
        }

        var nbnd -type INTEGER {
            default {
                for an insulator, @ref nbnd = number of valence bands
                (@ref nbnd = # of electrons /2);
                @br for a metal, 20% more (minimum 4 more)
            }
            info {
                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
            }
        }

         var nbnd_cond -type INTEGER {
            default { nbnd_cond = @ref nbnd - # of electrons / 2 in the collinear case;
                      nbnd_cond = @ref nbnd - # of electrons in the noncollinear case.
            }
            info {
                Number of electronic states in the conduction manifold
                for a two chemical-potential calculation (@ref twochem=.true.). 
            }
        }
        
        var tot_charge -type REAL { 
            default { 0.0 }
            info {
                Total charge of the system. Useful for simulations with charged cells.
                By default the unit cell is assumed to be neutral (tot_charge=0). 
                tot_charge=+1 means one electron missing from the system,
                tot_charge=-1 means one additional electron, and so on.

                In a periodic calculation a compensating jellium background is 
                inserted to remove divergences if the cell is not neutral.
            }
        }
        
        dimension starting_charge -start 1 -end ntyp -type REAL {
            default { 0.0 }
            info {
                starting charge on atomic type 'i',
                to create starting potential with @ref startingpot = 'atomic'.
            }
        }

        var tot_magnetization -type REAL { 
            default { -10000 [unspecified] }
            info {
                Total majority spin charge - minority spin charge.
                Used to impose a specific total electronic magnetization.
                If unspecified then tot_magnetization variable is ignored and
                the amount of electronic magnetization is determined during
                the self-consistent cycle.
            }
        }
        
        dimension starting_magnetization -start 1 -end ntyp -type REAL {
            default { 0 }
            info {
                Starting spin polarization on atomic type 'i' in a spin 
                polarized (LSDA or noncollinear/spin-orbit) calculation.
                For non-constrained calculations, the allowed values 
                range between -1 (all spins down for the valence electrons
                of atom type 'i') to 1 (all spins up).
                If you expect a nonzero magnetization in your ground state,
		you MUST either specify a nonzero value for at least one
		atomic type, or constrain the magnetization using variable
		@ref tot_magnetization for LSDA, @ref constrained_magnetization
		for noncollinear/spin-orbit calculations. If you don't,
		you will get a nonmagnetic (zero magnetization) state. 
                In order to perform LSDA calculations for an antiferromagnetic
		state, define two different atomic species corresponding to
		sublattices of the same atomic type.
                
                @b {NOTE 1:} @ref starting_magnetization is ignored in most BUT NOT ALL
		cases in non-scf calculations: it is safe to keep the same
		values for the scf and subsequent non-scf calculation.
                
		@b {NOTE 2:} If you fix the magnetization with
		@ref tot_magnetization, do not specify @ref starting_magnetization.
                
		@b {NOTE 3:} In the noncollinear/spin-orbit case, starting with zero 
                starting_magnetization on all atoms imposes time reversal
                symmetry. The magnetization is never calculated and is
		set to zero (the internal variable domag is set to .FALSE.).
            }
        }

        var ecutwfc -type REAL {
            status { REQUIRED }
            info {
                kinetic energy cutoff (Ry) for wavefunctions
            }
        }
        
        var ecutrho -type REAL { 
            default { 4 * @ref ecutwfc }
            info {
                Kinetic energy cutoff (Ry) for charge density and potential
                For norm-conserving pseudopotential you should stick to the
                default value, you can reduce it by a little but it will 
                introduce noise especially on forces and stress.
                If there are ultrasoft PP, a larger value than the default is
                often desirable (ecutrho = 8 to 12 times @ref ecutwfc, typically).
                PAW datasets can often be used at 4*@ref ecutwfc, but it depends
                on the shape of augmentation charge: testing is mandatory.
                The use of gradient-corrected functional, especially in cells 
                with vacuum, or for pseudopotential without non-linear core
                correction, usually requires an higher values of ecutrho
                to be accurately converged.
            }
        }

        var ecutfock -type REAL { 
            default { ecutrho }
            info {
                Kinetic energy cutoff (Ry) for the exact exchange operator in 
                EXX type calculations. By default this is the same as @ref ecutrho
                but in some EXX calculations, a significant speed-up can be obtained
                by reducing ecutfock, at the expense of some loss in accuracy.
                Must be .gt. @ref ecutwfc. Not implemented for stress calculation
                and for US-PP and PAW pseudopotentials.
                Use with care, especially in metals where it may give raise 
                to instabilities.
            }
        }
        
        vargroup -type INTEGER {
            var nr1
            var nr2
            var nr3
            info {
                Three-dimensional FFT mesh (hard grid) for charge
                density (and scf potential). If not specified
                the grid is calculated based on the cutoff for
                charge density (see also @ref ecutrho)
                Note: you must specify all three dimensions for this setting to
                be used.
            }
        }

        vargroup -type INTEGER {
            var nr1s
            var nr2s
            var nr3s
            info {
                Three-dimensional mesh for wavefunction FFT and for the smooth
                part of charge density ( smooth grid ).
                Coincides with @ref nr1, @ref nr2, @ref nr3 if @ref ecutrho = 4 * ecutwfc ( default )
                Note: you must specify all three dimensions for this setting to
                be used.
            }
        }
        
        var nosym -type LOGICAL { 
            default { .FALSE. }
            info {
                if (.TRUE.) symmetry is not used. Consequences:
                
                - if a list of k points is provided in input, it is used
                  "as is": symmetry-inequivalent k-points are not generated,
                  and the charge density is not symmetrized;

                - if a uniform (Monkhorst-Pack) k-point grid is provided in 
                  input, it is expanded to cover the entire Brillouin Zone,
                  irrespective of the crystal symmetry. 
                  Time reversal symmetry is assumed so k and -k are considered
                  as equivalent unless @ref noinv=.true. is specified.

                Do not use this option unless you know exactly what you want
                and what you get. May be useful in the following cases:
                - in low-symmetry large cells, if you cannot afford a k-point
                  grid with the correct symmetry
                - in MD simulations
                - in calculations for isolated atoms
            }
        }

        var nosym_evc -type LOGICAL { 
            default { .FALSE. }
            info {
                if (.TRUE.) symmetry is not used, and k points are 
                forced to have the symmetry of the Bravais lattice; 
                an automatically generated Monkhorst-Pack grid will contain
                all points of the grid over the entire Brillouin Zone,
                plus the points rotated by the symmetries of the Bravais 
                lattice which were not in the original grid. The same 
                applies if a k-point list is provided in input instead
                of a Monkhorst-Pack grid. Time reversal symmetry is assumed
                so k and -k are equivalent unless @ref noinv=.true. is specified.
                This option differs from @ref nosym because it forces k-points
                in all cases to have the full symmetry of the Bravais lattice
                (not all uniform grids have such property!)
            }
        }

        var noinv -type LOGICAL { 
            default { .FALSE. }
            info {
                if (.TRUE.) disable the usage of k => -k symmetry 
                (time reversal) in k-point generation
            }
        }

        var no_t_rev -type LOGICAL { 
            default { .FALSE. }
            info {
                if (.TRUE.) disable the usage of magnetic symmetry operations
                that consist in a rotation + time reversal. 
            }
        }

       var force_symmorphic -type LOGICAL { 
           default { .FALSE. }
           info {
               if (.TRUE.) force the symmetry group to be symmorphic by disabling
               symmetry operations having an associated fractionary translation
          }
      }

       var use_all_frac -type LOGICAL { 
           default { .FALSE. }
           info {
               if (.FALSE.) force real-space FFT grids to be commensurate with
               fractionary translations of non-symmorphic symmetry operations,
               if present (e.g.: if a fractional translation (0,0,c/4) exists, 
               the FFT dimension along the c axis must be multiple of 4).
               if (.TRUE.) do not impose any constraints to FFT grids, even in
               the presence of non-symmorphic symmetry operations. 
               BEWARE: use_all_frac=.TRUE. may lead to wrong results for
               hybrid functionals and phonon calculations. Both cases use 
               symmetrization in real space that works for non-symmorphic 
               operations only if the real-space FFT grids are commensurate.
          }
      }

        var occupations -type CHARACTER {
            options {
                info { Available options are: }
                
                opt -val 'smearing' {
                    gaussian smearing for metals; 
                    see variables @ref smearing and @ref degauss
                }
                opt -val 'tetrahedra' {
                    Tetrahedron method, Bloechl's version:
                    P.E. Bloechl, PRB 49, 16223 (1994)
                    Requires uniform grid of k-points, to be
                    automatically generated (see card @ref K_POINTS).
                    Well suited for calculation of DOS, 
                    less so (because not variational) for
                    force/optimization/dynamics calculations.
                }
                opt -val 'tetrahedra_lin' {
                    Original linear tetrahedron method.
                    To be used only as a reference;
                    the optimized tetrahedron method is more efficient.
                }
                opt -val 'tetrahedra_opt' {
                    Optimized tetrahedron method:
                    see M. Kawamura, PRB 89, 094515 (2014).
                    Can be used for phonon calculations as well.
                }
                opt -val 'fixed' {
                    for insulators with a gap
                }
                opt -val 'from_input' {
                    The occupation are read from input file,
                    card @ref OCCUPATIONS. Option valid only for a
                    single k-point, requires @ref nbnd to be set 
                    in input. Occupations should be consistent 
                    with the value of @ref tot_charge.
                }
            }
        }

        var one_atom_occupations -type LOGICAL { 
            default { .FALSE. }
            info {
               This flag is used for isolated atoms (@ref nat=1) together with 
               @ref occupations='from_input'. If it is .TRUE., the wavefunctions 
               are ordered as the atomic starting wavefunctions, independently 
               from their eigenvalue. The occupations indicate which atomic 
               states are filled.
                
               The order of the states is written inside the UPF pseudopotential file.
               In the scalar relativistic case: 
               S -> l=0, m=0 
               P -> l=1, z, x, y
               D -> l=2, r^2-3z^2, xz, yz, xy, x^2-y^2

               In the noncollinear magnetic case (with or without spin-orbit), 
               each group of states is doubled. For instance:
               P -> l=1, z, x, y for spin up, l=1, z, x, y for spin down.
               Up and down is relative to the direction of the starting
               magnetization.
                
               In the case with spin-orbit and time-reversal 
               (@ref starting_magnetization=0.0) the atomic wavefunctions are 
               radial functions multiplied by spin-angle functions.
               For instance:
               P -> l=1, j=1/2, m_j=-1/2,1/2. l=1, j=3/2, 
                    m_j=-3/2, -1/2, 1/2, 3/2.

               In the magnetic case with spin-orbit the atomic wavefunctions
               can be forced to be spin-angle functions by setting
               @ref starting_spin_angle to .TRUE..
            }
        }

        var starting_spin_angle -type LOGICAL { 
            default { .FALSE. }
            info {
               In the spin-orbit case when @ref domag=.TRUE., by default,
               the starting wavefunctions are initialized as in scalar 
               relativistic noncollinear case without spin-orbit.

               By setting @ref starting_spin_angle=.TRUE. this behaviour can
               be changed and the initial wavefunctions are radial 
               functions multiplied by spin-angle functions. 

               When @ref domag=.FALSE. the initial wavefunctions are always
               radial functions multiplied by spin-angle functions 
               independently from this flag.

               When @ref lspinorb is .FALSE. this flag is not used.
            }
        }

        var degauss_cond -type REAL {
            default { 0.D0 Ry }
            info {
                value of the gaussian spreading (Ry) for brillouin-zone
                integration in the conduction manifold in a two-chemical
                potential calculation (@ref twochem=.true.).
            }
        }

        var nelec_cond -type REAL {
            default { 0.D0 }
            info {
                Number of electrons placed in the conduction manifold in a two-chemical 
                potential calculation (@ref twochem=.true.). Of the total # of 
                electrons nelec, nelec-nelec_cond will occupy the valence 
                manifold and nelec_cond will be constrained in the conduction manifold. 
            }
        }
 
        var degauss -type REAL { 
            default { 0.D0 Ry }
            info {
                value of the gaussian spreading (Ry) for brillouin-zone
                integration in metals.
            }
        }
       
        var smearing -type CHARACTER {
            default { 'gaussian' }

            options {
                info {
                    Available options are:
                }
                
                opt -val {'gaussian', 'gauss'} {
                    ordinary Gaussian spreading (Default)
                }
                    
                opt -val {'methfessel-paxton', 'm-p', 'mp'} {
                    Methfessel-Paxton first-order spreading
                    (see PRB 40, 3616 (1989)).
                }

                opt -val {'marzari-vanderbilt', 'cold', 'm-v', 'mv'} {
                    Marzari-Vanderbilt-DeVita-Payne cold smearing
                    (see PRL 82, 3296 (1999))
                }
                    
                opt -val {'fermi-dirac', 'f-d', 'fd'} {
                    smearing with Fermi-Dirac function
                }
            }
        }
        
        var nspin -type INTEGER {
            default { 1 }
            info {
                nspin = 1 :  non-polarized calculation (default)
                
                nspin = 2 :  spin-polarized calculation, LSDA
                             (magnetization along z axis)

                nspin = 4 :  spin-polarized calculation, noncollinear
                             (magnetization in generic direction)
                             DO NOT specify @ref nspin in this case;
                             specify @ref noncolin=.TRUE. instead
            }
        }

        var sic_gamma -type REAL {
            default { 0 }
            info {
                Strength of the gammaDFT potential.
            }
        }

        var pol_type -type CHARACTER {
            options {
                info {
                    Type of polaron in gammaDFT.
                }
                opt -val 'e' { electron polaron }
                opt -val 'h' { hole polaron }
            }
        }

        var sic_energy -type LOGICAL {
            default { .false. }
            info {
                Enable the calculation of the total energy in gammaDFT. When .true., 
                a preliminary calculation is performed to calculate the electron density 
                in the absence of the polaron. When .false., the total energy printed in 
                output should not be considered. For structural relaxations, it is 
                recommended to use .false. to avoid doubling the computational cost.
            }
        }

        var sci_vb -type REAL {
            default { 0 }
            info {
                Valence band shift (in eV) through self-consistent 
                scissor operator. When performing gammaDFT calculations 
                of polarons, the polaron level is not shifted.
            }
        }

        var sci_cb -type REAL {
            default { 0 }
            info {
                Conduction band band shift (in eV) through self-consistent 
		scissor operator. When performing gammaDFT calculations 
                of polarons, the polaron level is not shifted.
            }
        }

        var noncolin -type LOGICAL {
            default { .false. }
            info {
                if .true. the program will perform a noncollinear calculation.
            }
        }
        
        var ecfixed -type REAL { default { 0.0 }; see { q2sigma } }         
        var qcutz   -type REAL { default { 0.0 }; see { q2sigma } }         
        var q2sigma -type REAL { 
            default { 0.1 } 
            info { 
                ecfixed, qcutz, q2sigma:  parameters for modified functional to be 
                used in variable-cell molecular dynamics (or in stress calculation).
                "ecfixed" is the value (in Rydberg) of the constant-cutoff;
                "qcutz" and "q2sigma" are the height and the width (in Rydberg)
                of the energy step for reciprocal vectors whose square modulus
                is greater than "ecfixed". In the kinetic energy, G^2 is
                replaced by G^2 + qcutz * (1 + erf ( (G^2 - ecfixed)/q2sigma) )
                See: M. Bernasconi et al, J. Phys. Chem. Solids 56, 501 (1995),
                doi:10.1016/0022-3697(94)00228-2
            }
        }
        
        var input_dft -type CHARACTER {
            default { read from pseudopotential files } 
            info {
                   Exchange-correlation functional: eg 'PBE', 'BLYP' etc
                   See Modules/funct.f90 for allowed values. 
                   Overrides the value read from pseudopotential files.
                   Use with care and if you know what you are doing!
            }
        }

        var ace -type LOGICAL {
            default {true } 
            info {
                Use Adaptively Compressed Exchange operator as in 
                Lin Lin, J. Chem. Theory Comput. 2016, 12, 2242--2249, doi:10.1021/acs.jctc.6b00092
                
                Set to false to use standard Exchange (much slower)
            }
        }


        var exx_fraction -type REAL { 
            default { it depends on the specified functional }
            info {
                Fraction of EXX for hybrid functional calculations. In the case of 
                @ref input_dft='PBE0', the default value is 0.25, while for @ref input_dft='B3LYP'
                the @ref exx_fraction default value is 0.20.
            }
        }

        var screening_parameter -type REAL {
            default {0.106}
            info {
                screening_parameter for HSE like hybrid functionals. 
                For more information, see:
                J. Chem. Phys. 118, 8207 (2003), doi:10.1063/1.1564060
                J. Chem. Phys. 124, 219906 (2006), doi:10.1063/1.2204597
            }
        }


        var exxdiv_treatment -type CHARACTER {
            default {'gygi-baldereschi'}
            options {
                info {
                    Specific for EXX. It selects the kind of approach to be used
                    for treating the Coulomb potential divergencies at small q vectors.
                }

                opt -val 'gygi-baldereschi' { appropriate for cubic and quasi-cubic supercells }
                
                opt -val 'vcut_spherical' { appropriate for cubic and quasi-cubic supercells }

                opt -val 'vcut_ws' { appropriate for strongly anisotropic supercells, see also @ref ecutvcut. }
                
                opt -val 'none' { sets Coulomb potential at G,q=0 to 0.0 (required for GAU-PBE) }
            }
        }

        var x_gamma_extrapolation -type LOGICAL {
            default {.true.}
            info {
                Specific for EXX. If .true., extrapolate the G=0 term of the
                potential (see README in examples/EXX_example for more)
                Set this to .false. for GAU-PBE.
            }
         }

        var ecutvcut -type REAL {
            default { 0.0 Ry }
            see { exxdiv_treatment } 
            info {
                Reciprocal space cutoff for correcting Coulomb potential
                divergencies at small q vectors.
            }
        }
        
        vargroup -type INTEGER {
            var nqx1
            var nqx2
            var nqx3
            info {
                Three-dimensional mesh for q (k1-k2) sampling of 
                the Fock operator (EXX). Can be smaller than 
                the number of k-points.

                Currently this defaults to the size of the k-point mesh used.
                In QE =< 5.0.2 it defaulted to nqx1=nqx2=nqx3=1.
            }
        }

        var localization_thr -type REAL {
                default {0.0 } 
                info {  
                       Overlap threshold over which the exchange integral over a pair of localized orbitals 
                       is included in the evaluation of EXX operator. Any value greater than 0.0 triggers 
                       the SCDM localization and the evaluation on EXX using the localized orbitals.
                       Very small value of the threshold should yield the same result as the default EXX 
                       evaluation } 
        } 

        multidimension Hubbard_occ -start 1,1 -end ntyp,3 -indexes ityp,i -type REAL {
            default { read from pseudopotentials }
            info {
                Hubbard occupations is the number of electrons in the
                Hubbard manifold. By default they are initialized by 
                reading the occupations from pseudopotentials. If specified
                from the input, then the values read from the pseudopotentials
                will be overwritten.
                The second index of the Hubbard_occ array corresponds to the
                Hubbard manifold number. It is possible to specify up to
                three Hubbard manifolds per Hubbard atom. However, if you want
                to specify three manifolds then the second and the third manifolds
                will be considered as one effective manifold (see Doc/Hubbard_input.pdf)

                Note: Hubbard_occ cannot be used together with fully-relativistic pseudopotentials
                (i.e. when noncolin=.true. and lspinorb=.true.) since this variable does not
                allow to distinguish between the occupied and unoccupied channels (this is 
                needed when determining the atomic orbital offsets).
            }
        }
        dimension Hubbard_alpha -start 1 -end ntyp -type REAL { 
            default { 0.D0 for all species }
            info {
                Hubbard_alpha(i) is the perturbation (on atom i, in eV)
                used to compute U (and V) with the linear-response method of
                Cococcioni and de Gironcoli, PRB 71, 035105 (2005)
                (only for DFT+U or DFT+U+V).
                
                Note: Hubbard U and V can be computed using the HP code
                which is based on density-functional perturbation theory,
                and it gives exactly the same result as the method of 
                Cococcioni and de Gironcoli.
            }
        }
        dimension Hubbard_beta -start 1 -end ntyp -type REAL { 
            default { 0.D0 for all species }
            info {
                Hubbard_beta(i) is the perturbation (on atom i, in eV)
                used to compute J0 with the linear-response method of
                Cococcioni and de Gironcoli, PRB 71, 035105 (2005)
                (only for DFT+U or DFT+U+V). See also 
                PRB 84, 115108 (2011).
            }
        }
        
        multidimension  starting_ns_eigenvalue  -indexes m,ispin,ityp -start 1,1,1 -end 2*lmax+1,nspin\ or\ npol,ntyp  -type REAL { 
            default { -1.d0 that means NOT SET }
            info {
                In the first iteration of an DFT+U run it overwrites
                the m-th eigenvalue of the ns occupation matrix for the
                ispin component of atomic species ityp. 
                For the noncollinear case, the ispin index runs up to npol=2
                The value lmax  is given by the maximum angular momentum 
                number to which the Hubbard U is applied. 
                Leave unchanged eigenvalues that are not set. 
                This is useful to suggest the desired orbital occupations 
                when the default choice takes another path.
            }
        } 

        var dmft -type LOGICAL { 
            default { .FALSE. }
            status {
                Requires compilation with hdf5 support
            }
            info { 
                If true, nscf calculation will exit in restart mode, scf calculation
                will restart from there if DMFT updates are provided as hdf5 archive.
                Scf calculation should be used only with @ref electron_maxstep = 1.
                @ref K_POINTS have to be identical and given explicitly with @ref nosym.
            }
        }

        var dmft_prefix -type CHARACTER { 
            default { @ref prefix }
            info {
                prepended to hdf5 archive: dmft_prefix.h5

                DMFT update should be provided in group/dataset as:
                - dft_misc_input/band_window with dimension [1, number of k-points, 2 (real + complex)] 
                - dft_update/delta_N with dimension [number of k-points, number of correlated orbitals,
                number of correlated orbitals, 2 (real + complex)]
            }
        }

        var ensemble_energies -type LOGICAL {
            default { .false. }
            info {
                If @ref ensemble_energies = .true., an ensemble of xc energies
                is calculated non-selfconsistently for perturbed
                exchange-enhancement factors and LDA vs. PBE correlation
                ratios after each converged electronic ground state
                calculation.

                Ensemble energies can be analyzed with the 'bee' utility
                included with libbeef.

                Requires linking against libbeef.
                @ref input_dft must be set to a BEEF-type functional
                (e.g. input_dft = 'BEEF-vdW')
            }
        }

        var edir -type INTEGER {
            info {
                The direction of the electric field or dipole correction is
                parallel to the bg(:,edir) reciprocal lattice vector, so the
                potential is constant in planes defined by FFT grid points;
                @ref edir = 1, 2 or 3. Used only if @ref tefield is .TRUE.
            }
        }
        
        var emaxpos -type REAL { 
            default { 0.5D0 }
            info {
                Position of the maximum of the saw-like potential along crystal
                axis @ref edir, within the  unit cell (see below), 0 < emaxpos < 1
                Used only if @ref tefield is .TRUE.
            }
        }
        
        var eopreg -type REAL {
            default { 0.1D0 }
            info {
                Zone in the unit cell where the saw-like potential decreases.
                ( see below, 0 < eopreg < 1 ). Used only if @ref tefield is .TRUE.
            }
        }

        var eamp -type REAL { 
            default { 0.001 a.u. }
            info {
                Amplitude of the electric field, in ***Hartree*** a.u.;
                1 a.u. = 51.4220632*10^10 V/m. Used only if @ref tefield==.TRUE.
                The saw-like potential increases with slope @ref eamp in the
                region from (@ref emaxpos+@ref eopreg-1) to (@ref emaxpos), then decreases
                to 0 until (@ref emaxpos+@ref eopreg), in units of the crystal
                vector @ref edir. Important: the change of slope of this
                potential must be located in the empty region, or else
                unphysical forces will result.
            }
        }
    
        dimension angle1 -start 1 -end ntyp -type REAL {
            info {
                The angle expressed in degrees between the initial
                magnetization and the z-axis. For noncollinear calculations
                only; index i runs over the atom types.
            }
        }

        dimension angle2 -start 1 -end ntyp -type REAL {
            info {
                The angle expressed in degrees between the projection
                of the initial magnetization on x-y plane and the x-axis.
                For noncollinear calculations only.
            }
        }
        
        var lforcet -type LOGICAL {
            info {
                When starting a non collinear calculation using an existing density
                file from a collinear lsda calculation assumes previous density points in 
                @i z direction and rotates it in the direction described by @ref angle1 and 
                @ref angle2 variables for atomic type 1
            } 
        } 

        var constrained_magnetization -type CHARACTER { 
            see { lambda, fixed_magnetization }
            default { 'none' }
            options {
                info {
                    Used to perform constrained calculations in magnetic systems.
                    Currently available choices:
                }

                opt -val 'none' {
                         no constraint
                }
                
                opt -val 'total' {
                         total magnetization is constrained by
                         adding a penalty functional to the total energy:
                    
                         LAMBDA * SUM_{i} ( magnetization(i) - fixed_magnetization(i) )**2
                        
                         where the sum over i runs over the three components of
                         the magnetization. Lambda is a real number (see below).
                         Noncolinear case only. Use @ref tot_magnetization for LSDA
                }
                
                opt -val 'atomic' {
                         atomic magnetization are constrained to the defined
                         starting magnetization adding a penalty:

                         LAMBDA * SUM_{i,itype} ( magnetic_moment(i,itype) - mcons(i,itype) )**2
                        
                         where i runs over the cartesian components (or just z 
                         in the collinear case) and itype over the types (1-ntype).
                         mcons(:,:) array is defined from starting_magnetization,
                         (also from angle1, angle2 in the noncollinear case).
                         lambda is a real number
                }
                opt -val {'total direction'} {
                          the angle theta of the total magnetization
                          with the z axis (theta = fixed_magnetization(3))  
                          is constrained: 

                          LAMBDA * ( arccos(magnetization(3)/mag_tot) - theta )**2

                          where mag_tot is the modulus of the total magnetization.
                }
                opt -val {'atomic direction'} {
                          not all the components of the atomic
                          magnetic moment are constrained but only the cosine
                          of angle1, and the penalty functional is:

                          LAMBDA * SUM_{itype} ( mag_mom(3,itype)/mag_mom_tot - cos(angle1(ityp)) )**2
                }
                info {
                    N.B.: symmetrization may prevent to reach the desired orientation
                    of the magnetization. Try not to start with very highly symmetric
                    configurations or use the nosym flag (only as a last remedy)
                }
            }
        }
        
        dimension fixed_magnetization -start 1 -end 3 -type REAL { 
            see { constrained_magnetization }
            default { 0.d0 }
            info {
                total magnetization vector (x,y,z components) to be kept
                fixed when @ref constrained_magnetization=='total'
            }
        }
        
        var lambda -type REAL {
            see { constrained_magnetization }
            default { 1.d0 }
            info {
                parameter used for constrained_magnetization calculations
                N.B.: if the scf calculation does not converge, try to reduce lambda 
                      to obtain convergence, then restart the run with a larger lambda
            }
        }
        
        var report -type INTEGER {
            default { -1 }
            info {
	        determines when atomic magnetic moments are printed on output:
                @b {report = 0}  never
                @b {report =-1}  at the beginning of the scf and at convergence
		@b {report = N}  as -1, plus every N scf iterations
            }
        }
        
        var lspinorb -type LOGICAL {
            info {
                if .TRUE. the noncollinear code can use a pseudopotential with
                spin-orbit.
            }
        }
        
        var assume_isolated -type CHARACTER { 
            default { 'none' }
            options {
                info { 
                    Used to perform calculation assuming the system to be
                    isolated (a molecule or a cluster in a 3D supercell).
                    
                    Currently available choices:
                }

                opt -val 'none' {
                    (default): regular periodic calculation w/o any correction.
                }
                opt -val {'makov-payne', 'm-p', 'mp'} {
                    the Makov-Payne correction to the 
                    total energy is computed. An estimate of the vacuum 
                    level is also calculated so that eigenvalues can be 
                    properly aligned. ONLY FOR CUBIC SYSTEMS (@ref ibrav=1,2,3).
                    Theory: G.Makov, and M.C.Payne, 
                         "Periodic boundary conditions in ab initio
                         calculations" , PRB 51, 4014 (1995).
                }

                opt -val {'martyna-tuckerman', 'm-t', 'mt'} {
                    Martyna-Tuckerman correction
                    to both total energy and scf potential. Adapted from:
                    G.J. Martyna, and M.E. Tuckerman,
                    "A reciprocal space based method for treating long
                    range interactions in ab-initio and force-field-based
                    calculation in clusters", J. Chem. Phys. 110, 2810 (1999),
                    doi:10.1063/1.477923.
                }

                opt -val 'esm' {
                    Effective Screening Medium Method.
                    For polarized or charged slab calculation, embeds
                    the simulation cell within an effective semi-
                    infinite medium in the perpendicular direction
                    (along z). Embedding regions can be vacuum or
                    semi-infinite metal electrodes (use @ref esm_bc to
                    choose boundary conditions). If between two
                    electrodes, an optional electric field
                    (@ref esm_efield) may be applied. Method described in
                    M. Otani and O. Sugino, "First-principles calculations
                    of charged surfaces and interfaces: A plane-wave
                    nonrepeated slab approach", PRB 73, 115407 (2006).

                    NB:
                       - Two dimensional (xy plane) average charge density
                         and electrostatic potentials are printed out to
                         'prefix.esm1'.

                       - Requires cell with a_3 lattice vector along z,
                         normal to the xy plane, with the slab centered
                         around z=0.

                       - For bc2 with an electric field and bc3 boundary
                         conditions, the inversion symmetry along z-direction
                         is automatically eliminated.

                       - In case of calculation='vc-relax', use
                         @ref cell_dofree='2Dxy' or other parameters so that
                         c-vector along z-axis should not be moved.

                    See @ref esm_bc, @ref esm_efield, @ref esm_w, @ref esm_nfit.
                }
                opt -val '2D' {
                    Truncation of the Coulomb interaction in the z direction 
                    for structures periodic in the x-y plane. Total energy, 
                    forces and stresses are computed in a two-dimensional framework. 
                    Linear-response calculations () done on top of a self-consistent 
                    calculation with this flag will automatically be performed in 
                    the 2D framework as well. Please refer to:
                    Sohier, T., Calandra, M., & Mauri, F. (2017), "Density functional 
                    perturbation theory for gated two-dimensional heterostructures:
                    Theoretical developments and application to flexural phonons in graphene",
                    PRB, 96, 075448 (2017).
                    
                    NB:
                       - The length of the unit-cell along the z direction should
                         be larger than twice the thickness of the 2D material 
                         (including electrons). A reasonable estimate for a 
                         layer's thickness could be the interlayer distance in the 
                         corresponding layered bulk material. Otherwise,  
                         the atomic thickness + 10 bohr should be a safe estimate. 
                         There is also a lower limit of 20 bohr imposed by the cutoff 
                         radius used to read pseudopotentials (see read_pseudo.f90 in Modules).

                       - As for ESM above, only in-plane stresses make sense and one
                         should use @ref cell_dofree= '2Dxy' in a @b vc-relax calculation.
                }
            }
        }

        var esm_bc -type CHARACTER {
            see { assume_isolated }
            default { 'pbc' }
            options {
                info {
                    If @ref assume_isolated = 'esm', determines the boundary
                    conditions used for either side of the slab.
                    
                    Currently available choices:
                }

                opt -val 'pbc' { (default): regular periodic calculation (no ESM). }

                opt -val 'bc1' { Vacuum-slab-vacuum (open boundary conditions). }

                opt -val 'bc2' {
                    Metal-slab-metal (dual electrode configuration).
                    See also @ref esm_efield.
                }
                opt -val 'bc3' { Vacuum-slab-metal }
            }
        }

        var esm_w -type REAL {
            see { assume_isolated }
            default { 0.d0 }
            info {
                If @ref assume_isolated = 'esm', determines the position offset
                [in a.u.] of the start of the effective screening region,
                measured relative to the cell edge. (ESM region begins at
                z = +/- [L_z/2 + esm_w] ).
            }
        }

        var esm_efield -type REAL {
            see { assume_isolated }
            default { 0.d0 }
            info {
                If @ref assume_isolated = 'esm' and @ref esm_bc = 'bc2', gives the
                magnitude of the electric field [Ry/a.u.] to be applied
                between semi-infinite ESM electrodes.
            }
        }

        var esm_nfit -type INTEGER {
            see { assume_isolated }
            default { 4 }
            info {
                If @ref assume_isolated = 'esm', gives the number of z-grid points
                for the polynomial fit along the cell edge.
            }
        }

        var lgcscf -type LOGICAL {
            default { .FALSE. }
            info {
                If .TRUE. perform a constant bias potential (constant-mu) calculation
                with Grand-Canonical SCF. (JCP 146, 114104 (2017), R.Sundararaman, et al.)

                NB:
                - The total energy displayed in output includes the potentiostat
                  contribution (-mu*N).
                - @ref assume_isolated = 'esm' and @ref esm_bc = 'bc2' or 'bc3' must be set
                  in @ref SYSTEM namelist.
                - ESM-RISM is also supported (@ref assume_isolated = 'esm' and @ref esm_bc = 'bc1'
                  and @ref trism = .TRUE.).
                - @ref mixing_mode has to be 'TF' or 'local-TF', also its default is 'TF.'
                - The default of @ref mixing_beta is 0.1 with ESM-RISM, 0.2 without ESM-RISM.
                - The default of @ref diago_thr_init is 1.D-5.
                - @ref diago_full_acc is always .TRUE. .
                - @ref diago_rmm_conv is always .TRUE. .
            }
        }

        var gcscf_mu -type REAL {
            status { REQUIRED }
            info {
                The target Fermi energy (eV) of GC-SCF. One can start 
                with appropriate total charge of the system by giving @ref tot_charge .
            }
        }

        var gcscf_conv_thr -type REAL {
            default { 1.D-2 }
            info {
                Convergence threshold of Fermi energy (eV) for GC-SCF.
            }
        }

        var gcscf_beta -type REAL { 
            default { 0.05D0 }
            info {
                Mixing factor for GC-SCF.
                Larger values are recommended,
                if systems with small DOS on Fermi surface as graphite.
            }
        }

         var vdw_corr -type CHARACTER {
             default { 'none' }
             see {
                 london_s6, london_rcut, london_c6, london_rvdw, 
                 dftd3_version, dftd3_threebody, ts_vdw_econv_thr, ts_vdw_isolated, xdm_a1, xdm_a2
             }
             options {
                 info {
                     Type of Van der Waals correction. Allowed values:
                 }

                 opt -val {'grimme-d2', 'Grimme-D2', 'DFT-D', 'dft-d'} {
                     Semiempirical Grimme's DFT-D2. Optional variables:
                     @ref london_s6, @ref london_rcut, @ref london_c6, @ref london_rvdw
                     S. Grimme, J. Comp. Chem. 27, 1787 (2006), doi:10.1002/jcc.20495
                     V. Barone et al., J. Comp. Chem. 30, 934 (2009), doi:10.1002/jcc.21112
                 }

                 opt -val {'grimme-d3', 'Grimme-D3', 'DFT-D3', 'dft-d3' } {
                     Semiempirical Grimme's DFT-D3. Optional variables:
                     @ref dftd3_version, @ref dftd3_threebody
                     S. Grimme et al, J. Chem. Phys 132, 154104 (2010), doi:10.1063/1.3382344
                 }

                 opt -val {'TS', 'ts', 'ts-vdw', 'ts-vdW', 'tkatchenko-scheffler'} {
                     Tkatchenko-Scheffler dispersion corrections with first-principle derived
                     C6 coefficients.
                     Optional variables: @ref ts_vdw_econv_thr, @ref ts_vdw_isolated
                     See A. Tkatchenko and M. Scheffler, PRL 102, 073005 (2009).
                 }

                 opt -val {'MBD', 'mbd', 'many-body-dispersion', 'mbd_vdw'} {
                     Many-body dipersion (MBD) correction to long-range interactions.
                     Optional variables: @ref ts_vdw_isolated
                     A. Ambrosetti, A. M. Reilly, R. A. DiStasio, A. Tkatchenko, J. Chem. Phys. 140
                     18A508 (2014).
                 }

                 opt -val {'XDM', 'xdm'} {
                     Exchange-hole dipole-moment model. Optional variables: @ref xdm_a1, @ref xdm_a2
                     A. D. Becke et al., J. Chem. Phys. 127, 154108 (2007), doi:10.1063/1.2795701
                     A. Otero de la Roza et al., J. Chem. Phys. 136, 174109 (2012),
                     doi:10.1063/1.4705760
                 }
                 info { Note that non-local functionals (eg vdw-DF) are NOT specified here but in @ref input_dft }
             }
         }

         var london -type LOGICAL {
           default { .FALSE. }
           status {
               OBSOLESCENT, same as @ref vdw_corr='DFT-D'
           }
         }

         var london_s6 -type REAL {
           default { 0.75 }
           info {
               global scaling parameter for DFT-D. Default is good for PBE.
           }
         }
         dimension london_c6 -type REAL -start 1 -end ntyp {
           default { standard Grimme-D2 values }
           info {
               atomic C6 coefficient of each atom type

               ( if not specified default values from S. Grimme, J. Comp. Chem. 27, 1787 (2006),
                 doi:10.1002/jcc.20495 are used; see file Modules/mm_dispersion.f90 )
           }
         }
         dimension london_rvdw -type REAL -start 1 -end ntyp {
           default { standard Grimme-D2 values }
           info {
               atomic vdw radii of each atom type

               ( if not specified default values from S. Grimme, J. Comp. Chem. 27, 1787 (2006),
                 doi:10.1002/jcc.20495 are used; see file Modules/mm_dispersion.f90 )
           }
         }
         var london_rcut -type REAL {
           default { 200 }
           info {
               cutoff radius (a.u.) for dispersion interactions
           }
         }
         var dftd3_version -type integer {
             default { 3 }
             options {
                 info {
                     Version of Grimme implementation of Grimme-D3:
                 }
                 opt -val {dftd3_version = 2} {
                     Original Grimme-D2 parametrization
                 }
                 opt -val {dftd3_version = 3} {
                     Grimme-D3 (zero damping)
                 }
                 opt -val {dftd3_version = 4} {
                     Grimme-D3 (BJ damping)
                 }
                 opt -val {dftd3_version = 5} {
                     Grimme-D3M (zero damping)
                 }
                 opt -val {dftd3_version = 6} {
                     Grimme-D3M (BJ damping)
                 }
                 
                 info {
                     NOTE: not all functionals are parametrized.
                 }
             }
         }
         var dftd3_threebody -type LOGICAL {
           default { TRUE }
           info {
               Turn three-body terms in Grimme-D3 on. If .false. two-body contributions 
               only are computed, using two-body parameters of Grimme-D3.
               If dftd3_version=2, three-body contribution is always disabled.
           }
         }
        var ts_vdw_econv_thr -type REAL {
          default { 1.D-6 }
          info {
             Optional: controls the convergence of the vdW energy (and forces). The default value
             is a safe choice, likely too safe, but you do not gain much in increasing it
          }
        }

        var ts_vdw_isolated -type LOGICAL {
          default { .FALSE. }
          info {
             Optional: set it to .TRUE. when computing the Tkatchenko-Scheffler vdW energy or the
             Many-Body dispersion (MBD) energy for an isolated (non-periodic) system.
          }
        }

         var xdm -type LOGICAL {
             default { .FALSE. }
             status {
               OBSOLESCENT, same as @ref vdw_corr='xdm'
             }
         }

         var xdm_a1 -type REAL {
           default { 0.6836 }
           info {
               Damping function parameter a1 (adimensional). It is NOT necessary to give
               a value if the functional is one of B86bPBE, PW86PBE, PBE, BLYP. For functionals
               in this list, the coefficients are given in:
                  http://schooner.chem.dal.ca/wiki/XDM
                  A. Otero de la Roza, E. R. Johnson, J. Chem. Phys. 138, 204109 (2013),
                  doi:10.1063/1.4705760
           }
         }
         var xdm_a2 -type REAL {
           default { 1.5045 }
           info {
               Damping function parameter a2 (angstrom). It is NOT necessary to give
               a value if the functional is one of B86bPBE, PW86PBE, PBE, BLYP. For functionals
               in this list, the coefficients are given in:
                  http://schooner.chem.dal.ca/wiki/XDM
                  A. Otero de la Roza, E. R. Johnson, J. Chem. Phys. 138, 204109 (2013),
                  doi:10.1063/1.4705760
           }
         }

         var space_group -type INTEGER {
             default { 0 }
             info {
                 The number of the space group of the crystal, as given
                 in the International Tables of Crystallography A (ITA).
                 This allows to give in input only the inequivalent atomic 
                 positions. The positions of all the symmetry equivalent atoms
                 are calculated by the code. Used only when the atomic positions
                 are of type crystal_sg. See also @ref uniqueb,
                 @ref origin_choice, @ref rhombohedral
             }
         }

         var uniqueb -type LOGICAL {
             default { .FALSE. }
             info {
                  Used only for monoclinic lattices. If .TRUE. the b
                  unique @ref ibrav (-12 or -13) are used, and symmetry 
                  equivalent positions are chosen assuming that the
                  twofold axis or the mirror normal is parallel to the
                  b axis. If .FALSE. it is parallel to the c axis.
             }
         }

         var origin_choice -type INTEGER {
             default { 1 }
             info {
                  Used only for space groups that in the ITA allow 
                  the use of two different origins. @ref origin_choice=1,
                  means the first origin, while @ref origin_choice=2 is the
                  second origin.
             }
         }
    
         var rhombohedral -type LOGICAL {
             default { .TRUE. }
             info {
                  Used only for rhombohedral space groups. 
                  When .TRUE. the coordinates of the inequivalent atoms are
                  given with respect to the rhombohedral axes, when .FALSE.
                  the coordinates of the inequivalent atoms are given with
                  respect to the hexagonal axes. They are converted internally
                  to the rhombohedral axes and @ref ibrav=5 is used in both cases.
             }
         }
    
        group {
            label { variables used only if @ref gate = .TRUE. }

            var zgate -type REAL {
                default { 0.5 }
                info {
                    used only if @ref gate = .TRUE.
                    Specifies the position of the charged plate which represents
                    the counter charge in doped systems (@ref tot_charge .ne. 0).
                    In units of the unit cell length in @i z direction, @ref zgate in ]0,1[
                    Details of the gate potential can be found in
                    T. Brumme, M. Calandra, F. Mauri; PRB 89, 245406 (2014).
                }
            }

            var relaxz -type LOGICAL {
                default { .FALSE. }
                info {
                    used only if @ref gate = .TRUE.
                    Allows the relaxation of the system towards the charged plate.
                    Use carefully and utilize either a layer of fixed atoms or a
                    potential barrier (@ref block=.TRUE.) to avoid the atoms moving to
                    the position of the plate or the dipole of the dipole
                    correction (@ref dipfield=.TRUE.).
                }
            }

            var block -type LOGICAL {
                default { .FALSE. }
                info {
                    used only if @ref gate = .TRUE.
                    Adds a potential barrier to the total potential seen by the
                    electrons to mimic a dielectric in field effect configuration
                    and/or to avoid electrons spilling into the vacuum region for
                    electron doping. Potential barrier is from @ref block_1 to @ref block_2 and
                    has a height of block_height.
                    If @ref dipfield = .TRUE. then @ref eopreg is used for a smooth increase and
                    decrease of the potential barrier.
                }
            }

            var block_1 -type REAL {
                default { 0.45 }
                info {
                    used only if @ref gate = .TRUE. and @ref block = .TRUE.
                    lower beginning of the potential barrier, in units of the
                    unit cell size along @i z, @ref block_1 in ]0,1[
                }
            }

            var block_2 -type REAL {
                default { 0.55 }
                info {
                    used only if @ref gate = .TRUE. and @ref block = .TRUE.
                    upper beginning of the potential barrier, in units of the
                    unit cell size along @i z, @ref block_2 in ]0,1[
                }
            }

            var block_height -type REAL {
                default { 0.1 }
                info {
                    used only if @ref gate = .TRUE. and @ref block = .TRUE.
                    Height of the potential barrier in Rydberg.
                }
            }
        }

         var nextffield -type INTEGER {
           default { 0 }
           info {
               Number of activated external ionic force fields. 
               See Doc/ExternalForceFields.tex for further explanation and parameterizations
           }
         }  
    

    }

    #
    # namelist ELECTRONS
    #

    namelist ELECTRONS {

        var electron_maxstep    -type INTEGER { 
            default { 100 }
            info {
                maximum number of iterations in a scf step. If exact exchange is active, 
                this will affect the inner loops.
            }
        }

        var exx_maxstep    -type INTEGER { 
            default { 100 }
            info {
                maximum number of outer iterations in a scf calculation with exact exchange.
            }
        }

        var scf_must_converge   -type LOGICAL { 
            default { .TRUE. }
            info {
                If .false. do not stop molecular dynamics or ionic relaxation
                when electron_maxstep is reached. Use with care.
            }
        }


        var conv_thr -type REAL { 
            default { 1.D-6 }
            info {
                Convergence threshold for selfconsistency:
                   estimated energy error < conv_thr
                (note that conv_thr is extensive, like the total energy).
                
                For non-self-consistent calculations, conv_thr is used
                to set the default value of the threshold (ethr) for
                iterative diagonalization: see @ref diago_thr_init
            }
        }
        
        var adaptive_thr -type LOGICAL { 
            default { .FALSE }
            info {
                If .TRUE. this turns on the use of an adaptive @ref conv_thr for 
                the inner scf loops when using EXX.
            }
        }

        var conv_thr_init -type REAL { 
            default { 1.D-3 }
            info {
                When @ref adaptive_thr = .TRUE. this is the convergence threshold 
                used for the first scf cycle.           
            }
        }
        
        var conv_thr_multi -type REAL { 
            default { 1.D-1 }
            info {
                When @ref adaptive_thr = .TRUE. the convergence threshold for 
                each scf cycle is given by:
                max( @ref conv_thr, @ref conv_thr_multi * dexx )
            }
        }

        var mixing_mode -type CHARACTER {
            default { 'plain' }
            options {
                info { Available options are: }
                
                opt -val 'plain' { charge density Broyden mixing }
                
                opt -val 'TF' {
                    as above, with simple Thomas-Fermi screening
                    (for highly homogeneous systems)
                }                
                opt -val 'local-TF' {
                    as above, with local-density-dependent TF screening
                    (for highly inhomogeneous systems)
                }
            }
        }

        var mixing_beta -type REAL { 
            default { 0.7D0 }
            info {
                mixing factor for self-consistency
            }
        }

        var mixing_ndim -type INTEGER { 
            default { 8 }
            info {
                number of iterations used in mixing scheme.
                If you are tight with memory, you may reduce it to 4 or so.
            }
        }

        var mixing_fixed_ns -type INTEGER { 
            default { 0 }
            info {
                For DFT+U : number of iterations with fixed ns ( ns is the
                atomic density appearing in the Hubbard term ).
            }
        }
        
        var diagonalization -type CHARACTER {
            default { 'david' }
            options {
                info { Available options are: }
                
                opt -val 'david' {
                    Davidson iterative diagonalization with overlap matrix
                    (default). Fast, may in some rare cases fail.
                }

                opt -val 'cg' {
                    Conjugate-gradient-like band-by-band diagonalization.
                    MUCH slower than 'david' but uses less memory and is 
                    (a little bit) more robust.
                }

                opt -val {'ppcg'} {
                    PPCG iterative diagonalization
                }

                opt -val {'paro', 'ParO'} {
                    ParO iterative diagonalization
                }
               
                opt -val {'rmm-davidson', 'rmm-paro'} {
                    RMM-DIIS iterative diagonalization.  
                    To stabilize the SCF loop 
                    RMM-DIIS is alternated with calls to Davidson or
                    ParO  solvers depending on the string used. 
                    Other variables that can be used to tune the behavior of 
                    RMM-DIIS are:  @ref diago_rmm_ndim and @ref diago_rmm_conv
                }
            }
        }

        var diago_thr_init -type REAL {
            info {
                Convergence threshold (ethr) for iterative diagonalization
                (the check is on eigenvalue convergence).
                
                For scf calculations: default is 1.D-2 if starting from a
                superposition of atomic orbitals; 1.D-5 if starting from a
                charge density. During self consistency the threshold
                is automatically reduced (but never below 1.D-13) when 
                approaching convergence.

                For non-scf calculations: default is (@ref conv_thr/N elec)/10.
            }
        }

        var diago_cg_maxiter -type INTEGER {
            info {
                For conjugate gradient diagonalization:  max number of iterations
            }
        }

        var diago_ppcg_maxiter -type INTEGER {
            info {
                For @b ppcg diagonalization:  max number of iterations
            }
        }

        var diago_david_ndim -type INTEGER { 
            default { 2 }
            info {
                For Davidson diagonalization: dimension of workspace
                (number of wavefunction packets, at least 2 needed).
                A larger value may yield a smaller number of iterations in
                the algorithm but uses more memory and more CPU time in 
                subspace diagonalization (cdiaghg/rdiaghg). You may try
                @ref diago_david_ndim=4 if you are not tight on memory 
                and if the time spent in subspace diagonalization is small
                compared to the time spent in h_psi
            }
        }

        var diago_rmm_ndim -type INTEGER { 
            default { 4 }
            info {
                For RMM-DIIS diagonalization: dimension of workspace
                (number of wavefunction packets, at least 2 needed).
            }
        }

        var diago_rmm_conv -type LOGICAL { 
            default { .FALSE. }
            info {
                If .TRUE., RMM-DIIS is performed up to converge.
                If .FALSE., RMM-DIIS is performed only once.
            }
        }

        var diago_gs_nblock -type INTEGER { 
            default { 16 }
            info {
                For RMM-DIIS diagonalization:
                blocking size of Gram-Schmidt orthogonalization
            }
        }

        var diago_full_acc -type LOGICAL { 
            default { .FALSE. }
            info {
                If .TRUE. all the empty states are diagonalized at the same level
                of accuracy of the occupied ones. Otherwise the empty states are
                diagonalized using a larger threshold (this should not affect
                total energy, forces, and other ground-state properties).
            }
        }
        

        var efield -type REAL {
            default { 0.D0 }
            info {
                Amplitude of the finite electric field (in Ry a.u.;
                1 a.u. = 36.3609*10^10 V/m). Used only if @ref lelfield==.TRUE.
                and if k-points (@ref K_POINTS card) are not automatic.
            }
        }

        dimension efield_cart -start 1 -end 3 -type REAL { 
            default { (0.D0, 0.D0, 0.D0) }
            info {
                Finite electric field (in Ry a.u.=36.3609*10^10 V/m) in
                cartesian axis. Used only if @ref lelfield==.TRUE. and if
                k-points (@ref K_POINTS card) are automatic.
            }
        }

        var efield_phase -type CHARACTER {
            default { 'none' }
            options {
                info { Available options are: }
                
                opt -val 'read' {
                    set the zero of the electronic polarization (with @ref lelfield==.true..) 
                    to the result of a previous calculation
                }                
                opt -val 'write' {
                    write on disk data on electronic polarization to be read in another 
                    calculation
                }                
                opt -val 'none' {
                    none of the above points
                }
            }  
        }
        
        var startingpot -type CHARACTER {
            options {
                info { Available options are: }
                
                opt -val 'atomic' {
                    starting potential from atomic charge superposition
                    (default for scf, *relax, *md)
                }

                opt -val 'file'  {
                    start from existing "charge-density.xml" file in the
                    directory specified by variables @ref prefix and @ref outdir
                    For nscf and bands calculation this is the default
                    and the only sensible possibility.
                }
            }
        }

        var startingwfc -type CHARACTER {
            default { 'atomic+random' }
            options {
                info { Available options are: }
                
                opt -val 'atomic' {
                    Start from superposition of atomic orbitals.
                    If not enough atomic orbitals are available,
                    fill with random numbers the remaining wfcs
                    The scf typically starts better with this option,
                    but in some high-symmetry cases one can "loose" 
                    valence states, ending up in the wrong ground state.
                }
                opt -val 'atomic+random' {
                    As above, plus a superimposed "randomization"
                    of atomic orbitals. Prevents the "loss" of states 
                    mentioned above.
                }
                opt -val 'random' {
                    Start from random wfcs. Slower start of scf but safe.
                    It may also reduce memory usage in conjunction with
                    @ref diagonalization='cg'.
                }
                opt -val 'file' {
                    Start from an existing wavefunction file in the 
                    directory specified by variables @ref prefix and @ref outdir.
                }
            }
        }

        var tqr -type LOGICAL { 
            default { .FALSE. }
            info {
                If .true., use a real-space algorithm for augmentation
                charges of ultrasoft pseudopotentials and PAWsets.
                Faster but numerically less accurate than the default
                G-space algorithm. Use with care and after testing!
            }
        }

        var real_space -type LOGICAL { 
            default { .FALSE. }
            info {
                If .true., exploit real-space localization to compute
                matrix elements for nonlocal projectors. Faster and in
                principle better scaling than the default G-space algorithm,
                but numerically less accurate, may lead to some loss of
                translational invariance. Use with care and after testing!
            }
        }
    }

    
    #
    # NAMELIST IONS
    #
    
    namelist IONS  {
        label { 
            REQUIRED if @ref calculation == 'relax', 'md', 'vc-relax', or 'vc-md' 
            OPTIONAL for @ref calculation == 'scf' (only @ref ion_positions is used)
        }
 

        var ion_positions -type CHARACTER {
            default { 'default' }
            options {
                info { Available options are: }
                
                opt -val 'default' {
                    if restarting, use atomic positions read from the
                    restart file; in all other cases, use atomic
                    positions from standard input.
                }
                opt -val 'from_input' {
                    read atomic positions from standard input, even if restarting.
                }
            }
        }

        var ion_velocities -type CHARACTER {
            default { 'default' }
            options {
                info {
                    Initial ionic velocities. Available options are:                
                }

                opt -val 'default' {
                    start a new simulation from random thermalized
                    distribution of velocities if @ref tempw is set,
                    with zero velocities otherwise; restart from
                    atomic velocities read from the restart file
                }
                opt -val 'from_input' {
                    start or continue the simulation with atomic
                    velocities read from standard input - see card
                    @ref ATOMIC_VELOCITIES
                }
            }
        }

        var ion_dynamics -type CHARACTER {
            options {
                info {
                    Specify the type of ionic dynamics.
                    
                    For different type of calculation different possibilities are
                    allowed and different default values apply:
                    
                    @b CASE ( @ref calculation == 'relax' )
                }
                opt -val 'bfgs' {
                    @b (default)  use BFGS quasi-newton algorithm,
                    based on the trust radius procedure,
                    for structural relaxation
                }
                opt -val 'damp' {
                    use damped (quick-min Verlet)
                    dynamics for structural relaxation
                    Can be used for constrained 
                    optimisation: see @ref CONSTRAINTS card
                }
		opt -val 'fire' {
                    use the FIRE minimization algorithm employing the
		    semi-implicit Euler integration scheme
		    see:
		       Bitzek et al.,PRL, 97, 170201, (2006), doi: 10.1103/PhysRevLett.97.170201
		       Guenole et al.,CMS, 175, 109584, (2020), doi: 10.1016/j.commatsci.2020.109584

                    Can be used for constrained 
                    optimisation: see @ref CONSTRAINTS card
                }
                info {
                    @b CASE ( @ref calculation == 'md' )
                }
                opt -val 'verlet' {
                    @b (default)  use Verlet algorithm to integrate
                    Newton's equation. For constrained 
                    dynamics, see @ref CONSTRAINTS card
                }
                opt -val 'langevin' {
                    ion dynamics is over-damped Langevin
                }
                opt -val 'langevin-smc' {
                    over-damped Langevin with Smart Monte Carlo:
                    see R.J. Rossky, JCP, 69, 4628 (1978), doi:10.1063/1.436415
                }
                info {
                    @b CASE ( @ref calculation == 'vc-relax' )
                }
                opt -val 'bfgs' {
                    @b (default)  use BFGS quasi-newton algorithm;
                    @ref cell_dynamics must be 'bfgs' too
                }
                opt -val 'damp' {
                    use damped (Beeman) dynamics for
                    structural relaxation
                }
                info {
                    @b CASE ( @ref calculation == 'vc-md' )
                }
                opt -val 'beeman' {
                    @b (default)  use Beeman algorithm to integrate
                    Newton's equation
                }
            }
        }

        var pot_extrapolation -type CHARACTER { 
            default { 'atomic' }
            options {
                info {
                    Used to extrapolate the potential from preceding ionic steps.
                }
                opt -val 'none' { no extrapolation }

                opt -val 'atomic' {
                    extrapolate the potential as if it was a sum of
                    atomic-like orbitals
                }
                opt -val 'first_order' {
                    extrapolate the potential with first-order
                    formula
                }

                opt -val 'second_order' {
                    as above, with second order formula
                }
                info {
                    Note: 'first_order' and 'second-order' extrapolation make sense
                    only for molecular dynamics calculations
                }
            }
        }

        var wfc_extrapolation -type CHARACTER { 
            default { 'none' }
            options {
                info {
                    Used to extrapolate the wavefunctions from preceding ionic steps.
                }
                opt -val 'none' {  no extrapolation }

                opt -val 'first_order' {
                    extrapolate the wave-functions with first-order formula.
                }

                opt -val 'second_order' {
                    as above, with second order formula.
                }
                info {
                    Note: @b 'first_order' and @b 'second-order' extrapolation make sense
                    only for molecular dynamics calculations
                }
            }
        }

        var remove_rigid_rot -type LOGICAL { 
            default { .FALSE. }
            info {
               This keyword is useful when simulating the dynamics and/or the
               thermodynamics of an isolated system. If set to true the total
               torque of the internal forces is set to zero by adding new forces
               that compensate the spurious interaction with the periodic
               images. This allows for the use of smaller supercells.

               BEWARE: since the potential energy is no longer consistent with
               the forces (it still contains the spurious interaction with the
               repeated images), the total energy is not conserved anymore.
               However the dynamical and thermodynamical properties should be
               in closer agreement with those of an isolated system.
               Also the final energy of a structural relaxation will be higher,
               but the relaxation itself should be faster.
            }
        }
         
        group {
            label {
                variables used for molecular dynamics
            }       

            var ion_temperature -type CHARACTER {
                default { 'not_controlled' }
                options {
                    info { Available options are: }
                    
                    opt -val 'rescaling' {
                        control ionic temperature via velocity rescaling
                        (first method) see parameters @ref tempw, @ref tolp, and
                        @ref nraise (for VC-MD only). This rescaling method
                        is the only one currently implemented in VC-MD
                    }
                    opt -val 'rescale-v' {
                        control ionic temperature via velocity rescaling
                        (second method) see parameters @ref tempw and @ref nraise
                    }
                    opt -val 'rescale-T' {
                        scale temperature of the thermostat every @ref nraise steps
                        by @ref delta_t, starting from @ref tempw.
                        The temperature is controlled via velocitiy rescaling.
                    }
                    opt -val 'reduce-T' {
                        reduce temperature of the thermostat every @ref nraise steps
                        by the (negative) value @ref delta_t, starting from @ref tempw.
                        If  @ref delta_t is positive, the target temperature is augmented.
                        The temperature is controlled via velocitiy rescaling.
                    }
                    opt -val 'berendsen' {
                        control ionic temperature using "soft" velocity
                        rescaling - see parameters @ref tempw and @ref nraise
                    }
                    opt -val 'andersen' {
                        control ionic temperature using Andersen thermostat
                        see parameters @ref tempw and @ref nraise
                    }
                    opt -val 'svr' {
                        control ionic temperature using stochastic-velocity rescaling
                        (Donadio, Bussi, Parrinello, J. Chem. Phys. 126, 014101, 2007),
                        with parameters @ref tempw and @ref nraise.
                    }
                    opt -val 'initial' {
                        initialize ion velocities to temperature @ref tempw
                        and leave uncontrolled further on
                    }
                    opt -val 'not_controlled' {
                        (default) ionic temperature is not controlled
                    }
                }
            }

            var tempw -type REAL { 
                default { 300.D0 }
                info {
                    Starting temperature (Kelvin) in MD runs
                    target temperature for most thermostats.
                }
            }

            var tolp -type REAL { 
                default { 100.D0 }
                info {
                    Tolerance for velocity rescaling. Velocities are rescaled if
                    the run-averaged and target temperature differ more than tolp.
                }
            }

            var delta_t -type REAL { 
                default { 1.D0 }
                info {
                    if @ref ion_temperature == 'rescale-T' :
                           at each step the instantaneous temperature is multiplied
                           by delta_t; this is done rescaling all the velocities.

                    if @ref ion_temperature == 'reduce-T' :
                           every 'nraise' steps the instantaneous temperature is
                           reduced by -@ref delta_t (i.e. @ref delta_t < 0 is added to T)

                    The instantaneous temperature is calculated at the end of
                    every ionic move and BEFORE rescaling. This is the temperature
                    reported in the main output.
                
                    For @ref delta_t < 0, the actual average rate of heating or cooling
                    should be roughly C*delta_t/(nraise*dt) (C=1 for an
                    ideal gas, C=0.5 for a harmonic solid, theorem of energy
                    equipartition between all quadratic degrees of freedom).
                }
            }

            var nraise -type INTEGER { 
                default { 1 }
                info {
                    if @ref ion_temperature == 'reduce-T' :
                           every @ref nraise steps the instantaneous temperature is
                           reduced by -@ref delta_t (i.e. @ref delta_t is added to the temperature)
                
                    if @ref ion_temperature == 'rescale-v' :
                           every @ref nraise steps the average temperature, computed from
                           the last @ref nraise steps, is rescaled to @ref tempw

                    if @ref ion_temperature == 'rescaling' and @ref calculation == 'vc-md' :
                           every @ref nraise steps the instantaneous temperature
                           is rescaled to @ref tempw
                    
                    if @ref ion_temperature == 'berendsen' :
                           the "rise time" parameter is given in units of the time step:
                           tau = nraise*dt, so dt/tau = 1/nraise
                    
                    if @ref ion_temperature == 'andersen' :
                           the "collision frequency" parameter is given as nu=1/tau
                           defined above, so nu*dt = 1/nraise

                    if @ref ion_temperature == 'svr' :
                           the "characteristic time" of the thermostat is set to
                           tau = nraise*dt
                }
            }

            var refold_pos -type LOGICAL { 
                default { .FALSE. }
                info {
                    This keyword applies only in the case of molecular dynamics or
                    damped dynamics. If true the ions are refolded at each step into
                    the supercell.
                }
            }
        }
    
        group {
            label {
                keywords used only in BFGS calculations
            }   

            var upscale -type REAL { 
                default { 100.D0 }
                info {
                    Max reduction factor for @ref conv_thr during structural optimization
                    @ref conv_thr is automatically reduced when the relaxation
                    approaches convergence so that forces are still accurate,
                    but @ref conv_thr will not be reduced to less that @ref conv_thr / @ref upscale.
                }
            }

            var bfgs_ndim -type INTEGER { 
                default { 1 }
                info {
                    Number of old forces and displacements vectors used in the
                    PULAY mixing of the residual vectors obtained on the basis
                    of the inverse hessian matrix given by the BFGS algorithm.
                    When @ref bfgs_ndim = 1, the standard quasi-Newton BFGS method is
                    used.
                    (bfgs only)
                }
            }

            var trust_radius_max -type REAL { 
                default { 0.8D0 }
                info {
                    Maximum ionic displacement in the structural relaxation.
                    (bfgs only)
                }
            }

            var trust_radius_min -type REAL { 
                default { 1.D-3 }
                info {
                    Minimum ionic displacement in the structural relaxation
                    BFGS is reset when @ref trust_radius < @ref trust_radius_min.
                    (bfgs only)
                }
            }

            var trust_radius_ini -type REAL { 
                default { 0.5D0 }
                info {
                    Initial ionic displacement in the structural relaxation.
                    (bfgs only)
                }
            }
        
            var w_1 -type REAL { default { 0.01D0 }; see { w_2 } }
            var w_2 -type REAL { 
                default { 0.5D0 }
                info {
                    Parameters used in line search based on the Wolfe conditions.
                    (bfgs only)
                }
            }
        }
	group {
            label {
                keywords used only in the FIRE minimization algorithm 
            }   

            var fire_alpha_init -type REAL { 
                default { 0.2D0 }
                info {
                    Initial value of the alpha mixing factor in the FIRE minimization scheme;
		    recommended values are between 0.1 and 0.3 
                }
            }
	    var fire_falpha -type REAL { 
                default { 0.99D0 }
                info {
                    Scaling of the alpha mixing parameter for steps with P > 0;  
                }
            }
	    var fire_nmin -type INTEGER { 
                default { 5 }
                info {
                    Minimum number of steps with P > 0 before increase of @ref dt 
                }
            }
	    var fire_f_inc -type REAL { 
                default { 1.1D0 }
                info {
                   Factor for increasing @ref dt 
                }
            }
	    var fire_f_dec -type REAL { 
                default { 0.5D0 }
                info {
                   Factor for decreasing @ref dt 
                }
            }
	    var fire_dtmax -type REAL { 
                default { 10.D0 }
                info {
                   Determines the maximum value of @ref dt in the FIRE minimization;
		   dtmax = fire_dtmax*@ref dt 
                }
            }
        }

    }

    #
    # namelist CELL
    #

    namelist CELL {
        label {
            input this namelist only if @ref calculation == 'vc-relax' or 'vc-md' 
        }

        var cell_dynamics -type CHARACTER {
            options {
                info {
                    Specify the type of dynamics for the cell.
                    For different type of calculation different possibilities
                    are allowed and different default values apply:

                    @b CASE ( @ref calculation == 'vc-relax' )
                }
                opt -val 'none' { no dynamics }
                opt -val 'sd'   { steepest descent ( not implemented ) }
                opt -val 'damp-pr' {
                    damped (Beeman) dynamics of the Parrinello-Rahman extended lagrangian
                }
                opt -val 'damp-w' {
                    damped (Beeman) dynamics of the new Wentzcovitch extended lagrangian
                }
                opt -val 'bfgs' {
                    BFGS quasi-newton algorithm @b (default)
                    @ref ion_dynamics must be @b 'bfgs' too
                }
                info {
                    @b CASE ( @ref calculation == 'vc-md' )
                }
                opt -val 'none' { no dynamics }
                opt -val 'pr' {
                    (Beeman) molecular dynamics of the Parrinello-Rahman extended lagrangian
                }
                opt -val 'w' {
                    (Beeman) molecular dynamics of the new Wentzcovitch extended lagrangian
                }
            }
        }       

        var press -type REAL { 
            default { 0.D0 }
            info { 
                Target pressure [KBar] in a variable-cell md or relaxation run. 
            }
        }
        
        var wmass -type REAL { 
            default {
                0.75*Tot_Mass/pi**2 for Parrinello-Rahman MD;
                0.75*Tot_Mass/pi**2/Omega**(2/3) for Wentzcovitch MD
            }
            info {
                Fictitious cell mass [amu] for variable-cell simulations
                (both 'vc-md' and 'vc-relax')
            }
        }

        var cell_factor -type REAL { 
            default { 2.0 for variable-cell calculations, 1.0 otherwise }
            info {
                Used in the construction of the pseudopotential tables.
                It should exceed the maximum linear contraction of the
                cell during a simulation.
            }
        }
        
        var press_conv_thr -type REAL { 
            default { 0.5D0 Kbar }
            info {
                Convergence threshold on the pressure for variable cell
                relaxation ('vc-relax' : note that the other convergence
                            thresholds for ionic relaxation apply as well).
            }
        }
        
        var cell_dofree -type CHARACTER { 
            default { 'all' }
            options {
                info {
                    Select which of the cell parameters should be moved:
                }                
                opt -val 'all'          { all axis and angles are moved }
                opt -val 'ibrav'        { all axis and angles are moved, 
                but the lattice remains consistent
                with the initial ibrav choice. You can use this option in combination
                with any other one by specifying "ibrav+option". Please note that some
                combinations do not make sense for some crystals and will guarantee that
                the relax will never converge. E.g. 'ibrav+2Dxy' is not a problem for
                hexagonal cells, but will never converge for cubic ones.  }
                opt -val 'a'            { the x component of axis 1 (v1_x) is fixed }
                opt -val 'b'            { the y component of axis 2 (v2_y) is fixed }
                opt -val 'c'            { the z component of axis 3 (v3_z) is fixed }
                opt -val 'fixa'         { axis 1 (v1_x,v1_y,v1_z) is fixed }
                opt -val 'fixb'         { axis 2 (v2_x,v2_y,v2_z) is fixed }
                opt -val 'fixc'         { axis 3 (v3_x,v3_y,v3_z) is fixed }
                opt -val 'x'            { only the x component of axis 1 (v1_x) is moved }
                opt -val 'y'            { only the y component of axis 2 (v2_y) is moved }
                opt -val 'z'            { only the z component of axis 3 (v3_z) is moved }
                opt -val 'xy'           { only v1_x and v2_y are moved }
                opt -val 'xz'           { only v1_x and v3_z are moved }
                opt -val 'yz'           { only v2_y and v3_z are moved }
                opt -val 'xyz'          { only v1_x, v2_y, v3_z are moved }
                opt -val 'shape'        { all axis and angles, keeping the volume fixed }
                opt -val 'volume'       { the volume changes, keeping all angles fixed (i.e. only celldm(1) changes) }
                opt -val '2Dxy'         { only x and y components are allowed to change }
                opt -val '2Dshape'      { as above, keeping the area in xy plane fixed }
                opt -val 'epitaxial_ab' {fix axis 1 and 2 while allowing axis 3 to move }
                opt -val 'epitaxial_ac' {fix axis 1 and 3 while allowing axis 2 to move }
                opt -val 'epitaxial_bc' {fix axis 2 and 3 while allowing axis 1 to move }
                info {
                    BEWARE: if axis are not orthogonal, some of these options do not
                            work (symmetry is broken). If you are not happy with them, 
                            edit subroutine init_dofree in file Modules/cell_base.f90
                }
            }
        }
    }

    #
    # namelist FCP
    #

    namelist FCP {
        label {
            Input this namelist only if @ref lfcp = .TRUE.
        }

        var fcp_mu -type REAL {
            status { REQUIRED }
            info {
                The target Fermi energy (eV). One can start
                with appropriate total charge of the system by giving @ref tot_charge .
            }
        }

        var fcp_dynamics -type CHARACTER {
            options {
                info {
                    Specify the type of dynamics for the Fictitious Charge Particle (FCP).

                    For different type of calculation different possibilities
                    are allowed and different default values apply:

                    @b CASE ( @ref calculation == 'relax' )
                }
                opt -val 'bfgs' {
                    @b (default) BFGS quasi-newton algorithm, coupling with ions relaxation
                    @ref ion_dynamics must be @b 'bfgs' too
                }
                opt -val 'newton' {
                    Newton-Raphson algorithm with DIIS
                    @ref ion_dynamics must be @b 'damp' too
                }
                opt -val 'damp' {
                    damped (quick-min Verlet) dynamics for FCP relaxation
                    @ref ion_dynamics must be @b 'damp' too
                }
                opt -val 'lm' {
                    Line-Minimization algorithm for FCP relaxation
                    @ref ion_dynamics must be @b 'damp' too
                }
                info {
                    @b CASE ( @ref calculation == 'md' )
                }
                opt -val 'velocity-verlet' {
                    @b (default) Velocity-Verlet algorithm to integrate Newton's equation.
                    @ref ion_dynamics must be @b 'verlet' too
                }
                opt -val 'verlet' {
                    @b Verlet algorithm to integrate Newton's equation.
                    @ref ion_dynamics must be @b 'verlet' too
                }
            }
        }

        var fcp_conv_thr -type REAL {
            default { 1.D-2 }
            info {
                Convergence threshold on force (eV) for FCP relaxation.
            }
        }

        var fcp_ndiis -type INTEGER {
            default { 4 }
            info {
                Size of DIIS for FCP relaxation,
                used only if @ref fcp_dynamics = 'newton'.
            }
        }

        group {
            label {
                Variables used for FCP dynamics.
            }

            var fcp_mass -type REAL {
                default {
                    5.D+6 / (xy area) for ESM only;
                    5.D+4 / (xy area) for ESM-RISM
                }
                info {
                    Mass of the FCP.
                }
            }

            var fcp_velocity -type REAL {
                default { determined by @ref fcp_temperature }
                info {
                    Initial velocity of the FCP.
                }
            }

            var fcp_temperature -type CHARACTER {
                default { @ref ion_temperature }
                options {
                    info { Available options are: }
                    opt -val 'rescaling' {
                        control FCP's temperature via velocity rescaling
                        (first method) see parameters @ref fpc_tempw and @ref fcp_tolp.
                    }
                    opt -val 'rescale-v' {
                        control FCP's temperature via velocity rescaling
                        (second method) see parameters @ref fcp_tempw and @ref fcp_nraise
                    }
                    opt -val 'rescale-T' {
                        control FCP's temperature via velocity rescaling
                        (third method) see parameter @ref fcp_delta_t
                    }
                    opt -val 'reduce-T' {
                        reduce FCP's temperature every @ref fcp_nraise steps
                        by the (negative) value @ref fcp_delta_t
                    }
                    opt -val 'berendsen' {
                        control FCP's temperature using "soft" velocity
                        rescaling - see parameters @ref fcp_tempw and @ref fcp_nraise
                    }
                    opt -val 'andersen' {
                        control FCP's temperature using Andersen thermostat
                        see parameters @ref fcp_tempw and @ref fcp_nraise
                    }
                    opt -val 'initial' {
                        initialize FCP's velocities to temperature @ref fcp_tempw
                        and leave uncontrolled further on
                    }
                    opt -val 'not_controlled' {
                        @b (default) FCP's temperature is not controlled
                    }
                }
            }

            var fcp_tempw -type REAL {
                default { @ref tempw }
                info {
                    Starting temperature (Kelvin) in FCP dynamics runs
                    target temperature for most thermostats.
                }
            }

            var fcp_tolp -type REAL {
                default { @ref tolp }
                info {
                    Tolerance for velocity rescaling. Velocities are rescaled if
                    the run-averaged and target temperature differ more than tolp.
                }
            }

            var fcp_delta_t -type REAL {
                default { @ref delta_t }
                info {
                    if @ref fcp_temperature == 'rescale-T' :
                           at each step the instantaneous temperature is multiplied
                           by fcp_delta_t; this is done rescaling all the velocities.

                    if @ref fcp_temperature == 'reduce-T' :
                           every @ref fcp_nraise steps the instantaneous temperature is
                           reduced by -@ref fcp_delta_t (i.e. @ref fcp_delta_t < 0 is added to T)

                    The instantaneous temperature is calculated at the end of
                    FCP's move and BEFORE rescaling. This is the temperature
                    reported in the main output.

                    For @ref fcp_delta_t < 0, the actual average rate of heating or cooling
                    should be roughly C*fcp_delta_t/(fcp_nraise*dt) (C=1 for an
                    ideal gas, C=0.5 for a harmonic solid, theorem of energy
                    equipartition between all quadratic degrees of freedom).
                }
            }

            var fcp_nraise -type INTEGER {
                default { @ref nraise }
                info {
                    if @ref fcp_temperature == 'reduce-T' :
                           every @ref fcp_nraise steps the instantaneous temperature is
                           reduced by -@ref fcp_delta_t (i.e. @ref fcp_delta_t is added to the temperature)

                    if @ref fcp_temperature == 'rescale-v' :
                           every @ref fcp_nraise steps the average temperature, computed from
                           the last @ref fcp_nraise steps, is rescaled to @ref fcp_tempw

                    if @ref fcp_temperature == 'berendsen' :
                           the "rise time" parameter is given in units of the time step:
                           tau = fcp_nraise*dt, so dt/tau = 1/fcp_nraise

                    if @ref fcp_temperature == 'andersen' :
                           the "collision frequency" parameter is given as nu=1/tau
                           defined above, so nu*dt = 1/fcp_nraise
                }
            }
        }

        var freeze_all_atoms -type LOGICAL {
            default { .FALSE. }
            info {
                If .TRUE., freeze all atoms
                to perform relaxation or dynamics only with FCP.
            }
        }
    }

    #
    # namelist RISM
    #

    namelist RISM {
        label {
            Input this namelist only if @ref trism = .TRUE.
        }

        var nsolv -type INTEGER {
            status { REQUIRED }
            info {
                The number of solvents (i.e. molecular species) in the unit cell
            }
        }

        var closure -type CHARACTER {
            default { 'kh' }
            options {
                info {
                    Specify the type of closure equation:
                }
                opt -val 'kh' {
                    The Kovalenko and Hirata's model.
                    [A.Kovalenko, F.Hirata, JCP 110, 10095 (1999), doi:10.1063/1.478883]
                }
                opt -val 'hnc' {
                    The HyperNetted-Chain model, which is
                    suitable only for solvents without charge.
                    [J.P.Hansen et al., Theory of simple liquids. Academic Press, London, 1990]
                }
            }
        }

        var tempv -type REAL {
            default { 300.D0 }
            info {
                Temperature (Kelvin) of solvents.
            }
        }

        var ecutsolv -type REAL {
            default { 4 * @ref ecutwfc }
            info {
                Kinetic energy cutoff (Ry) for solvent's correlation functions.
                If a solute is an isolated system or slab, you may allowed to
                use default value. For a frameworked or porous solute (e.g. Zeolite, MOF),
                it is desirable to apply a larger value. Solvents confined in a framework
                often have a high frequency.
            }
        }

        dimension solute_lj -start 1 -end ntyp -type CHARACTER {
            default { 'uff' }
            options {
                info {
                    Specify the Lennard-Jones potential of solute on atomic type 'i':
                }
                opt -val 'none' {
                    The Lennard-Jones potential is not specified here.
                    you must set @ref solute_epsilon and @ref solute_sigma.
                }
                opt -val 'uff' {
                    Universal Force Field.
                    [A.K.Rappe et al., JACS 144, 10024 (1992), doi:10.1021/ja00051a040]
                }
                opt -val 'clayff' {
                    Clay's Force Field
                    [R.T.Cygan et al., JPC B 108, 1255 (2004), doi:10.1021/jp0363287]
                }
                opt -val 'opls-aa' {
                    OPLS-AA (generic parameters for QM/MM)
                }
            }
        }

        dimension solute_epsilon -start 1 -end ntyp -type REAL {
            info {
                The Lennard-Jones potential of solute on atomic type 'i'.
                Here, you can set the parameter 'epsilon' (kcal/mol).
            }
        }

        dimension solute_sigma -start 1 -end ntyp -type REAL {
            info {
                The Lennard-Jones potential of solute on atomic type 'i'.
                Here, you can set the parameter 'sigma' (Angstrom).
            }
        }

        var starting1d -type CHARACTER {
            options {
                opt -val 'zero' {
                    Starting correlation functions of 1D-RISM from zero.
                    ( default for scf, *relax, *md )
                }
                opt -val 'file' {
                    Start from existing "1d-rism_csvv_r.xml" file in the
                    directory specified by variables "prefix" and "outdir".
                }
                opt -val 'fix' {
                    Read from existing "1d-rism_csvv_r.xml" file in the
                    directory specified by variables "prefix" and "outdir",
                    and never calculate 1D-RISM.
                    For nscf and bands calculation this is the default.
                }
            }
        }

        var starting3d -type CHARACTER {
            options {
                opt -val 'zero' {
                    Starting correlation functions of 3D-RISM from zero.
                    ( default for scf, *relax, *md )
                }
                opt -val 'file' {
                    Start from existing "3d-rism_csuv_r.dat" file in the
                    directory specified by variables "prefix" and "outdir".
                    For nscf and bands calculation this is the default.
                }
            }
        }

        var smear1d -type REAL {
            default { 2.D0 }
            info {
                Coulomb smearing radius (a.u.) for 1D-RISM.
            }
        }

        var smear3d -type REAL {
            default { 2.D0 }
            info {
                Coulomb smearing radius (a.u.) for 3D-RISM.
            }
        }

        var rism1d_maxstep -type INTEGER {
            default { 50000 }
            info {
                Maximum number of iterations in a 1D-RISM step.
            }
        }

        var rism3d_maxstep -type INTEGER {
            default { 5000 }
            info {
                Maximum number of iterations in a 3D-RISM step.
            }
        }

        var rism1d_conv_thr -type REAL {
            default { 1.D-8 }
            info {
                Convergence threshold for 1D-RISM.
            }
        }

        var rism3d_conv_thr -type REAL {
            default {
                1.D-5 if @ref lgcscf == .FALSE.;
                5.D-6 if @ref lgcscf == .TRUE.
            }
            info {
                Convergence threshold for 3D-RISM.
            }
        }

        var mdiis1d_size -type INTEGER {
            default { 20 }
            info {
                Size of Modified DIIS (MDIIS) for 1D-RISM.
            }
        }

        var mdiis3d_size -type INTEGER {
            default { 10 }
            info {
                Size of Modified DIIS (MDIIS) for 3D-RISM.
            }
        }

        var mdiis1d_step -type REAL {
            default { 0.5D0 }
            info {
                Step of Modified DIIS (MDIIS) for 1D-RISM.
            }
        }

        var mdiis3d_step -type REAL {
            default { 0.8D0 }
            info {
                Step of Modified DIIS (MDIIS) for 3D-RISM.
            }
        }

        var rism1d_bond_width -type REAL {
            info {
                Gaussian width of bonds to smear intra-molecular correlation for 1D-RISM.
                If 3D-RISM calculation, default is 0.
                If Laue-RISM calculation, default is 2 / SQRT(@ref ecutwfc).
            }
        }

        var rism1d_dielectric -type REAL {
            default { -1.0D0 }
            info {
                Dielectric constant for 1D-RISM.
                If @ref rism1d_dielectric > 0, dielectrically consistent RISM (DRISM) is performed.

                For details of DRISM, see:
                J.S.Perkyns and B.M.Pettitt, CPL 1992, 190, 626, doi:10.1016/0009-2614(92)85201-K
            }
        }

        var rism1d_molesize -type REAL {
            default { 2.0D0 }
            info {
                Size of solvent molecules (a.u.) for 1D-RISM.
                This is used only if @ref rism1d_dielectric > 0.
                If you have large molecules, you have to set ~ 20 a.u. .
            }
        }

        var rism1d_nproc -type INTEGER {
            default { 128 }
            info {
                Number of processes to calculate 1D-RISM.
            }
        }

        var rism3d_conv_level -type REAL {
            default { 
                0.1 if @ref laue_both_hands == .FALSE. .AND. @ref lgcscf == .FALSE.;
                0.3 if @ref laue_both_hands == .FALSE. .AND. @ref lgcscf == .TRUE.;
                0.5 if @ref laue_both_hands == .TRUE.
            }
            options {
                info {
                    Convergence level of 3D-RISM.
                }
                opt -val 0.0 {
                    Convergence level is 'low'.
                    Convergence threshold of 3D-RISM is greater than
                    @ref rism3d_conv_thr, when estimated energy error >> @ref conv_thr .
                    The threshold becomes @ref rism3d_conv_thr, when
                    estimated energy error is enough small.
                }
                opt -val 0.0<x<1.0 {
                    Convergence level is 'medium'.
                    Convergence threshold of 3D-RISM is intermediate value
                    between 'low' and 'high', where @ref rism3d_conv_level is mixing rate.
                }
                opt -val 1.0 {
                    Convergence level is 'high'.
                    Convergence threshold of 3D-RISM is always @ref rism3d_conv_thr .
                }
            }
        }

        var rism3d_planar_average -type LOGICAL {
            info {
                If .TRUE., planar averages of solvent densities and potentials
                are calculated and written to 'prefix.rism1'.
                For 3D-RISM, default is .FALSE.
                For Laue-RISM, default is .TRUE.
            }
        }

        var laue_nfit -type INTEGER {
            default { 4 }
            info {
                The number of z-grid points for the polynomial fit along the cell edge.
                This is only for Laue-RISM.
            }
        }

        var laue_expand_right -type REAL {
            default { -1.0 }
            info {
                If positive value, set the ending position offset [in a.u.]
                of the solvent region on right-hand side of the unit cell,
                measured relative to the unit cell edge.
                (the solvent region ends at z = + [L_z/2 + @ref laue_expand_right].)
                This is only for Laue-RISM.
            }
        }

        var laue_expand_left -type REAL {
            default { -1.0 }
            info {
                If positive value, set the ending position offset [in a.u.]
                of the solvent region on left-hand side of the unit cell,
                measured relative to the unit cell edge.
                (the solvent region ends at z = - [L_z/2 + @ref laue_expand_left].)
                This is only for Laue-RISM.
            }
        }

        var laue_starting_right -type REAL {
            default { 0.0 }
            info {
                Set the starting position [in a.u.] of the solvent region
                on right-hand side of the unit cell. Then the solvent region is
                defined as [ @ref laue_starting_right , L_z/2 + @ref laue_expand_right ],
                where distribution functions are finite.
                This is only for Laue-RISM.
            }
        }

        var laue_starting_left -type REAL {
            default { 0.0 }
            info {
                Set the starting position [in a.u.] of the solvent region
                on left-hand side of the unit cell. Then the solvent region is
                defined as [ -L_z/2 - @ref laue_expand_left , @ref laue_starting_left ],
                where distribution functions are finite.
                This is only for Laue-RISM.
            }
        }

        var laue_buffer_right -type REAL {
            default {
                8.0 if @ref laue_expand_right > 0.0;
               -1.0 if @ref laue_expand_right <= 0.0
            }
            info {
                If positive value, set the buffering length [in a.u.]
                of the solvent region on right-hand side of the unit cell.
                Then correlation functions are defined inside of
                [ @ref laue_starting_right - @ref laue_buffer_right , L_z/2 + @ref laue_expand_right ].
                This is only for Laue-RISM.
            }
        }

        var laue_buffer_left -type REAL {
            default {
                8.0 if @ref laue_expand_left > 0.0;
               -1.0 if @ref laue_expand_left <= 0.0
            }
            info {
                If positive value, set the buffering length [in a.u.]
                of the solvent region on left-hand side of the unit cell.
                Then correlation functions are defined inside of
                [ -L_z/2 - @ref laue_expand_left , @ref laue_starting_left + @ref laue_buffer_left ].
                This is only for Laue-RISM.
            }
        }

        var laue_both_hands -type LOGICAL {
            default { .FALSE. }
            info {
                If .TRUE., you can set different densities
                to the solvent regions of right-hand side and left-hand side.
                See @ref SOLVENTS card.
            }
        }

        var laue_wall -type CHARACTER {
            default { 'auto' }
            options {
                info {
                    Set the repulsive wall with (1/r)^12 term of Lennard-Jones potential.
                    This is only for Laue-RISM.
                }
                opt -val 'none' {
                    The repulsive wall is not defined.
                }
                opt -val 'auto' {
                    The repulsive wall is defined, whose edge position is set automatically.
                    One does not have to set @ref laue_wall_z (the edge position).
                }
                opt -val 'manual' {
                    The repulsive wall is defined, whose edge position is set manually.
                    One have to set @ref laue_wall_z (the edge position).
                }
            }
        }

        var laue_wall_z -type REAL {
            default { 0.0 }
            info {
                Set the edge position [in a.u.] of the repulsive wall.
                If @ref laue_expand_right > 0.0, the repulsive wall is defined on [ -inf , @ref laue_wall_z ].
                If @ref laue_expand_left > 0.0, the repulsive wall is defined on [ @ref laue_wall_z , inf ].
                This is only for Laue-RISM and @ref laue_wall == 'manual' .
            }
        }

        var laue_wall_rho -type REAL {
            default { 0.01 }
            info {
                The density (1/bohr^3) of the repulsive wall.
                This is only for Laue-RISM and @ref laue_wall /= 'none' .
            }
        }

        var laue_wall_epsilon -type REAL {
            default { 0.1 }
            info {
                The Lennard-Jones potential of the repulsive wall.
                Here, you can set the parameter 'epsilon' (kcal/mol).
                This is only for Laue-RISM and @ref laue_wall /= 'none' .
            }
        }

        var laue_wall_sigma -type REAL {
            default { 4.0 }
            info {
                The Lennard-Jones potential of the repulsive wall.
                Here, you can set the parameter 'sigma' (Angstrom).
                This is only for Laue-RISM and @ref laue_wall /= 'none' .
            }
        }

        var laue_wall_lj6 -type LOGICAL {
            default { .FALSE. }
            info {
                If .TRUE., the attractive term -(1/r)^6 of Lennard-Jones potential is added.
                This is only for Laue-RISM and @ref laue_wall /= 'none' .
            }
        }
    }



    #
    # card ATOMIC_SPECIES
    #
    card ATOMIC_SPECIES {
        syntax {
            table atomic_species {
                rows -start 1 -end ntyp {
                    col X -type CHARACTER {
                        info { 
                            label of the atom. Acceptable syntax:
                            chemical symbol X (1 or 2 characters, case-insensitive) 
                            or chemical symbol plus a number or a letter, as in
                            "Xn" (e.g. Fe1) or "X_*" or "X-*" (e.g. C1, C_h;
                            max total length cannot exceed 3 characters)
                        }
                    }
                    col Mass_X -type REAL {
                        info {
                            mass of the atomic species [amu: mass of C = 12]
                            Used only when performing Molecular Dynamics run
                            or structural optimization runs using Damped MD.
                            Not actually used in all other cases (but stored
                            in data files, so phonon calculations will use
                            these values unless other values are provided)
                        }
                    }
                    col PseudoPot_X -type CHARACTER {
                        info {
                            File containing PP for this species.
            
                            The pseudopotential file is assumed to be in the new UPF format.
                            If it doesn't work, the pseudopotential format is determined by
                            the file name:
                            
                            *.vdb or *.van     Vanderbilt US pseudopotential code
                            *.RRKJ3            Andrea Dal Corso's code (old format)
                            none of the above  old PWscf norm-conserving format
                        }
                    }
                }
            }
        }
    }

    #
    # card ATOMIC_POSITIONS
    #

    card ATOMIC_POSITIONS {

        flag atompos_unit -use optional {
            enum { alat | bohr | angstrom | crystal | crystal_sg }
            default { (DEPRECATED) alat }
            options {
                info {
                    Units for ATOMIC_POSITIONS:
                }
                opt -val alat {
                    atomic positions are in cartesian coordinates, in
                    units of the lattice parameter (either celldm(1) 
                    or A). If no option is specified, 'alat' is assumed;
                    not specifying units is DEPRECATED and will no
                    longer be allowed in the future
                }
                
                opt -val bohr {
                    atomic positions are in cartesian coordinate, 
                    in atomic units (i.e. Bohr radii)
                }
                
                opt -val angstrom {
                    atomic positions are in cartesian coordinates, in Angstrom
                }
                
                opt -val crystal {
                    atomic positions are in crystal coordinates, i.e.
                    in relative coordinates of the primitive lattice
                    vectors as defined either in card @ref CELL_PARAMETERS
                    or via the ibrav + celldm / a,b,c... variables
                }

                opt -val crystal_sg {
                    atomic positions are in crystal coordinates, i.e.
                    in relative coordinates of the primitive lattice.
                    This option differs from the previous one because
                    in this case only the symmetry inequivalent atoms
                    are given. The variable @ref space_group must indicate
                    the space group number used to find the symmetry
                    equivalent atoms. The other variables that control 
                    this option are uniqueb, origin_choice, and 
                    rhombohedral.
                }
            }
        }

        choose {
            when -test "calculation == 'bands' OR calculation == 'nscf'" {
                message { 
                    Specified atomic positions will be IGNORED and those from the
                    previous scf calculation will be used instead !!!
                }
            }
            otherwise  {
                syntax {
                    
                    table atomic_coordinates {
                        rows -start 1 -end nat {
                            col X -type CHARACTER {
                                info { label of the atom as specified in @ref ATOMIC_SPECIES }
                            }

                            colgroup -type REAL {
                                info { 
                                    atomic positions 
                                    
                                    NOTE: each atomic coordinate can also be specified as a simple algebraic expression.
                                          To be interpreted correctly expression must NOT contain any blank
                                          space and must NOT start with a "+" sign. The available expressions are:
                                          
                                            + (plus), - (minus), / (division), * (multiplication), ^ (power)

                                          All numerical constants included are considered as double-precision numbers;
                                          i.e. 1/2 is 0.5, not zero. Other functions, such as sin, sqrt or exp are
                                          not available, although sqrt can be replaced with ^(1/2). 

                                          Example:
                                                C  1/3   1/2*3^(-1/2)   0
                                        
                                          is equivalent to

                                                C  0.333333  0.288675  0.000000 

                                          Please note that this feature is NOT supported by XCrysDen (which will
                                          display a wrong structure, or nothing at all).         

                                          When atomic positions are of type crystal_sg coordinates can be given 
                                          in the following four forms (Wyckoff positions):
                                             C  1a 
                                             C  8g   x 
                                             C  24m  x y 
                                             C  48n  x y z
                                          The first form must be used when the Wyckoff letter determines uniquely 
                                          all three coordinates, forms 2,3,4 when the Wyckoff letter and 1,2,3
                                          coordinates respectively are needed.
                                          
                                          The forms:
                                             C 8g  x  x  x
                                             C 24m x  x  y 
                                          are not allowed, but
                                             C x x x
                                             C x x y
                                             C x y z
                                          are correct.
                                }
                                col x
                                col y
                                col z
                            }
                            
                            optional {
                                colgroup -type INTEGER {                                                
                                    info {
                                        component i of the force for this atom is multiplied by if_pos(i),
                                        which must be either 0 or 1.  Used to keep selected atoms and/or
                                        selected components fixed in MD dynamics or
                                        structural optimization run.
                                           
                                        With crystal_sg atomic coordinates the constraints are copied in all equivalent
                                        atoms.
                                    }
                                    default { 1 }
                                    
                                    col if_pos(1)
                                    col if_pos(2)
                                    col if_pos(3)
                                }
                            }
                        }
                    }
                }

            }
        }
    }    


    #
    # K_POINTS
    #
    card K_POINTS {
        flag kpoint_type -use optional {
            enum { tpiba | automatic | crystal | gamma | tpiba_b | crystal_b | tpiba_c | crystal_c }
            default { tbipa }
            options {
                info {
                    K_POINTS options are:
                }
                opt -val tpiba    {
                    read k-points in cartesian coordinates, 
                    in units of 2 pi/a (default)
                }

                opt -val automatic {
                    automatically generated uniform grid of k-points, i.e,
                    generates ( nk1, nk2, nk3 ) grid with ( sk1, sk2, sk3 ) offset.
                    nk1, nk2, nk3 as in Monkhorst-Pack grids
                    k1, k2, k3 must be 0 ( no offset ) or 1 ( grid displaced
                    by half a grid step in the corresponding direction ) 
                    BEWARE: only grids having the full symmetry of the crystal
                            work with tetrahedra. Some grids with offset may not work.
                }
 
                opt -val crystal  {
                    read k-points in crystal coordinates, i.e. in relative
                    coordinates of the reciprocal lattice vectors
                }

                opt -val gamma {
                    use k = 0 (no need to list k-point specifications after card)
                    In this case wavefunctions can be chosen as real, 
                    and specialized subroutines optimized for calculations
                    at the gamma point are used (memory and cpu requirements 
                    are reduced by approximately one half).
                }

                opt -val tpiba_b {
                    Used for band-structure plots.
                    See Doc/brillouin_zones.pdf for usage of BZ labels;
                    otherwise, k-points are in units of  2 pi/a. 
                    nks points specify nks-1 lines in reciprocal space.
                    Every couple of points identifies the initial and
                    final point of a line. pw.x generates N intermediate
                    points of the line where N is the weight of the first point.
                }

                opt -val crystal_b {
                    As tpiba_b, but k-points are in crystal coordinates.
                    See Doc/brillouin_zones.pdf for usage of BZ labels.
                }

                opt -val tpiba_c {
                    Used for band-structure contour plots. 
                    k-points are in units of  2 @i pi/a. nks must be 3.
                    3 k-points k_0, k_1, and k_2 specify a rectangle 
                    in reciprocal space of vertices k_0, k_1, k_2, 
                    k_1 + k_2 - k_0: k_0 + \alpha (k_1-k_0)+
                    \beta (k_2-k_0) with 0 <\alpha,\beta < 1. 
                    The code produces a uniform mesh n1 x n2 
                    k points in this rectangle. n1 and n2 are 
                    the weights of k_1 and k_2. The weight of k_0
                    is not used.
                }

                opt -val crystal_c {
                    As tpiba_c, but k-points are in crystal coordinates.
                }
            }
        }

        choose {
            when -test "tpiba  OR  crystal  OR  tpiba_b  OR  crystal_b OR tpiba_c OR crystal_c" {
                syntax -flag {tpiba | crystal | tpiba_b | crystal_b | tpiba_c | crystal_c } {
                    line { 
                        var nks -type INTEGER {
                            info {Number of supplied special k-points.}
                        }
                    }
                    table kpoints {
                        rows -start 1 -end nks {
                            colgroup -type REAL {
                                col xk_x 
                                col xk_y
                                col xk_z
                                col wk
                                info {
                                    Special k-points (xk_x/y/z) in the irreducible Brillouin Zone
                                    (IBZ) of the lattice (with all symmetries) and weights (wk)
                                    See the literature for lists of special points and
                                    the corresponding weights.
                                    
                                    If the symmetry is lower than the full symmetry
                                    of the lattice, additional points with appropriate
                                    weights are generated. Notice that such procedure
                                    assumes that ONLY k-points in the IBZ are provided in input

                                    In a non-scf calculation, weights do not affect the results.
                                    If you just need eigenvalues and eigenvectors (for instance,
                                    for a band-structure plot), weights can be set to any value
                                    (for instance all equal to 1).
                                }
                            }
                        }
                    }
                }               
            }
            elsewhen -test "automatic" {
                syntax -flag {automatic} {
                    line {
                        vargroup -type INTEGER {
                            var nk1
                            var nk2
                            var nk3 
                            info { 
                                These parameters specify the k-point grid 
                                (nk1 x nk2 x nk3) as in Monkhorst-Pack grids. 
                            }
                        }
                        vargroup -type INTEGER {
                            var sk1
                            var sk2
                            var sk3
                            info {
                                The grid offsets;  sk1, sk2, sk3 must be 
                                0 ( no offset ) or 1 ( grid displaced by 
                                half a grid step in the corresponding direction ).
                            }
                        }
                    }
                }
            }
            elsewhen -test "gamma" {
                syntax -flag {gamma} {}
            }
        }
    }

    #
    # card ADDITIONAL_K_POINTS
    #
    card ADDITIONAL_K_POINTS {
        message {
            Optional card. Adds a list of k-points with zero weight, after those used for
            the scf calculation. When doing an EXX calculation and @ref nq1x, @ref nq2x or @ref nq3x are
            different from one, also include the required @b k+q points. The main use of this
            card is to do band plots with EXX.
        }
        flag additional_kpoints_type -use optional {
            enum { tpiba | crystal | tpiba_b | crystal_b | tpiba_c | crystal_c }
            default { tbipa }
            info {
                for the explanation of the K_POINTS' options, see @ref K_POINTS
            }
        }

        syntax -flag {tpiba | crystal | tpiba_b | crystal_b | tpiba_c | crystal_c } {
            line { 
                var nks_add -type INTEGER {
                    info {Number of supplied "additional" k-points.}
                }
            }
            table kpoints {
                rows -start 1 -end nks_add {
                    colgroup -type REAL {
                        col k_x 
                        col k_y
                        col k_z
                        col wk_
                        info {
                            for the respective explanation, see the @ref xk_x, @ref xk_y, @ref xk_z, @ref wk
                        }
                    }
                }               
            }
        }
    }
 

    #
    # CELL_PARAMETERS
    #
    card CELL_PARAMETERS {
        flag lattice_type -use optional {
            enum { alat | bohr | angstrom }
            info {
                Unit for lattice vectors; options are:
                
                @b 'bohr' / @b 'angstrom':
                                     lattice vectors in bohr-radii / angstrom.
                                     In this case the lattice parameter alat = sqrt(v1*v1).
                
                @b 'alat' / nothing specified:
                                     lattice vectors in units of the lattice parameter (either
                                     @ref celldm(1) or @ref A). Not specifying units is DEPRECATED
                                     and will not be allowed in the future.

                If neither unit nor lattice parameter are specified,
                'bohr' is assumed - DEPRECATED, will no longer be allowed
            }
        }
        
        label { 
            Optional card, must be present if @ref ibrav == 0, must be absent otherwise
        }
        
        syntax {
            table lattice {
                cols -start 1 -end 3 {
                    rowgroup -type REAL {
                        info { 
                            Crystal lattice vectors (in cartesian axis):
                                v1(1)  v1(2)  v1(3)    ... 1st lattice vector
                                v2(1)  v2(2)  v2(3)    ... 2nd lattice vector
                                v3(1)  v3(2)  v3(3)    ... 3rd lattice vector
                        }                   
                        row v1
                        row v2
                        row v3
                    }
                }
            }
        }
    }


    #
    # CONSTRAINTS
    #

    card CONSTRAINTS {
        label {
            Optional card, used for constrained dynamics or constrained optimizations
            (only if @ref ion_dynamics=='damp' or 'verlet', variable-cell excepted)
        }
        message {
            When this card is present the SHAKE algorithm is automatically used.
        }

        syntax {
            line {
                var nconstr -type INTEGER {
                    info { Number of constraints. }
                }
                
                optional {
                    var constr_tol -type REAL {
                        info { Tolerance for keeping the constraints satisfied. }
                    }
                }
            }
            
            table constraints_table {
                rows -start 1 -end nconstr {
                    col constr_type -type CHARACTER {
                        options {
                            info {
                                Type of constraint :
                            }
                            opt -val 'type_coord' {
                                constraint on global coordination-number, i.e. the
                                average number of atoms of type B surrounding the
                                atoms of type A. The coordination is defined by
                                using a Fermi-Dirac.
                                (four indexes must be specified).
                            }
                            opt -val 'atom_coord' {
                                constraint on local coordination-number, i.e. the
                                average number of atoms of type A surrounding a
                                specific atom. The coordination is defined by
                                using a Fermi-Dirac.
                                (four indexes must be specified).
                            }
                            opt -val 'distance' {
                                constraint on interatomic distance 
                                (two atom indexes must be specified).
                            }
                            opt -val 'planar_angle' {
                                constraint on planar angle 
                                (three atom indexes must be specified).
                            }
                            opt -val 'torsional_angle' {
                                constraint on torsional angle 
                                (four atom indexes must be specified).
                            }
                            opt -val 'bennett_proj' {
                                constraint on the projection onto a given direction
                                of the vector defined by the position of one atom
                                minus the center of mass of the others.
                                G. Roma, J.P. Crocombette: J. Nucl. Mater. 403, 32 (2010),
                                doi:10.1016/j.jnucmat.2010.06.001
                            }
                            opt -val 'potential_wall' {
                                (experimental) add a potential wall at the origin
                                normal to the the z-axis.
                            }
                        }
                    }
                    colgroup {
                        col constr(1)
                        col constr(2)
                        conditional {
                            col constr(3)
                            col constr(4)
                        }
                        info {
                            These variables have different meanings for different constraint types:

                            @b 'type_coord' :
                                           @i constr(1) is the first index of the atomic type involved
                                           @i constr(2) is the second index of the atomic type involved
                                           @i constr(3) is the cut-off radius for estimating the coordination
                                           @i constr(4) is a smoothing parameter

                            @b 'atom_coord' :
                                           @i constr(1) is the atom index of the atom with constrained coordination
                                           @i constr(2) is the index of the atomic type involved in the coordination
                                           @i constr(3) is the cut-off radius for estimating the coordination
                                           @i constr(4) is a smoothing parameter

                            @b 'distance' :
                                           atoms indices object of the constraint, as they appear in
                                           the @ref ATOMIC_POSITIONS card

                            @b 'planar_angle', @b 'torsional_angle' :
                                           atoms indices object of the constraint, as they appear in the
                                           @ref ATOMIC_POSITIONS card (beware the order)

                            @b 'bennett_proj' :
                                           @i constr(1) is the index of the atom whose position is constrained.
                                           @i constr(2:4) are the three coordinates of the vector that specifies
                                           the constraint direction.
                            @b 'potential_wall' :
                                           Formula is: External force = prefac * exponent * Exp(-exponent). Force is only applied
                                           on atoms within the cutoff.
                                           @i constr(1) is the prefactor
                                           @i constr(2) is the value in the exponent
                                           @i constr(3) is the cutoff (in a.u.)
                        }
                    }

                    optional {
                        col constr_target -type REAL {
                            info {
                                Target for the constrain ( angles are specified in degrees ).
                                This variable is optional.
                            }
                        }
                    }
                }
            }
        }
    }

    #
    # card OCCUPATIONS
    #
    card OCCUPATIONS {
        label { Optional card, used only if @ref occupations == 'from_input', ignored otherwise ! }
        syntax {
            table occupations_table {
                cols -start 1 -end nbnd {
                    row f_inp1 -type REAL {
                        info { 
                            Occupations of individual states (MAX 10 PER ROW). 
                            For spin-polarized calculations, these are majority spin states. 
                        }
                    }
                    conditional {
                        row f_inp2 -type REAL {
                            info {                              
                                Occupations of minority spin states (MAX 10 PER ROW)
                                To be specified only for spin-polarized calculations.
                            }
                        }
                    }
                }
            }
        }
    }    

    #
    # ATOMIC_VELOCITIES
    #
    card ATOMIC_VELOCITIES {
	flag atomvel_type -use optional {
	    enum {  a.u }
	    	}

	label { 
	    Optional card, reads velocities from standard input  
	}

	syntax {
                    table atomic_velocities {
                       rows -start 1 -end nat {
                            col V -type CHARACTER {
                                info { label of the atom as specified in ATOMIC_SPECIES }
                            }

                            colgroup -type REAL {
                                info { atomic velocities along x y and z direction}
                                col vx
                                col vy
                                col vz
                            }
                       }
                    }
	}
    }

    #
    # card ATOMIC_FORCES
    #

    card ATOMIC_FORCES { 
        label { Optional card used to specify external forces acting on atoms. }
        message {
            BEWARE: if the sum of external forces is not zero, the center of mass of
                    the system will move
        }
        syntax {
            table atomic_forces {
               rows -start 1 -end nat {
                  col X -type CHARACTER {
                     info { label of the atom as specified in @ref ATOMIC_SPECIES }
                 }
                  colgroup -type REAL {
                      info { external force on atom X (cartesian components, Ry/a.u. units)
                     }
                      col fx
                      col fy
                     col fz
                  }
              }
           }
        }
    }   
    
    #
    # card SOLVENTS
    #

    card SOLVENTS {
        flag solvents_unit -use optional {
            enum { 1/cell | mol/L | g/cm^3 }
            options {
                opt -val 1/cell {
                    solvent's densities are specified
                    as number of molecules in the unit cell.
                }
                opt -val mol/L {
                    solvent's densities are specified as molar concentrations.
                }
                opt -val g/cm^3 {
                    solvent's densities are in gram per cm^3.
                }
            }
        }

        label {
            Optional card, used only if @ref trism = .TRUE., ignored otherwise !
        }

        choose {
            when -test "laue_both_hands = .FALSE." {
                syntax {
                    table solvent {
                        rows -start 1 -end nsolv {
                            col X -type CHARACTER {
                                info {
                                    label of the solvent molecule.
                                }
                            }
                            col Density -type REAL {
                                info {
                                    density of the solvent molecule.
                                    if not positive value is set, density is read from MOL-file.
                                }
                            }
                            col Molecule -type CHARACTER {
                                info {
                                    MOL-file of the solvent molecule.
                                    in the MOL-file, molecular structure and some other data are written.
                                }
                            }
                        }
                    }
                }
            }
            elsewhen -test "laue_both_hands = .TRUE." {
                syntax {
                    table solvent {
                        rows -start 1 -end nsolv {
                            col X -type CHARACTER {
                                info {
                                    label of the solvent molecule.
                                }
                            }
                            col Density_Left -type REAL {
                                info {
                                    density of the solvent molecule in the left-hand side.
                                    if not positive value is set, density is read from MOL-file.
                                }
                            }
                            col Density_Right -type REAL {
                                info {
                                    density of the solvent molecule in the right-hand side.
                                    if not positive value is set, density is read from MOL-file.
                                }
                            }
                            col Molecule -type CHARACTER {
                                info {
                                    MOL-file of the solvent molecule.
                                    in the MOL-file, molecular structure and some other data are written.
                                }
                            }
                        }
                    }
                }
            }
        }
    }

    #
    # HUBBARD
    #
    card HUBBARD {
        set Hflags { atomic | ortho-atomic | norm-atomic | wf | pseudo }
        flag hubbard_type {
            enum $Hflags
            options {
                info {
                    @b HUBBARD options are:
                }
                opt -val atomic    {
                    use atomic orbitals (read from pseudopotential) to build the 
                    Hubbard projectors
                }

                opt -val ortho-atomic {
                    use Lowdin orthogonalized atomic orbitals. This option is 
                    recommended to be used whenever possible instead of atomic
                    because it allows to avoid applying Hubbard corrections twice
                    in the orbital overlap regions.
                }

                opt -val norm-atomic  {
                    Lowdin normalization of atomic orbitals. Keep in mind:
                    atomic orbitals are not orthogonalized in this case.
                    This is a "quick and dirty" trick to be used when
                    atomic orbitals from the pseudopotential are not
                    normalized (and thus produce occupation whose
                    value exceeds unity). 
                }

                opt -val wf {
                    use Wannier functions to built Hubbard projectors. 
                    The information about the Wannier functionas are read
                    from file "prefix".hub that must be generated using pmw.x
                    (see PP/src/poormanwannier.f90 for details).
                    Note: these are not maximally localized Wannier functions.
                    (see PP/examples/example05)
                }

                opt -val pseudo {
                    use the pseudopotential projectors. The charge density
                    outside the atomic core radii is excluded.
                    N.B.: for atoms with +U, a pseudopotential with the
                    all-electron atomic orbitals are required (i.e.,
                    as generated by ld1.x with lsave_wfc flag).
                }

                info {
                    NB: forces and stress are currently implemented only for the
                    'atomic', 'ortho-atomic', and 'pseudo' Hubbard projectors.
                }

                info {
                    Check Doc/Hubbard_input.pdf to see how to specify Hubbard parameters
                    U, J0, J, B, E2, E3, V in the HUBBARD card.
                }

            }
        }

        choose {
            when -test "DFT+U" {
                syntax -flag $Hflags {

                    # atom-1 specs
                    
                    line {
                        vargroup -type {CHARACTER-LITERAL, CHARACTER, REAL} {
                            keyword U
                            var label(1)-manifold(1)
                            var u_val(1)
                            info {
                                @b Syntax:
                                  @b U @i {label-manifold u_val}

                                @b Where:
                                @b U        = string constant "U"; indicates the specs for the @i U parameter will be given
                                @i label    = label of the atom (as defined in @ref ATOMIC_SPECIES)
                                @i manifold = specs of the manifold (e.g., 3d, 2p...)
                                @i u_val    = value of the @i U parameter (in eV)
                                    
                                @b Example:
                                HUBBARD (ortho-atomic)
                                  U Mn-3d 5.0
                                  U Ni-3d 6.0
                            }                                                                
                        }
                    }
                    line {
                        conditional {
                            vargroup -type {CHARACTER-LITERAL, CHARACTER, REAL} {
                                keyword J0
                                var label(1)-manifold(1)
                                var j0_val(1)
                                info {
                                    @b Remark: specs of @b J0 parameters are optional
                                    
                                    @b Syntax:
                                      @b J0 @i {label-manifold j0_val}
                                        
                                    @b Where:
                                    @b J0       = string constant "J0"; indicates the specs for the @i J0 parameter will be given
                                    @i label    = label of the atom (as defined in @ref ATOMIC_SPECIES)
                                    @i manifold = specs of the manifold (e.g., 3d, 2p...)
                                    @i j0_val   = value of the @i J0 parameter (in eV)
                                    
                                    @b Example:
                                      HUBBARD (ortho-atomic)
                                      U  Mn-3d 5.0
                                      J0 Mn-3d 1.0
                                      U  Ni-3d 6.0
                                      J0 Ni-3d 1.2
                                }
                            }                                
                        }
                    }
                        
                    # print ". . ." on a separate line
                        
                    line { etc }
                    
                    line {
                        vargroup -type {CHARACTER-LITERAL, CHARACTER, REAL} {
                            keyword U
                            var label(n)-manifold(n)
                            var u_val(n)
                        }
                    }
                    line {
                        conditional {
                            vargroup -type {CHARACTER-LITERAL, CHARACTER, REAL} {
                                keyword J0
                                var label(n)-manifold(n)
                                var j0_val(n)
                            }                                
                        }
                    }                        
                }
            }
            
            elsewhen -test "DFT+U+J" { 
                syntax -flag $Hflags {
                    
                    # atom-1 specs
                    
                    line {
                        vargroup -type {CHARACTER, CHARACTER, REAL} {
                            var paramType(1)
                            var label(1)-manifold(1)
                            var paramValue(1)
                            info {
                                @b Syntax of the line:
                                
                                  @i {paramType label-manifold paramValue}

                                @b Where:
                                @i paramType  = character describing the type of Hubbard parameter 
                                             allowed values: @b U, @b J and either @b B (for d-orbitals) or @b E2 and @b E3 (for f-orbitals)
                                @i label      = label of the atom (as defined in @ref ATOMIC_SPECIES)
                                @i manifold   = specs of the manifold (e.g., 3d, 2p...)
                                @i paramValue = value of the parameter (in eV)

                                @b Example:
                                  HUBBARD (ortho-atomic)
                                  U Mn-3d 5.0
                                  J Mn-3d 1.0
                                  B Mn-3d 1.1
                                  U Ni-3d 6.0
                                  J Ni-3d 1.2
                                  B Ni-3d 1.3
                            }                        
                        }
                    }
                                            
                    # print ". . ." on a separate line
                    line { etc }
                    
                    # atom-n specs
                    
                    line {
                        vargroup -type {CHARACTER, CHARACTER, REAL} {
                            var paramType(n)
                            var label(n)-manifold(n)
                            var paramValue(n)
                        }
                    }
                }
            }
            elsewhen -test "DFT+U+V" { 
                syntax -flag $Hflags {
                    line {
                        vargroup -type {CHARACTER, REAL} {
                            keyword U
                            var label(I)-manifold(I)
                            var u_val(I)
                            info {
                                @b Syntax of the line:
                                
                                  @b U @i {label-manifold u_val}

                                @b Where:
                                @b U        = string constant "U"; indicates the specs for the @i U parameter will be given
                                @i label    = label of the atom (as defined in @ref ATOMIC_SPECIES)
                                @i manifold = specs of the manifold (e.g., 3d, 2p...)
                                @i u_val    = value of the @i U parameter (in eV)
                            }
                        }
                    }

                    line {
                        conditional {
                            vargroup -type {CHARACTER, REAL} {
                                keyword J0
                                var label(I)-manifold(I)
                                var j0_val(I)
                                info {
                                    @b Remark: specs of @b J0 parameters are optional
                                        
                                    @b Syntax of the line:
                                    
                                      @b J0 @i {label(I)-manifold(I) j0_val(I)}
                                        
                                    @b Where:
                                    @b J0       = string constant "J0"; indicates the specs for the @i J0 parameter will be given
                                    @i label    = label of the atom (as defined in @ref ATOMIC_SPECIES)
                                    @i manifold = specs of the manifold (e.g., 3d, 2p...)
                                    @i j0_val   = value of the @i J0 parameter (in eV) 
                                }
                            }
                        }
                    }
                        

                    line {
                        vargroup -type {CHARACTER, CHARACTER, INTEGER, INTEGER, REAL} {
                            keyword V
                            var label(I)-manifold(I)
                            var label(J)-manifold(J)
                            var I
                            var J
                            var v_val(I,J)
                            info {
                                @b Syntax of the line:
                                
                                  @b V @i {label(I)-manifold(J) label(J)-manifold(J) I J v_val(I,J)}

                                @b Where:
                                @b V           = string constant "V"; indicates the specs for the @i V parameter will be given
                                @i label(I)    = label of the atom @i I (as defined in @ref ATOMIC_SPECIES)
                                @i manifold(I) = specs of the manifold for atom @i I (e.g., 3d, 2p...)
                                @i label(J)    = label of the atom @i J (as defined in @ref ATOMIC_SPECIES)
                                @i manifold(J) = specs of the manifold for atom @i J (e.g., 3d, 2p...)
                                @i I           = index of the atom @i I
                                @i J           = index of the atom @i J
                                @i v_val(I,J)  = value of the @i V parameter for the atom pair @i I,J (in eV)

                                @b Example:
                                  HUBBARD (ortho-atomic)
                                  U Co-3d 7.70
                                  V Co-3d O-2p 1 19 0.75
                                  V Co-3d O-2p 1 46 0.75
                                  V Co-3d O-2p 1 43 0.75
                                  V Co-3d O-2p 1 54 0.75
                                  V Co-3d O-2p 1 11 0.75
                                  V Co-3d O-2p 1 22 0.75
                            }
                        }
                    }
                    
                    line { etc }
                    
                    line {
                        vargroup -type {CHARACTER, REAL} {
                            keyword U
                            var label(N)-manifold(N)
                            var u_val(N)
                        }
                    }

                    line {
                        conditional {
                            vargroup -type {CHARACTER, REAL} {
                                keyword J0
                                var label(N)-manifold(N)
                                var j0_val(N)
                            }
                        }
                    }
                        

                    line {
                        vargroup -type {CHARACTER, REAL} {
                            keyword V
                            var label(N)-manifold(N)
                            var label(M)-manifold(M)
                            var N
                            var M
                            var v_val(N,M)
                        }
                    }
                }
            }
        }
    }
   ###
}
