.. module:: ase.calculators.openmx

======
OpenMX
======

Introduction
============

OpenMX_ (Open source package for Material eXplorer) is a software
package for nano-scale material simulations based on density functional
theories (DFT), norm-conserving pseudopotentials, and pseudo-atomic
localized basis functions. This interface makes it possible to use
OpenMX_ as a calculator in ASE, and also to use ASE as a post-processor
for an already performed OpenMX_ calculation.

You should import the OpenMX calculator when writing ASE code.
To import into your python code,

.. code-block:: python

  from ase.calculators.openmx import OpenMX

Then you can define a calculator object and set it as the calculator of an
atoms object:

.. code-block:: python

  calc = OpenMX(**kwargs)
  atoms.calc = calc

Environment variables
=====================

The environment variable :envvar:`ASE_OPENMX_COMMAND` must point to that file.

A directory containing the pseudopotential directories :file:`VPS`, and it
is to be put in the environment variable :envvar:`OPENMX_DFT_DATA_PATH`.

Set both environment variables in your shell configuration file:

.. highlight:: bash

::

  $ export OPENMX_DFT_DATA_PATH=/openmx/DFT_DATA13
  $ export ASE_OPENMX_COMMAND='openmx'

.. highlight:: python

Keyword Arguments of OpenMX objects
===================================

kwargs are categorized by integer, float, string, boolean, tuple and matrix.
Integer keyword argument(kwargs) is argument have integer value. For example,

.. code-block:: python

  calc = OpenMX(scf_maxiter = 500, md_maxiter = 100, ...)

as you can see, in ASE, standard format is to use lowercase alphabet. To
follow this rule, every OpenMX keyword are changed to standard format.
Further more, since python dose not allow dot(.) as a variable name. Every dot
is changed to underbar(_). For example,::

  scf.maxIter -> scf_maxiter
  MD.maxIter  -> md_maxiter

Some variable such like atoms_number or species_number, which can be guessed
easily, are automatically generated by the given information from atoms object.
Float keywords are keyword have float type. Standard rules are applied like
integer keywords. You can specify OpenMX float keywords by specifying,

.. code-block:: python

  from ase.units import Ha
  calc = OpenMX(scf_criterion = 1e-6, energy_cutoff = 150 * Ry, ...)

scf_criterion is correspond to ``scf.criterion``. The other argument
``energy_cutoff`` is a standard parameter format referencing GPAW. It acts same
as scf_energycutoff. However, units are different. ASE uses standard energy
unit as eV, and OpenMX scf.energycutoff uses the Rydburg unit. Thus, one have
to specify the unit explicitly. This keyword and unit thing is applied to every
keyword. For example, command above will be same as specifying,

.. code-block:: python

  from ase.units import Ry
  calc = OpenMX(scf_criterion = 1e-6, scf_energycutoff = 150, ...)

energy_cutoff is correspond to ``scf_energycutoff``. But it is written in
standard format. More standard parameters are specified in
calculators/openmx/parameter.py. Bool keywords have boolean format, True or
False. This will be translated On or Off when writing input file. For example,

.. code-block:: python

  calc = OpenMX(scf_restart = True, scf_spinorbit_coupling = True, ...)

String keywords are keyword have string format. For example,

.. code-block:: python

  calc = OpenMX(scf_xctype = 'LDA', xc = 'PBE', ...)

Both keyword arguments specifying exchange correlation we want to calculate.
Left is written in OpenMX format and the right one is written in standard
format. If calculator see contradicting arguments, it will use standard keyword
``xc`` and ``scf_xctype`` will be ignored. Tuple keywords are keyword that
have length 3. For example,

.. code-block:: python

  calc = OpenMX(scf_kgrid = (4, 4, 4), ...)

Matrix keywords are keyword that have special format in OpenMX. For example,::

  <Definition.of.Atomic.Species
    H   H5.0-s2p2d1      H_CA13
    C   C5.0-s2p2d2      C_CA13
  Definition.of.Atomic.Species>

This is typical example of matrix keyword. User can specify explicitly this
argument using python list object. For example,

.. code-block:: python

  calc = OpenMX(definition_of_atomic_species=[['H','H5.0-s2p2d1','H_CA13'],
                                              ['C','C5.0-s2p2d2','C_CA13']])

although user can specify it explicitly, most of the case, this matrix Arguments
are generated automatically by the information using Atoms object. information
such like cutoff radius or...

See the official `OpenMX`_ manual for more detail.

.. _OpenMX: http://www.openmx-square.org

The default setting used by the OpenMX interface is

.. autoclass:: OpenMX

Below follows a list with a selection of standard parameters

================= ======= ========== ===============================
keyword           type    default    openmx_keyword
================= ======= ========== ===============================
``xc``            ``str`` `LDA`      'scf.XcType'
``maxiter``       ``int`` 100        'scf.maxIter'
``energy_cutoff`` ``flt`` 150\*Ry    'scf.energycutoff'
``kpts``          ``tpl`` (4, 4, 4)  'scf.Kgrid'
``kpts``          ``lst`` None       'Band.kpath'
``eigensolver``   ``str`` 'Band'     'scf.EigenvalueSolver'
``spinpol``       ``bol`` None       'scf.SpinPolarization'
``convergence``   ``flt`` 1e-6\*Ha   'scf.criterion'
``external``      ``lst`` None       'scf.Electric.Field'
``mixer``         ``str`` 'Rmm-Diis' 'scf.Mixing.Type'
``charge``        ``flt`` None       'scf.system.charge'
``smearing``      ``lst`` None       'scf.Electronic.Temperature'
================= ======= ========== ===============================

Calculator parameters
=====================

By default, calculator uses `openmx` arguments to run the code. However, single
node calculating is not a good way to run heavy DFT calculation. Parallel
computation is inevitable. In OpenMX calculator, user may choose the way to
run. There are two ways to excute the code. First is to use MPI and the second
is to use Plane Batch System. MPI method can be applied in general. To use it,
put the mpi dictionary as a kwargs. For example,

.. code-block:: python

  calc = OpenMX(mpi={'processes':20, 'threads':3}, ...)

Similarly, You can use PBS method by specifying kwargs,


.. code-block:: python

  calc = OpenMX(pbs={'processes':20, 'threads':3, 'walltime':'100:00:00'}, ...)

.. note::

  PBS method will not be applied unless you have schedular specifically
  supports PBS. If your schedular support `qsub` command and `qlist` command,
  you may check pbs command is possible to use.

Below follows a list with a selection of calculator parameters

================= ======= ======= =============================================
keyword           type    default description
================= ======= ======= =============================================
``label``         ``str`` 'test'  It will define the name of file. Also,
                                  'System.Name' and 'System.CurrentDirectory'
                                  will be defined by the label.
``restart``       ``str`` None    Restart the calculation. While restarting,
                                  'scf.retart' will be changed to 'On',
                                  'scf.fixed.grid' and 'MD.Current.Iter' will
                                  be readed from '.dat#'. Make sure '_rst' file
                                  have same name with 'System.Name'.
``mpi``           ``dic`` None    Dictionary contains the key ``processes`` and
                                  ``threads``. If user specify this variable,
                                  calculator will calculate using
                                  ``mpirun -np (processes) -t (threads) ...``.
``pbs``           ``dic`` None    Dictionary contains the key ``processes``,
                                  ``threads`` and ``walltime``. If user specify
                                  this value, caluculator will execute
                                  ``qsub -l ppn=(procesees) -l walltime=
                                  (walltime) ...``
``debug``         ``bol`` False   Boolean value which shows the position of
                                  code are being excuted
``nohup``         ``bol`` True    If it changes to False, calculation log will
                                  be printed
``data_path``     ``dic`` None    Correspond to pseudo potential path
                                  ``DATA.PATH``. If it is None, check there is
                                  environment variable 'OPENMX_DFT_DATA_PATH'.
``dft_data_dict`` ``dic`` None    A specification of the atomic orbital basis
                                  to be used for each atomic species e.g)
                                  ``dft_data_dict = {'C': {'cutoff radius':
                                  8 * ase.units.Bohr, 'orbitals used': [1,1]}}``
                                  means that for carbon species, the spatial
                                  extent of the atomic orbitals used is limited
                                  to 8 Bohr and one level of s orbitals are
                                  used and one level of p orbitals are used.
                                  The default value for this is specified in
                                  the default_settings.py file, namely,
                                  default_dictionary.
================= ======= ======= =============================================


Density of States
=================

================= ========= ============== ============================
keyword           type      default value  description
================= ========= ============== ============================
``dos_fileout``   ``str``   False          if True, density of states
                                           will be calculated for an energy
                                           range given by dos_erange.
``dos_erange``    ``tuple`` (-25, 20)      Gives the density of states
                                           energy range in eV
``dos_kgrid``     ``tuple`` None           defaults to the value given by kpts.
================= ========= ============== ============================


Methods of OpenMX objects
=========================

get_dos(kwargs):
key word arguments:

====================  =========  ===============================================
keyword               type       description
====================  =========  ===============================================
``energy``            float      The total energy of the system in eV.
``forces``            float      An array of tuples describing the forces on an
                                 each atom in eV / Ang. e.g. array([(atom1Fx,
                                 atom1Fy, atom1Fz), (atom2Fx, atom2Fy, atom2Fz)]
                                 'dipole': A tuple describing the total dipole
                                 moment in Debeye 'chemical_potential':
                                 The chemical potential of the system in eV
``atoms``             atom       Needs to be specified if system hasn't been
                                 calculated with the parameter,
                                 dos_fileout=True.
``erange``            tuple      e.g. (min_energy, max_energy) with the energy
                                 quoted in eV. If not specified, this will be
                                 the same as the dos_erange parameter of the
                                 calculator.
``method``            str        'Tetrahedron' or 'Gaussian'. The method of
                                 calculating the density of states from the
                                 eigenvalues and eigenvectors.
``gaussian_width``    str        If method='Gaussian', then the width of
                                 broadening needs to be specified in eV. The
                                 default is 0.1eV.
spin_polarization     bool       If True, each graph plotted will split
                                 horizontally with spin up above the x-axis and
                                 spin down below the x-axis. If not specified,
                                 this will be True for spin polarized systems
                                 and False for spin non-polarized systems. You
                                 may specify this as False for a spin_polarized
                                 system.
``density``           bool       If True, the (partial) density of states will
                                 be plotted. The default is True.
cum                   bool       If True, the cumulative number of states from
                                 the minimum energy specified in the dos_erange
                                 parameter will be plotted. The default is False
``fermi_level``       bool       If True, the region of the graph below the
                                 fermi level will be highlighted in yellow.
                                 The default is True.
``file_format``       str        If specified, instead of opening a window to
                                 the view the plot, the plot will be saved in a
                                 specified format. The following formats are
                                 available: 'pdf', 'png', 'ps', 'eps' or 'svg'.
``pdos``              bool       If True, the partial density of states will be
                                 calculated and plotted for the atoms specified
                                 in atom_index_list and their orbitals specified
                                 by orbital_list. If False, the total density of
                                 states for the whole system will be calculated
                                 and plotted.
``atom_index_list``   list       if pdos=True, a list of reference numbers of
                                 the atoms to have their partial density of
                                 states calculated and plotted. If not
                                 specified, only the first atom will be used.
``orbital_list``      list       if pdos=True, a list of all the orbitals to
                                 have their partial density of states plotted.
                                 If is in the list, the combined partial
                                 density of states for each desired atom will be
                                 plotted. If 's', 'p', 'd' or 'f' is in the list
                                 then all the corresponding orbitals of that
                                 type will be plotted. If the list is not
                                 specified, then only the combined density of
                                 states will be plotted.
====================  =========  ===============================================
