README_lmto

Introduction:
-------------

'lm2xsf' is a command line tool that converts crystal structures, charge
densities and the electron localization function (ELF) generated by the 
'TB-LMTO-ASA' code to a format that can be read by the program
'XCrysDen', a powerful and easy to use visualization tool for crystal
structures and densities. 

In detail it reads the 'CTRL' file and, if present, also the 'RHO' and
'ELF' files, converts the lengths and densities to Angstrom units, and
writes it to a single xsf-file, the 'XCrysDen' file format. Finally the
output file is compressed using 'gzip'.  

It can automatically remove the empty spheres and, if necessary, helps
you to generate a conventional unit cell.


Version:
--------

1.03 (12.09.2014):



Author:
-------

Jens Kunstmann (jens@j-kunstmann.de)
appreciates comments and bug reports.
 

Copyright:
----------

Copyright (C) 2005,2014 Jens Kunstmann

'xsfconvert' is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

'xsfconvert' is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.


Requirements:
-------------

Please use 'XCrysDen' Version Beta-1.0 and above. Some problems were
reported by people using older versions.

To take advantage of the automatic compression feature of 'lm2xsf' the
tool 'gzip' is required. It is usually available on all Unix platforms.


Installation:
-------------

The program is written in ANSI-C and should compile on any machine.
In a linux shell change to the xsfconvert directory and type:

 > mkdir bin
 > cd source
 > make lmto

If this doesn't work change the compiler options in the makefile or 
contact the author.
The executable is called 'lm2xsf'. After compilation it can be found
in the 'bin' directory. Now copy it somewhere in your PATH.


Usage: examples
---------------

 > lm2xsf
 
By default 'lm2xsf' will read the files named 'CTRL', 'RHO', and 'ELF'
from the local directory, remove the empty spheres, convert the lengths
and densities to Angstrom units, write everything to a file named
'this.xsf', and compress this file using 'gzip'.
The resulting file 'this.xsf.gz' can directly be read by 'XCrysDen'.


 > lm2xsf -wrong

Starting 'lm2xsf' with some wrong arguments will print the following
help text:

---------------------------------------------
 +++ lm2xsf version 1.0 (1 Apr 2005) written by Jens Kunstmann +++

Usage: lm2xsf [-s] [-d] [-u a b c] [<option> file <option> file ...]

options:
  -s, -S        do not remove empty spheres
  -d, -D        do not compress the xsf output file
  -u, -U        define lattice constants a,b,c of conventional unit cell
                (a,b,c are in units of the LMTO lattice constant 'ALAT')
  -c, -C        CTRL file
  -r, -R        RHO or RHOS file (density is converted to (1/Ang)^3)
  -e, -E        ELF file (dimensionless, no conversion)
  -o, -O        xsf output file (without .gz extension)
  
---------------------------------------------

 > lm2xsf -s

The empty spheres are not removed.


 > lm2xsf -d

The xsf output file is not compressed. 


 > lm2xsf -c CTRL-1  -r RHO-1  -e ELF-1

Will read from the files 'CTRL-1', 'RHO-1', and 'ELF-1'.


 > lm2xsf -r RHOS
 
Will read the spin density (magnetization density) file 'RHOS' instead
of the normal density 'RHO'. Both files have the same file format and
are exchangeable.

MIND: although the format of 'ELF' is also similar to that of 'RHO'
and 'RHOS', you should not exchange charge densities and ELFs because
they have to be treated differently: ELFs are dimensionless and thus
don't need a conversion of units, while the charges densities 'RHO' and
'RHOS' have to be converted to (1/Ang)^3. 


 > lm2xsf -o SiO_2.xsf

Will write the output to the file 'SiO_2.xsf'.


 > lm2xsf -u 1 1 1

Will create a cubic conventional unit cell, with each side having the
length of the LMTO lattice constant 'ALAT'.

Explanation: 'XCrysDen' can switch between primitive and conventional
unit cells if both are defined in the xsf-file. For structures where
the primitive and the conventional unit cell differ, you have to
define the conventional unit cell yourself, either by changing the
xsf-file by hand or by using the '-u' command line argument as above. 
By default 'lm2xsf' will define both unit cells to be the same.


XCrysDen:
---------

 > xcrysden --xsf this.xsf.gz
 
This starts 'XCrysDen' and will read in the file 'this.xsf.gz'. 
The 3D-Structure is displayed in the main window. The ELF and charge
density are saved as two different data grids. You can visualize them
via the menu 'Tools'->'Data Grid'. Please read the XCrysDen user manual
for further information.


Restrictions:
-------------

'lm2xsf' can only read the 'CTRL' file if the category DIM is present
and if the data given for one entry do not exceed one line. You can
prevent this by setting: VERBOS < 50 in the IO category. 

The format of the 'RHO' and 'ELF' files should be that suitable for
the 'DataExplorer'. Set: FORMAT=3 in the PLOT category.  

History:
--------

Version 1.02 (18 Apr 2005)
- first release

Version 1.03 (12.09.2014):
 - included ANSI-C include files. This removes the error messages during compilation.


References:
-----------

TB-LMTO-ASA:	http://www.fkf.mpg.de/andersen/
XCrysDen:	http://www.xcrysden.org/