3 Quick Start

We assume that WIEN2k is properly installed and configured for your site and that you ran userconfig_lapw to adjust your path and environment. (For a detailed description of the installation see chapter 11.

This chapter is intended to guide the novice user in the handling of the program package. We will use the example of TiC in the sodium chloride structure to show which steps are necessary to initialize a calculation and run a self consistent field cycle. We also demonstrate how to calculate various physical properties from these SCF data. Along the way we will give all important information in a very abridged form, so that the novice user is not flooded with information, and the experienced user will be directed to more complete information.

Figure: TiC in the sodium chloride structure. This plot was generated using BALSAC (see 9.18.1). Interface programs between WIEN2k and BALSAC are available.
\begin{figure}\begin{center} \leavevmode {\epsfig{figure=figs/tic/structure, height=70mm}} \end{center}\end{figure}

In this chapter we will also show, how the new graphical user interface w2web can be utilized to setup and run the calculations.


1 Naming conventions

Before we begin with our introductory example, we describe the naming conventions, to which we will adhere throughout this user's guide.

On UNIX systems the files are specified by case.type and it is required that all files reside in a subdirectory ./case. Here and in the following sections and in the shell scripts which run the package themselves, we follow a simple, systematic convention for file labeling.

For the general discussion (when no specific crystal is involved), we use case, while for a specific case, e.g. TiC, we use the following notation:

case=TiC

The filetype ``type'' always describes the content of the file (e.g.,

type=inm is inPUT for mIXER).

Thus the input to MIXER for TiC is found in the file

TiC.inm
which should be in subdirectory ./TiC.

2 Starting the w2web server

Start the user interface w2web on the computer where you want to execute WIEN2k(you may have to telnet, ssh,.. to this machine) with the command

w2web [-p xxxx]

If the default port (7890) used to serve the interface is already in use by some other process, you will get the error message w2web failed to bind port 7890 - port already in use!. Then you will have to choose a different port number (between 1024 and 65536) . Please remember this port number, you need it when connecting to the w2web server.

Note: Only user root can specify port numbers below 1024!

At the first startup of this server, you will also be asked to setup a username and password, which is required to connect to this server.

3 Connecting to the w2web server

Use your favorite WWW-browser to connect to w2web, specifying the correct portnumber, e.g.

netscape http://hostname_where_w2web_runs:7890

(If you do not remember the portnumber, you can find it by using ``ps -ef $\vert$ grep w2web'' on the computer where w2web is running.) You should see a screen as in Fig.3.2.

4 Creating a new session

The user interface w2web uses sessions to distinguish between different working environments and to quickly change between different calculations. First you have to create a new session (or select an old one). Enter ``TiC'' and click the ``Create'' button.
Note: Creating a session does not automatically create a new directory!

You will be placed in your home directory if no working directory was designated to this session previously (or if the directory does not exist any more).

Figure: Startup screen of w2web
\begin{figure}\begin{center} \leavevmode \rotatebox{0}{\epsfig{figure=screenshot2k/startupn, width=.8\textwidth}} \end{center}\end{figure}

5 Creating a new case-directory

Using ``Session Mgmt. $\rightarrow $ change directory'' you can select an existing directory or create a new one. For this example create a new directory lapw and than TiC using the ``Create'' button. After the directory has been created, you have to click on select current directory to assign this newly created directory to the current session.

After clicking on Click to restart session the main window of w2web will appear (Fig.3.3.

Figure: Main window of w2web
\begin{figure}\begin{center} \leavevmode \rotatebox{0}{\epsfig{figure=screenshot2k/mainn, width=.7\textwidth}} \end{center}\end{figure}


6 Creating the ``master input`` file case.struct

To create the file TiC.struct start the struct-file generator using ``Execution $\rightarrow $ StructGen'' (see figure 3.4).

For a new case w2web creates an empty structure template in which you can specify structural data. Later on this information is used to generate the TiC.struct file.

As a first step specify the number of atoms (2 for TiC) and fill in the data given below into the corresponding fields (white boxes):

Title TiC
Lattice F (for face centered)
a 4.328 Å(make sure the Ang button is selected)
b 4.328 Å
c 4.328 Å
$\alpha,\beta,\gamma$ 90
Atom Ti, enter position (0,0,0)
Atom C, enter position (.5,.5,.5)

Click ``Save Structure'' (Z will be updated automatically) and ``set automatically RMT and continue editing '':

This will compute the nearest neigbor distances using the program nn and setrmt_lapw will then determine the optimal RMT values (muffin-tin radius, atomic sphere radius). To learn more about the philosophy of setting RMTs see $http://www.wien2k.at/reg_user/faq$. Since it is essential to keep RMTs constant within a series of calculations (eg. when you do a Volume-optimization, see 3.11.6 ), you should already now decide whether you want to do just one single calculation with fixed structural parameters, or whether you intend a relaxation of internal parameters (using forces and min_lapw) or a volume optimization, which would required reduced RMT values.

Choose a reduction of 3 % so that we can later optimize the lattice parameter.

Figure: StructGen of w2web
\begin{figure}\begin{center} \leavevmode \rotatebox{0}{\epsfig{figure=screenshot2k/structgen, width=\textwidth}} \end{center}\end{figure}

When you are done, exit the StructGen with ``save file and clean up''. This will generate the file TiC.struct (shown now in view-only mode with a different background color), which is the master input file for all subsequent programs. This step also automatically generates the input file for the free atom program lstart (atomic configurations) tic.inst.

A few other hints on StructGen:

You have to click on Save Structure after every modifications you make in the white fields. Add/remove a position/atom only if you have made no other changes before.

In a face-centered (body-centered) spacegroup you have to enter just one atom (not the ones in (.5,.5,0),...).

StructGen offers a built in calculator: Each position of equivalent atoms can be entered as a number, a fraction (e.g. $1/3$) or a simple expression (e.g. $0.21+1/3$). The first position defines the variables x, y and z, which can be using in expression defining the other positions (e.g. $-y$, $x$, $-z+1/2$).

When you now choose ``Files $\rightarrow $ show all files'', you will see, that both files tic.struct and tic.inst have been created.

For a detailed description of these files consult sections 4.3 and 6.4.3.


7 Initialization of the calculation (init_lapw)

After the two basic input files have been created, initalization of the calculation is done by ``Execution $\rightarrow $ initialize calc.''. This will guide you through the steps necessary to initialite the calculation. Simply follow the steps that are highlighted in green and follow the instructions.

The initialization process is described in detail in section 5.1.2.

Alternatively you could run the script init_lapw from the command line. All actions of this script are logged in short in :log and in detail in the file case.dayfile, which can easily be accessed by Utils. $\rightarrow $ show dayfile.

Initializing the calculation will run several steps automatically, where x is the script to start WIEN2k programs (see section: 5.1.1).

x nn
calculates the nearest neighbors up to a specified distance and thus helps to determine the atomic sphere radii (you must specify a distance factor f, e.g. 2, and all distances up to f * NN-dist. are calculated)
view TiC.outputnn
: check for overlapping spheres, coordination numbers and nearest neighbor distances, (e.g. in the sodium chloride structure there must 6 nearest and 12 next nearest neighbors). Using these distances and coordinations you can check whether you put the proper positions into your struct file or if you made a mistake. nn also checks whether your equivalent atoms are really crystallographically equivalent and eventually writes a new struct-file which you may or may not accept. If you have not done so at the very beginning, go back to StructGen and choose proper RMT values. You can save a lot of CPU-time by changing RMT to almost touching spheres. See Sec.4.3
x sgroup
calculates the point and spacegroups for the given structure
view TiC.outputsgroup
: Now you can either accept the TiC.struct file generated by sgroup (if you want to use the spacegroup information or a different cell has been found by sgroup) or keep your original file (default).

x symmetry
generates from a raw case.struct file the space group symmetry operations, determines the point group of the individual atomic sites, generates the LM expansion for the lattice harmonics (in case.in2_st) and local rotation matrices (in case.struct_st).

view TiC.outputs
: check the symmetry operations (they have been written to or compared with already available ones in TiC.struct by the program symmetry) and the point group symmetry of the atoms (You may compare them with the ``International Tables for X-Ray Crystallography``). If the output does not match your expectations from the ``Tables'', you might have made an error in specifying the positions. The TiC.struct file will be updated with symmetry operations, positive or negativ atomic counter (for ``cubic'' point group symmetries) and the local rotation matrix.

x lstart
generates atomic densities (see section 6.4) and determines how the orbitals are treated in the band structure calculations (i.e. as core or band states, with or without local orbitals, ...). You are requested to specify the desired exchange correlation potential and an energy that separates valence from core states. For TiC select the recommended potential option ``GGA of Perdew-Burke-Ernzerhof 96'' and a separation energy of -6.0 Ry.

edit TiC.outputst
: check the output (did you specify a proper atomic configuration, did lstart converge, are the core electrons confined to the atomic sphere?). Warnings for the radial mesh can usually be neglected since it affects only the atomic total energy. lstart generates TiC.in0_st, in1_st, in2_st, inc_st and inm. For Ti it selects automatically $1s$, $2s$, and $2p$ as core states, $3s$ and $3p$ will be treated with local orbitals together with $3d$, $4s$ and $4p$ valence states.

edit TiC.in1_st
: As mentioned, the input files are generated automatically with some default values which should be a reasonable choice for most cases. Nevertheless we highly recommend that you go through these inputs and become familiar with them. The most important parameter here is RKMAX, which determines the number of basis functions (size of the matrices). Values between 5-9 (APW) and 6-10 (LAPW) are usually reasonable. You may change here the usage of APW or LAPW (set 1 or 0 after the CONT/STOP switch), since often APW is necessary only for orbitals more difficult to converge (3d, 4f). Here we will just change EMAX of the energy window from 1.5 to 2.0 Ry in order to be able to calculate the unoccupied DOS to higher energies.
edit TiC.in2_st
: Here you may limit the LM expansion (for some speedup), change the value of GMAX (in cases with small spheres (e.g. systems with H-atoms) values of 15-24 are recommended) or specify a different BZ-integration method to determine the Fermi energy. For this example you should not change anything so that you can compare your results with the test run.
edit TiC.inm_st
: For ``difficult to converge systems'' (several atoms with localized d- or f-electrons, magnetic systems) you should reduce the mixing factor from 0.4 to a smaller value (e.g. 0.05). (See our faq-page on www.wien2k.at what you should do when the scf cycle crashes). For TiC no changes are necessary.
Copy all generated inputs
(from case.in$*$_st to case.in*). In cases without inversion symmetry the files case.in1c, in2c are produced.
x kgen
generates a k-mesh in the Brillouin zone (BZ). You must specify the number of k-points in the whole BZ (use 1000 for comparison with the provided output, a ``good'' calculations needs many more). For details see section 6.5.
view TiC.klist
: check the number of k-points in the irreducible wedge of the BZ (IBZ) and the energy interval specified for the first k-point. You can now either rerun kgen (and generate a different k-mesh) or continue.
x dstart
generates a starting density for the SCF cycle by superposition of atomic densities generated in lstart. For details see section 6.6.
view TiC.outputd
(check if gmax $>$gmin)
Now you are asked
, whether or not you want to run a spin-polarized calculation (in such a case case dstart is re-run to generate spin-densities). For TiC say No.

Alternatively, w2web provides an ``expert-mode'', where some inputs can be specified right at the beginning and then the whole initialization runs at once. Please check carefully the STDOUT-listing and some output-files for possible errors or warnings!!

Initialization of a calculation (running init_lapw) will create all inputs for the subsequent SCF calculation choosing some default options and values. You can find a list of input files using ``Files $\rightarrow $ input files'' ( 3.5).

Figure 3.5: List of input files
\begin{figure}\begin{center} \leavevmode \rotatebox{0}{\epsfig{figure=screenshot2k/inputfiles, width=.7\textwidth}} \end{center}\end{figure}


8 The SCF calculation

After the case has been set up, a link to ``run SCF'' is added, (``Run Programs $\rightarrow $ run SCF'' and you should invoke the self-consistency cycle (SCF). This runs the script run_lapw with the desired options.

The SCF cycle consists of the following steps:

LAPW0
(POTENTIAL) generates potential from density
LAPW1
(BANDS) calculates valence bands (eigenvalues and eigenvectors)
LAPW2
(RHO) computes valence densities from eigenvectors
LCORE
computes core states and densities
MIXER
mixes input and output densities

After selecting ``run SCF'' from the ``Execution'' menu, the SCF-window will open, and you can now specify additional parameters. For this example we select charge convergence to 0.0001: Specify ``charge'' to be used as convergence criterion, and select a value of 0.0001 (-cc 0.0001).

To run the SCF cycle, click on ``Run!''

Since this might take a long time for larger systems; you can specify the ``Execution type'' to be batch or submit (if your system is configured with a queuing system and w2web has been properly set up, see section 11.3).

While the calculation is running (as indicated by the status frame in the top right corner of the window), you can monitor several quantities (see section 3.9).

Once the calculation is finished (11 iterations), view case.dayfile for timing and errors and compare your results with the files in the provided example (TiC/case_scf).

For magnetic systems you would run a spin-polarized calculation with the script runsp_lapw. The program flow of such a calculation is described in section 4.5.2 and the script itself in section 5.1.3.


9 The ``history`` file case.scf

During the SCF cycle the essential data of each iteration are appended to the file case.scf, in our example TiC.scf. For an easier retrieval of certain quantities, the essential lines carry a label of the form :LABEL: which can be used to monitor these quantities during a SCF run.

The information is retrieved using the UNIX grep command or using the ``Utils. $\rightarrow $ analyze'' menu.

While the SCF cycle of TiC is running try to monitor e.g. the total energy (label :ENE) or the charge distance (label :DIS). The calculation has converged, when the convergence criterion is met for three subsequent iterations (compare the charge distance in the example).

For a detailed description of the various labels consult section 4.4.


10 Saving a calculation

Before you proceed to another calculation, you should save the results of the SCF-cycle with the save_lapw command, which is also described in detail in section 5.2.1. This can also be done from the graphical user interface by choosing the ``Utils. $\rightarrow $ save_lapw'' menu.

Save the result to this example under the name ``TiC_scf''.

You can now improve your calculation and check the convergence of the most important parameters:

Then just execute another run_lapw using ``Execution $\rightarrow $ run SCF''.


11 Calculating properties

Once the SCF cycle has converged one can calculate various properties like Density of States (DOS), band structure, Optical properties or X-ray spectra.

For the calculation of properties (which from now on will be called ``Tasks''). We strongly encourage the user to utilize the user interface, w2web. This user interface automatically supplies input file templates and shows how to calculate the named properties on a step by step basis.


1 Electron density plots

Select ``El. Dens.'' from the ``Tasks'' menu and click on the buttons one by one (see figure 3.6):

Figure 3.6: Task ``Electron Density Plots''
\begin{figure}\begin{center} \leavevmode {\epsfig{figure=screenshot2k/densityn, width=0.99\textwidth}} \end{center}\end{figure}

Figure 3.7: Electron density of TiC in (100) plane using Xcrysden
\begin{figure}\begin{center} \leavevmode \rotatebox{0}{\epsfig{figure=screenshot2k/density-xcrysden, width=0.8\textwidth}}\end{center}\end{figure}

Compare the result with the electron density plotted in the (100) plane (see figure 3.8). The program gnuplot (public domain) must be installed on your computer. For more advanced graphics use your favorite plotting package or specify other options in gnuplot (see rhoplot_lapw how gnuplot is called).

Figure 3.8: Electron density of TiC in (100) plane
\begin{figure}\begin{center} \leavevmode \rotatebox{0}{\epsfig{figure=screenshot2k/density2n, width=0.75\textwidth}}\end{center}\end{figure}


2 Density of States (DOS)

Select ``Density of States (DOS)'' from the ``Tasks'' menu and click on the buttons one by one:

If you want to use the supplied plotting interface dosplot2 to preview the results, the program gnuplot (public domain) must be installed on your computer.

The calculated DOS can be compared with figures 3.9 and 3.10. Together with the electron density the partial DOS allows you to analyse the chemical bonding (covalency between $Ti-d_{eg}$ and $C-p$, non-bonding $Ti-d_{t2g}$, charge transfer estimates,....)

Figure 3.9: Density of states of TiC
\begin{figure}\begin{center} \leavevmode \rotatebox{0}{\epsfig{figure=screenshot2k/dos1, width=0.55\textwidth}}\end{center}\end{figure}

Figure 3.10: Density of states of TiC
\begin{figure}\begin{center} \leavevmode \rotatebox{0}{\epsfig{figure=screenshot2k/dos2, width=0.55\textwidth}}\end{center}\end{figure}


3 X-ray spectra

Select ``X-Ray Spectra'' from the ``Tasks menu'' and click on the buttons one by one:

If you want to use the supplied plotting interface specplot to preview the results, the public domain program gnuplot must be installed on your computer. The calculated TiC Ti-$L_{III}$-spectrum can be compared with figure 3.11.

Figure 3.11: Ti $L_{III}$ spectrum of TiC
\begin{figure}\begin{center} \leavevmode \rotatebox{0}{\epsfig{figure=figs/tic/TiC_xspec, width=8cm}} \end{center}\end{figure}


4 Bandstructure

Select ``Bandstructure'' from the ``Tasks'' menu and click on the buttons one by one:

If you want to preview the bandstructure, the program ghostview (public domain) must be installed on your computer. You can compare your calculated bandstructure with figure 3.12.

Figure 3.12: Bandstructure of TiC
\begin{figure}\begin{center} \leavevmode \rotatebox{0}{\epsfig{figure=figs/tic/bands, height=8cm}} \end{center}\end{figure}


5 Bandstructure with band character plotting / full lines

Select again ``Bandstructure'' from the ``Tasks'' menu. We assume that you have already done the steps described in the previous section (generate TiC.klist_band and x lapw1 -band).
If you have case.irrep* or case.qtl* files from previous runs which do not fit to the present case.output1 file, you may get errors while running spaghetti. In this case remove all case.irrep or case.qtl files.

You can compare your results with figure 3.13.

Figure 3.13: Bandstructure of TiC, showing t2g-character bands of Ti in character plotting mode
\begin{figure}\begin{center} \leavevmode \rotatebox{0}{\epsfig{figure=figs/tic/dbands, height=8cm}} \end{center}\end{figure}


6 Volume Optimization

Select ``Optimize (V,c/a)'' from the ``Execution'' menu. Setup the shell script optimize.job script using x optimize and volume variations of -10, -5, 0, +5 and +10%. Edit this file and uncomment the x dstart line (remove the ``#'' character). Then run the optimize.job. When the job has finished, you should click on Plot and then preview the energy curve.

You should get an energy curve as in figure 3.14. On the screen you will find the fitting parameters for the ``equation of states'' (Murnaghan, Birch-Murnaghan and the EOS2 equation, see sec. 9.9). This information is also written to TiC.outputeos.

Figure 3.14: Energy vs. volume curve for TiC
\begin{figure}\begin{center} \leavevmode \rotatebox{0}{\epsfig{figure=figs/tic/TiC_vol, width=8cm}} \end{center}\end{figure}


12 Setting up a new case

In order to setup a new case you need at least the following information:

Usually this information can be collected from the ``International Tables of Crystallography'' once you know the space group, the Wyckoff position and the internal free coordinates.

1 Manually setting up a new case

Usually for a new ``case`` the input is not created from scratch, but one uses the struct file from a similar case as pattern. Change into the lapw subdirectory and proceed as follows:

mkdir case_new
cd case_new
cp ../case_old/case_old.struct case_new.struct

Now edit case_new.struct (see section 4.3) as necessary (Note: this is a fixed formatted file, so all values must remain at their proper columns). Afterwards generate case_new.inst using instgen_lapw.

2 Setting up a new case using w2web

Use the menu Session Mgmt. $\rightarrow $ change session of w2web to create a new session (enter the name of the new session and click on ``Create''). Then you should also create a new directory and ``select'' it..

When you select ``Execution $\rightarrow $ StructGen'', you have several choices:

You can just specify the number of non-equivalent atoms and a template file will be created. In StructGen you simply specify the lattice (type or spacegroup), cell parameters and name and positions of atoms. When you ``save file and clean up'' the new case.struct file and the case.inst file are created automatically.

Alternatively, you can use cif2struct or xyz2struct to convert a ``cif'', ``txt'' or ``xyz'' file into the WIEN2k case.struct file. Check page [*] for more info on the specific file formats.

For more information on the StructGen refer to page [*].

pblaha 2007-11-27