openmx setup and basic calculation...

OpenMX Setup and Basic Calculation Tutorial

Mitchell Senger

Oregon State University - Department of Physics

Table of Contents OpenMX Setup and Basic Calculation Tutorial ....................................................................... 0

1 Preliminary Steps for ssh ...................................................................................................... 1

1.1 Installation of ssh software on Windows............................................................................. 1

1.2 Starting an ssh session with the 412 computers from Windows .......................................... 1

1.3 Installation of ssh software on Mac OS and opening an ssh session .................................... 4

2 OpenMX File Transfer .......................................................................................................... 5

2.1 Copy the files ..................................................................................................................... 5

2.2 Methane Test Calculation .................................................................................................. 6

3 Basic Parameter Input for Calculation of Bulk Material Properties ...................................... 7

3.1 Baseline Material Parameter Input .................................................................................... 7

3.2 The “SCF or Electronic System” and “MD or Geometry Optimization” Sections ................ 9

3.3 The “Band dispersion” Section ......................................................................................... 10

3.4 The “DOS and PDOS” Section ......................................................................................... 11

3.5 Save and Close ................................................................................................................. 11

4 Basic Calculations of Bulk Material Properties ................................................................... 12

4.1 Band Structure Calculation .............................................................................................. 12

4.2 Density of States Calculation ........................................................................................... 14

4.3 Lattice Visualization with XCrySDen .............................................................................. 17

5 Simulating your own materials............................................................................................ 19

5.1 Getting unit cell information from .CIF files for new materials ........................................ 19

5.2 Generating custom k-paths .............................................................................................. 21

Mitchell Senger OpenMX Tutorial Oregon State University

1 PH 575 02/20/2019

1 Preliminary Steps for ssh

OpenMX software runs on the computers in Weniger 412 in a Linux environment, but it is convienient to be able to run the software remotely from any machine. The best way to remotely access the software is through Secure Shell (ssh), and in order to do this on a Mac or Windows machine there are a few important steps that need to be taken first.

1.1 Installation of ssh software on Windows

Windows does have built in ssh software, but because we are interfacing with programs that have guis, it is best to use third party ssh software that makes that easy. To give windows the tools that it needs, you need to install putty (a simple ssh tool) Xming (a graphics environment for streaming Linux programs over ssh). Please follow the installation steps below.

Putty Installation –

Navigate your browser to http://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html and click the link for the .msi file that corresponds to your version of Windows, then follow the default installation.

Xming Installation –

Download Xming from Sourceforge here: https://sourceforge.net/projects/xming/files/latest/download. Again, follow the default installation options.

1.2 Starting an ssh session with the 412 computers from Windows

First, launch Xming. Xming will now run in the background. No windows will pop up, but you should see the Xming icon appear in the system tray.

Now that Xming is running, launch putty. In the Host Name box, enter the address of your user account at the Weniger 412 computer you will be using in the form [email protected], where ONID is your onid username and XX is the PC number assigned to you.

http://www.chiark.greenend.org.uk/%7Esgtatham/putty/latest.html

https://sourceforge.net/projects/xming/files/latest/download


2 PH 575 02/20/2019

Before opening the connection, navigate the category panel to Connection>SSH>X11, then check the box to “Enable X11 forwarding”.

Now click the “Open” button to connect to the 412 PC over ssh. You’ll get a security warning – just click “Yes” to allow the connection, then enter your assigned password. You should then see the command line for your PC appear.


3 PH 575 02/20/2019

As a quick check to see if the handshake between putty and Xming is working properly, in the command line, enter -

nautilus .&

If everything is functioning properly, you’ll see the Ubuntu file explorer pop up on screen.

You are now ready to transfer the OpenMX files from the CoSINe server to your onid files. Close the nautilus window to get the terminal input ready to go again.


4 PH 575 02/20/2019

1.3 Installation of ssh software on Mac OS and opening an ssh session

Running ssh from a Mac with an X server requires the installation of third party software. A common way of using ssh with an X server is with XQuartz. You can download it from here –

https://www.xquartz.org/

Once it is installed, run XQuartz and open the X terminal form the application drop-down menu. Start an ssh session by entering at the XQuartz command line –

ssh –Y [email protected]

where ONID is your onid username and XX is the 412 computer number assigned to you. This should change your command line to reflect the new PC you are entering commands to.

As a quick check to make sure everything is working properly, in the command line, enter -

nautilus . &

If everything is good to go, you’ll see the Ubuntu file explorer pop up on screen.

https://www.xquartz.org/


5 PH 575 02/20/2019

2 OpenMX File Transfer

OpenMX software is preinstalled on the computers in WNGR 412, but your account is not preloaded with the files OpenMX requires to run correctly. We have preloaded the OpenMX files onto the CoSINe server, and it can be copied from there. Essentially, you need only follow this procedure once.

2.1 Copy the files

Open a terminal program on (or begin an ssh session with) a WNGR 412 computer, and enter

cp -R /common/ph575/openmx3.7 /home/ONID/

Note that the space between /common/ph575/openmx3.7 and /home/ONID/ is necessary. Here, ONID is your onid username. This will copy the OpenMX folder to your home folder. The files in your home folder can be accessed from any of the computers in WNGR 412. To make sure the transfer worked, navigate to your home folder and list the files located there. Enter the following

cd /home/ONID/openmx3.7

ls

You should see the openmx3.7 folder contents listed as shown below.

Now as a last step you need to copy a makefile into the source folder for later use.

cp makefile ./source


6 PH 575 02/20/2019

2.2 Methane Test Calculation

OpenMX sorts its files into two main folders named source and work. The source folder contains all the software that is needed for running calculations and the work folder contains all the input and output material data files. You need to start in work to run the test calculation.

cd work

You need to run the test calculation on a preloaded material data file for molecular methane called Methane.dat. Execute the calculation via

mpirun -np 1 openmx Methane.dat > met.std &

The output of this calculation is contained across several files. To check if the calculation worked properly, you need to open the one named met.out. One way to find and open the file is with the built-in file browser program nautilus. Open this program in the current directory with –

nautilus . &

The “.” after the nautilus command initiates the program in the directory you’re currently working in. The “&” lets you continue using the command line if you’re using ssh. Now using the file browser, find and open met.out. There are more concise ways of doing this at the command line; for those of you that are well versed in Linux, feel free to navigate directories and manage your files in the way you think is best.

The table in this file labeled “Total energy” should match the one shown in the test calculation section of the OpenMX 3.7 user manual (http://www.openmx-square.org/openmx_man3.7/node16.html) which is shown below.

If your outputs match the manual’s, then you’re ready to test out calculations of bulk material properties.

http://www.openmx-square.org/openmx_man3.7/node16.html



7 PH 575 02/20/2019

3 Basic Parameter Input for Calculation of Bulk Material Properties

OpenMX does bulk material property calculations by operating on input data files with executables that correspond to a desired material property. These files are stored in either the source or work folders in the OpenMX file. Source generally contains all of the code that OpenMX uses to make calculations. Work contains the input and output files used in and produced by the OpenMX calculations. A .dat files contains all the needed material information to run a calculation. When OpenMX is installed, it comes preloaded with several material data files in the work folder. Running OpenMX on a material .dat file can generate band structures, density of states, fermi surfaces, electric transport properties, spin densities, electric field responses, and more.

For the purposes of this tutorial, we will be using the data file for diamond, Cdia.dat to calculate diamond’s band structure and density of states. Remember to save any changes you make to this file before running any calculations. Later, when you want to run material property calculations for a material of your choice, you’ll need to generate a new .dat file with input data corresponding to the desired material, then run OpenMX on that file in the same ways we handle Cdia.dat. That process is detailed in section 5 of the tutorial.

In this example, we are running all OpenMX operations on files contained in the work folder, which leads to all example calculation output files also being generated in the work folder. Going forward beyond this example, it would be best to organize your input/output files into subfolders within work, otherwise your organization will be a nightmare.

3.1 Baseline Material Parameter Input

First, you’ll need to examine and edit the preloaded input file for diamond, which is in the work directory. Open this file by executing gedit on the Cdia.dat file.

cd

cd openmx3.7/work

gedit Cdia.dat

The file should be open for editing in front of you. The first three sections detail (i) the file information, (ii) which atoms are in the material, (iii) where the atoms are located. The first section is there to make sure programs executing the calculations can figure out what to name the output files.


8 PH 575 02/20/2019

All the default options should work regardless of the material choice, but it’s important to understand that the input of System.name will be the same as the names of the output files. You may change this to whatever you want your output files to be named, however this tutorial assumes that System.name has been left as cdia.

The number of unique atoms in the material are specified by Species.Number. Below the Species.Number there is a table that tells the OpenMX programs which files to access to get the correct data for each atom named Definition.Atomic.Species. The first column simply specifies the atomic symbol. The second contains the name of the data file holding information on the pseudo-atomic orbitals (PAOs) that correspond to the atom, and the third specifies the data file containing the fully relativistic pseudopotentials (VPS). These file names aren’t entirely intuitive, but OpenMX has supplied a catalog of the different PAO and VPS files for most atoms on their website at http://www.jaist.ac.jp/~t-ozaki/vps_pao2013/. Use this as a reference when you are generating your own material data files. To add more atoms to the system, simply add more rows into this table, each specifying atomic species, then the PAO file, then the VPS file. See the figure below for an example from NaCl.

The last step in material specification is the input of atomic locations in the material, which occurs in the “Atoms” section of the data file. The number of the atoms in the primitive unit cell is specified by Atoms.Number. The unit of the input lengths, specified by Atoms.SpeciesAndCoordinates.Unit, can take either Angstroms (Ang) or atomic units (AU). Next is a table that gives the actual locations.

http://www.jaist.ac.jp/%7Et-ozaki/vps_pao2013/


9 PH 575 02/20/2019

The unit cell used in this example contains two atoms in the basis, thus Atoms.SpeciesAndCoordinates is a table with only two rows. The first column in this table gives the index for each atom, and the second is the atomic species. The third, fourth, and fifth are the x, y, and z coordinates of the atoms in the unit cell, respectively. The sixth and seventh columns are the number of initial up spins and number of initial down spins. The sum of the last two columns should add to the total number of valence electrons for each atom.

The second table in this section Atoms.UnitVectors has columns that are simply the x, y, and z components of the primitive vectors of the lattice. The unit cell used in this example (outlined in red above) is not the traditional diamond cubic unit cell normally shown (outlined in blue above), but only one octant of it, thus the lattice vectors in the example are modified to give the correct tessellation (see the image above). These parameters can be found on the crystallography open database for most materials at http://www.crystallography.net.

3.2 The “SCF or Electronic System” and “MD or Geometry Optimization” Sections

The sections labeled “SCF [Self-Consistent Field] or Electronic System” and “MD [Molecular Dynamics] or Geometry Optimization” detail the calculation methods and system variables that OpenMX uses for all the material property calculations. The default options should be sufficient for most calculations, so try those first. Please see the OpenMX manual for a more detailed explanation of each of these parameters at http://www.openmx-square.org/openmx_man3.7/node21.html. For this example, none of the parameters need to be changed.

http://www.crystallography.net/




10 PH 575 02/20/2019

3.3 The “Band dispersion” Section

The band structure calculation parameters are entered in the “Band dispersion” section. The first step is enabling the band dispersion output, so ensure that Band.dispersion is set to on.

Band.Kpath.UnitCell specifies a set of primitive vectors for the reciprocal lattice that will be used during the band structure calculation, each row being one vector. If you delete this table and the surrounding keyword brackets then OpenMX will use the primitive vectors specified in the “Atoms” section instead.

The next step is to set the path through k-space for which the band structure is calculated. Band.Nkpath sets the number of sections that comprise the path, and the table Band.kpath sets the parameters for each path section. The number set by Band.Nkpath should be equal to the number of rows in Band.kpath. The first column of the table specifies the number of k-points that the k-path section will be discretized into. The second, third, and fourth are the coordinates of the starting k-point and the fifth, sixth, and seventh are the coordinates of the ending k-point, both given as kx ky kz.

Image of an FCC Brillouin zone taken from https://en.wikipedia.org/wiki/Brillouin_zone


11 PH 575 02/20/2019

The eighth and ninth columns specify the labels given to the beginning and ending k-points for each path section. Keep in mind that some locations in k-space all have labels that are specific to certain points within the first Brillouin zone. The figure above shows the k-point labels in the Brillouin zone for an FCC unit cell. The k-path used in the carbon diamond example goes as Γ→X→W→L→Γ→X (note that “g” is used for Γ). An overview of the labels for some common lattices is given on Wikipedia at https://en.wikipedia.org/wiki/Brillouin_zone.

3.4 The “DOS and PDOS” Section

The density of states (DOS) calculation is straightforward and the .dat file only requires three input parameters in the “DOS and PDOS” section. The first is a switch to enable or disable the DOS output. By default, it is set to off, so delete the word off and replace it with on. Dos.Erange sets the range of energies in electronvolts over which the DOS is calculated. The default should be fine but you may change it as needed. Dos.Kgrid sets the discretization resolution of the grid comprising Brillouin zone in k-space in the form n1 n2 n3. Higher resolutions will take longer but will increase precision.

3.5 Save and Close

Remember to save the .dat file before running calculations with OpenMX. Close the .dat file and the nautilus browser to get back to the command line.

https://en.wikipedia.org/wiki/Brillouin_zone


12 PH 575 02/20/2019

4 Basic Calculations of Bulk Material Properties

Once you have a completed data file, all that remains is to run the SCF (self-consistent field) calculations with OpenMX and display the output data. The example calculations done in this section assume that the input file for carbon diamond Cdia.dat has already been setup as demonstrated in the previous section.

4.1 Band Structure Calculation

You need to run the SCF calculation with the Cdia.dat input file. First navigate to the work directory.

cd

cd openmx3.7/work

Then execute the OpenMX SCF calculation with

openmx Cdia.dat

You should see a long output in the command line that terminates with “The calculation was normally finished”. This will generate an output file named cdia.Band if it worked correctly.

Now that this step is complete, all the needed data to show the band structure has been generated, so all that’s left is to visualize it. To do this, OpenMX comes with a file that, when compiled, generates an executable program that converts the band structure data into a gnuplot script. Navigate the command line to the source folder.


13 PH 575 02/20/2019

cd ..

cd source

Now compile the file named bandgnu13.c – this will generate an executable named bandgnu13. You might see a lot of warnings here, but as long as there are no errors you are good to go.

gcc bandgnu13.c -lm -o bandgnu13

This file needs to be copied over to the work folder.

cp bandgnu13 /home/ONID/openmx3.7/source /home/ONID/openmx3.7/work

Now go back to the work folder to run the executable you copied on the band structure data generated by running openmx on Cdia.dat.

cd ..

cd work

./bandgnu13 cdia.Band

This should produce two output files. The one named cdia.GNUBAND is a script for Gnuplot that pulls the band structure data from the other output file named cdia.BANDDAT1 (use ls to make sure these files are here, they may not appear in nautilus if you’re using ssh). Before plotting the data, we need to edit cdia.GNUBAND. Open the cdia.GNUBAND file with

gedit cdia.GNUBAND

Change the top line to match the one in the figure below. Also edit the “set yra” line to a more reasonable set of energies (-25 to 20 eV should do nicely), then save and close it. For more information on gnuplot, see the documentation here. Most of the settings changed by these .GNUBAND files are listed in the Set-show section (pg 111).

Now at the command line plot the data with gnuplot. You should then see a window displaying the band structure of the material.

gnuplot cdia.GNUBAND

http://www.gnuplot.info/docs_5.2/Gnuplot_5.2.pdf


14 PH 575 02/20/2019

If you like, you can use you own plotting software instead of Gnuplot to plot the data contained in cdia.BANDDAT1. Matlab and Python are installed on the 412 machines, which might be helpful for that. You can also drag the cdia.BAND file into the OpenMX viewer (www.openmx-square.org/square/index.html) to easily visualize the data, but the formatting options are limited here.

4.2 Density of States Calculation

Before starting the DOS calculation make sure that the Dos.fileout keyword in Cdia.dat (near the end of the file) is set to on (see tutorial section 3.4). If you haven’t done so already, run the SCF calculation on the data file in the work directory.

cd

cd openmx3.7/work

openmx Cdia.dat

The SCF calculation outputs a couple files needed for the DOS calculations: cdia.Dos.val and cdia.Dos.vec. Like the band structure calculations, you need to compile an executable program (DosMain) from a file preloaded into the source directory (DosMain.c). If DosMain doesn’t already exist in your work directory, go to the source directory and generate the executable with make –

http://www.openmx-square.org/square/index.html

http://www.openmx-square.org/square/index.html


15 PH 575 02/20/2019

cd

cd openmx3.7/source

make DosMain

You may see some warnings while this is executing. Make sure the DosMain executable is now in the directory with ls, if it is, you’re OK to proceed. Copy DosMain from the source folder to the work folder

cp DosMain /home/ONID/openmx3.7/work

Now you can run the DOS calculation from the work folder via –

cd ..

cd work

./DosMain cdia.Dos.val cdia.Dos.vec

The program will then execute, but you need to enter some directions to the program as it runs (these steps are labeled in the figure above).

1. The software offers the option to run the calculation with either the tetrahedron or Gaussian broadening algorithm. These are two ways of approximating the potential wells of atoms in the lattice. For this example, you should proceed with the tetrahedral method because that seems to work best.

1

2

3


16 PH 575 02/20/2019

If you enter Gaussian broadening instead of tetrahedral, you’ll be prompted to enter the “value of Gaussian”. The Gaussian broadening functions are of the form exp(−(𝐸𝐸/𝑎𝑎)2), and the “value of Gaussian” specifies the value of 𝑎𝑎. The plot below shows the DOS output for several choices you can make here. See the manual for more information. You’ll need to research on your own to find out which is best for other materials.

2. You can either run the total DOS for the material, or you can run the partial DOS (PDOS) to get the density of states for individual atoms and orbitals.

PDOS only:

3. The software automatically detects how many atoms are in the unit cell you specified. Select which atom you want to run the PDOS for.

After completing these steps the software prints out a list of data files that contain the partial density of states. Each of these are labeled with the orbital they correspond to. The last one contains the total density of states for the atom you selected. These files contain three columns. The first is the energy given in electronvolts. The second contains the density of states at each energy point in units of eV-1. The third contains the integrated density of states through the corresponding energy. OpenMX doesn’t have a gnuplot converter for this data, so use your favorite plotting software to display it. Matlab can read the data with the dlmread function and Microsoft Excel can open the data files with fixed width delimitation.

-25 -20 -15 -10 -5 0 5 10 15 200

0.2

0.4

0.6

0.8

1

1.2Tetrahedron

a = 1.0 eV

a = 0.5 eV


17 PH 575 02/20/2019

4.3 Lattice Visualization with XCrySDen

The SCF calculation will automatically output a couple visualization files – cdia.bulk.xyz and cdia.xyz. .xyz files are common among DFT and molecular dynamics software and many programs can read them.

The computers in Weniger 412 already have XCrySDen installed. This software can be used to visualize several output files from OpenMX including .xyz, .md, .cube, and .xsf. There are some bugs that do not allow this software to run over putty with Xming easily, so you should use the computers in 412 directly without ssh. If you’re working on these machines via ssh you should use the OpenMX Viewer instead.

Running the software is straightforward. Simply open a terminal and run XCrySDen at the command line.

xcrysden

Now an empty XCrySDen window will open. Select File>Open Structure…>Open XYZ and open cdia.bulk.xyz under the OpenMX work directory.


18 PH 575 02/20/2019

This will display a few periods of your material structure.


19 PH 575 02/20/2019

5 Simulating your own materials

Once you are ready to simulate materials that are not preloaded into the OpenMX work folder (as you will need to do for your project!), you will need to generate a new .dat file for the material. This includes finding the atom species, the location of the atoms, pseudopotentials, the k-space path for the dispersion relationship, and the unit vectors, among other things for chosen material. There are databases loaded with these parameters for lots of materials.

5.1 Getting unit cell information from .CIF files for new materials

In the field of crystallography, there are two common languages used to define the conventional unit cell of a crystal structure. The first, which I’ll refer to as abc, pairs a primitive unit cell with a space group, which contains information about the needed rotations and tessellations needed to produce the conventional unit cell. The second defines the positions of all the atoms in the conventional unit cell via Cartesian coordinates without the need to specify a space group; I’ll call this xyz.

OpenMX needs a unit cell that is specified in xyz, meaning that the unit vectors and the atom positions must be specified in Cartesian coordinates. One of the best resources for obtaining crystal structure data, the Crystallography Open Database (crystallography.net) or the Materials Project (https://materialsproject.org/), but the data stored in these databases is distributed in .cif files that use the abc convention. Any .cif file downloaded from this database will specify a unit cell by giving three tessellation lengths (𝑎𝑎, 𝑏𝑏, and 𝑐𝑐) and the angles between the tessellation directions (𝛼𝛼, 𝛽𝛽, and 𝛾𝛾), referred to collectively as lattice constants (see the figure below).

To use the information contained in these .cif files in OpenMX, you need to convert the lattice constants to Cartesian unit vectors (this is separate from the atom positions). If we let the side length 𝑎𝑎 lie on the x-axis and put 𝑏𝑏 in the x-y plane, then the cartesian unit vectors can be found as follows –

http://crystallography.net/

https://materialsproject.org/


20 PH 575 02/20/2019

�⃑�𝑎 = 𝑎𝑎𝑥𝑥�

𝑏𝑏�⃑ = 𝑏𝑏(cos𝛾𝛾 𝑥𝑥� + sin 𝛾𝛾 𝑦𝑦�)

𝑐𝑐 = 𝑐𝑐 �cos𝛽𝛽 𝑥𝑥� +cos𝛼𝛼 − cos𝛾𝛾 cos𝛽𝛽

sin𝛾𝛾𝑦𝑦� + �sin2 𝛽𝛽 −

(cos𝛼𝛼 − cos𝛾𝛾 cos𝛽𝛽)2

sin2 𝛾𝛾 �1/2

�̂�𝑧�

These vectors can be added to the <Atoms.UnitVectors> section of the .dat file. Now that we have the Cartesian unit vectors we need to figure out the positions of the atoms within the unit cell. The .cif files report the atomic locations of the primitive unit cell in fractional coordinates as shown in the figure below.

Each row in the data table gives the coordinates of a primitive unit cell atom as fractions of 𝑎𝑎, 𝑏𝑏, and 𝑐𝑐 in the third, fourth, and fifth columns, respectively. Since OpenMX only tessellates the unit cell, the primitive unit cell may not contain all of the atom locations that OpenMX needs to perform the calculation correctly. For this example, the .cif file for MoS2 has only two atoms detailed, but there are six atoms that need to be detailed to generate the lattice purely by tessellating the unit cell. OpenMX has a web app (the OpenMX viewer) that allows us to convert the position data in a .cif file to Cartesian coordinates for all atoms needed easily at (http://www.openmx-square.org/viewer/index.html). You can also use this as an alternative to XCrySDen for crystal visualization. Simply download the desired .cif file from a database and drag it into the OpenMX Viewer window.

Atom Location Data

Data Table Column Titles

http://www.openmx-square.org/viewer/index.html


21 PH 575 02/20/2019

You’ll get a popup window asking if you want OpenMX Viewer to draw the conventional unit cell; just press “OK”. You should then see the conventional unit cell of the material. There are a lot of helpful tools built into this application, but for now, we just need the position data. You can download the data as a .xyz file with the toolbar at the bottom by selecting “xyz” from the “Save” dropdown menu.

Save the file and open it with gedit or another formatting word processor. These .xyz files contain a nicely formatted table containing the Cartesian coordinates of the atoms in the conventional unit cell (all units here are in angstroms).

The number in the header just specifies the number of atoms in the conventional unit cell. You can enter these positions as is into an OpenMX .dat file in the <Atoms.SpeciesAndCoordinates> section to run your calculations.

5.2 Generating custom k-paths

You can find the coordinates of the k-points for materials by looking up their space group number in the Bilbao Crystallographic Server database (http://www.cryst.ehu.es/cryst/get_kvec.html). Space groups can usually be found on the Wikipedia page for a given material and they are listed in the .cif files obtained from the Crystallography open database. To get the coordinates of the high-symmetry k-points, click the “comparative listing of k-vector types” button once you’ve entered the space group number for a material. The labels in the leftmost column correspond to the k-point names, and the values on the rightmost column correspond to the kx, ky, kz coordinate values that need to be entered into Band.kpath.

x-position y-position z-position Number of Atoms

http://www.cryst.ehu.es/cryst/get_kvec.html


22 PH 575 02/20/2019

openmx setup and basic calculation...

Documents