.. module:: ase.calculators.espresso ======== Espresso ======== .. image:: ../../static/espresso.png `Quantum ESPRESSO `_ (QE) is an integrated suite of Open-Source computer codes for electronic-structure calculations and materials modeling at the nanoscale. It is based on density-functional theory, plane waves, and pseudopotentials. The ASE calculator is an interface to the ``pw.x`` executable, however, input/output operations can be managed for other executables (see the Input/Output section below). Users interested to run calculation with other executables, can have a look in the ase ecosystem pages for other packages. Calculator ========== Basic usage ----------- Any calculation will need pseudopotentials for the elements involved. The default directory for the pseudopotential files can be set with the ``pseudo_dir`` parameter in the ASE configuration. Use ``ase info --calculators espresso`` Pseudopotential files can be passed to the calculator as a dictionary, where the keys are the element and values are the pseudopotential file names. The pseudopotential file names must be in the directory specified by the ``pseudo_dir`` parameter. .. code-block:: python pseudopotentials = {"Na": "na_pbe_v1.5.uspp.F.UPF", "Cl": "cl_pbe_v1.4.uspp.F.UPF"} A recommended list of pseudopotentials is the SSSP curated set, which can be found on `Materials Cloud `_. With the all of the above in mind, a simple calculation can be set up like so: .. code-block:: python from ase.build import bulk from ase.calculators.espresso import Espresso, EspressoProfile from ase.optimize import LBFGS rocksalt = bulk('NaCl', crystalstructure='rocksalt', a=6.0) # Pseudopotentials from SSSP Efficiency v1.3.0 pseudopotentials = {'Na': 'na_pbe_v1.5.uspp.F.UPF', 'Cl': 'cl_pbe_v1.4.uspp.F.UPF'} # Optionally create profile to override paths in ASE configuration: profile = EspressoProfile( command='/path/to/pw.x', pseudo_dir='/path/to/pseudopotentials' ) calc = Espresso(profile=profile, pseudopotentials=pseudopotentials) rocksalt.calc = calc rocksalt.get_potential_energy() # This will run a single point calculation opt = LBFGS(rocksalt) opt.run(fmax=0.005) # This will run a geometry optimization using ASE's LBFGS algorithm # Print lattice constant... print((8 * rocksalt.get_volume() / len(rocksalt)) ** (1.0 / 3.0)) The above example will run a single point calculation and a geometry optimization using default QE settings. In the next sections, we will describe how to customize the QE settings. Parameters ---------- The calculator will interpret most documented options for ``pw.x`` found at the `PW input description `_. Parameters must be passed in the ``input_data`` parameter, which is a dictionary , previously accepted kwargs keywords are now deprecated. The ``input_data`` dictionary can be used both in flat or nested format. In the flat format, keywords will be put into the correct section of the input file. In the nested format, the ``input_data`` dictionary will be used as is. Currently the nested format can be used to specify exotic input sections manually such as ``&FCP`` or ``&RISM``. All parameters must be given in QE units, usually Ry or atomic units in line with the documentation. ASE does not add any defaults over the defaults of QE. .. code-block:: python input_data = { 'system': {'ecutwfc': 60, 'ecutrho': 480}, 'disk_io': 'low', # Automatically put into the 'control' section } calc = Espresso( profile=profile pseudopotentials=pseudopotentials, tstress=True, # deprecated, put in input_data tprnfor=True, # deprecated, put in input_data input_data=input_data, ) Any ``FixAtoms`` or ``FixCartesian`` constraints are converted to Espresso constraints. Some parameters are used by ASE and have additional meaning: * ``kpts``, is used to specify the k-point sampling * If ``kpts`` is a tuple (or list) of 3 integers ``kpts=(int, int, int)``, it is interpreted as the dimensions of a Monkhorst-Pack grid. * If ``kpts`` is set to ``None``, only the Γ-point will be included and QE will use routines optimized for Γ-point-only calculations. Compared to Γ-point-only calculations without this optimization (i.e. with ``kpts=(1, 1, 1)``), the memory and CPU requirements are typically reduced by half. * If ``kpts`` is a dict, it will either be interpreted as a path in the Brillouin zone (see ase.dft.kpoints.bandpath) if it contains the 'path' keyword, otherwise it is converted to a Monkhorst-Pack grid (see ase.calculators.calculator.kpts2sizeandoffsets) * ``koffset=(0, 0, 0)`` set to 0 or 1 to displace the kpoint grid by a half cell in that direction. Also accepts ``True`` and ``False``. * ``kspacing=0.1`` sets the minimum distance between kpoints in reciprocal space. * ``nspin`` does not typically need to be specified by the user. If any atom has a magnetic moment, it is turned on automatically. Parallelism ----------- The above ``calc`` object will run the ``pw.x`` executable using the command specified by the ASE configuration. Parallelism can be customized by manually creating an ``EspressoProfile``. Currently there is no way to specify the parallelization keywords for QE, such as ``-nk``. This is a current limitation of the ASE calculator interface. .. code-block:: python profile = EspressoProfile( command='mpiexec -n 16 /path/to/pw.x', pseudo_dir='/path/to/pseudopotentials', ) # This will run 'mpirun -np 16 -v /path/to/pw.x' Input/Output ============ ASE can read and write input files for the espresso executables. The procedure depends on the executable. Each subsection will describe the procedure for each executable. pw.x ---- The ``pw.x`` executable is the main executable of the Quantum Espresso suite. ASE can fully read and write input files for this executable. This must be done by using the main :func:`ase.io.write` and :func:`ase.io.read` functions. The These two main functions are wrappers around the :func:`ase.io.espresso.write_espresso_in` and :func:`ase.io.espresso.read_espresso_out` functions. The former will write an input file for the ``pw.x`` executable, while the latter will read an input file and return Atoms object(s) with available results. .. autofunction:: ase.io.espresso.write_espresso_in :noindex: **Example:** .. code-block:: python from ase.io.espresso import write_espresso_in input_data = { 'calculation': 'relax', 'restart_mode': 'from_scratch', 'tprnfor': True, 'etot_conv_thr': 1e-5, 'forc_conv_thr': 1e-4, 'ecutwfc': 60, 'ecutrho': 480, 'input_dft': 'rpbe', 'vdw_corr': 'dft-d3', 'occupations': 'smearing', 'degauss': 0.01, 'smearing': 'cold', 'conv_thr': 1e-8, 'mixing_mode': 'local-TF', 'mixing_beta': 0.35, 'diagonalization': 'david', 'ion_dynamics': 'bfgs', 'bfgs_ndim': 6, 'startingwfc': 'random', } # This flat dictionary will be converted to a nested dictionary where, for example, "calculation" will be put into the "control" section write('pw.in', atoms, input_data=input_data, format='espresso-in') # Hubbard is not implemented in the write_espresso_in function, we can add it manually additional_cards = ['HUBBARD (ortho-atomic)', 'U Mn-3d 5.0', 'U Ni-3d 6.0'] write( 'pw_hubbard.in', atoms, input_data=input_data, additional_cards=additional_cards, format='espresso-in', ) .. autofunction:: ase.io.espresso.read_espresso_out :noindex: ph.x ---- As of January 2024, ``ph.x`` has custom read and write functions in ASE. The function :meth:`~ase.io.espresso.write_espresso_ph` can be used to write a Fortran namelist file for ``ph.x``. .. autofunction:: ase.io.espresso.write_espresso_ph **Example:** .. code-block:: python from ase.io.espresso import write_espresso_ph, read_espresso_ph input_data = { 'tr2_ph': 1.0e-12, 'prefix': 'pwscf', 'verbosity': 'high', 'ldisp': True, 'qplot': True, 'alpha_mix(1)': 0.1, } qpts = [(0.0, 0.0, 0.0), (0.5, 0.5, 0.5), (0.5, 0.5, 0.0), (0.0, 0.0, 0.5)] write_espresso_ph('input_ph.in', input_data, qpts=qpts) # Will automatically be built to nested format After running the calculation, the output can be read with the :meth:`~ase.io.espresso.read_espresso_ph` method. .. autofunction:: ase.io.espresso.read_espresso_ph **Example:** .. code-block:: python results = read_espresso_ph('ph.out') print(results[0]['qpoints']) # Will probably be (0, 0, 0) print(results[0]['freq']) # Eigenvalues of the dynamical matrix at the qpoint Other binaries -------------- Since January 2024, it is possible to use ASE to write input files for other QE executables. The :func:`ase.io.espresso.write_fortran_namelist` method will write a fortran namelist file, which can be read by QE executables. The list of currently implemented executable is available in :mod:`ase.io.espresso_namelist.keys` .. autofunction:: ase.io.espresso.write_fortran_namelist **Example:** .. code-block:: python from ase.io.espresso import Namelist from ase.io.espresso import write_fortran_namelist # input_data for pp.x, built automatically input_data = {'outdir': '/path/to/output', 'prefix': 'prefix', 'verbosity': 'high'} input_data = Namelist(input_data) input_data.to_nested(binary='pp') write_fortran_namelist('input_pp.in', input_data) # Alternatively, the input_data can be written manually # without the need to specify a binary input_data = { 'environ': { 'environ_type': 'water', ...} # In this case, the ``input_data`` is a nested dictionary # since ASE cannot guess the input sections for exotic executables additional_cards = [ 'EXTERNAL_CHARGES (bohr)', '-0.5 0. 0. 25.697 1.0 2 3', '-0.5 0. 0. 20.697 1.0 2 3' ] # This will be added at the end of the file write_fortran_namelist('environ.in', input_data) The :meth:`~ase.io.espresso.read_fortran_namelist` method will read a fortran namelist file and return a tuple, where the first element is the ``input_data`` dictionary and the second element is a list of additional cards at the end of the file. .. autofunction:: ase.io.espresso.read_fortran_namelist **Example:** .. code-block:: python from ase.io.espresso import read_fortran_namelist input_data, additional_cards = read_fortran_namelist('input_pp.in') print(input_data) print(additional_cards) You can use both of these methods to jungle between your favorite QE executables. Namelist Class ============== The Namelist class is a simple class to handle fortran namelist files. It derived from the dict class and is case case-insensitive. .. autoclass:: ase.io.espresso.Namelist Espresso Calculator Class ========================= .. autoclass:: ase.calculators.espresso.Espresso