Skip to main content
`Ctrl`+`K`

# 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,

    from ase.calculators.openmx import OpenMX

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

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

## Environment variables

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

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

Set both environment variables in your shell configuration file:

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

## 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,

    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,

    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,

    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,

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

String keywords are keyword have string format. For example,

    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,

    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,

    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.

The default setting used by the OpenMX interface is

class ase.calculators.openmx.OpenMX(restart=None, ignore_bad_restart_file=<object object>, label='./openmx', atoms=None, command=None, mpi=None, pbs=None, **kwargs)

  Calculator interface to the OpenMX code.

  File-IO calculator.

  command: str

    Command used to start calculation.

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,

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

Similarly, You can use PBS method by specifying kwargs,

    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.