Convert old atk files to NanoLanguage

[Anders Blom]

The short story Some users may still have a lot of .atk input files for ATK 2.0 and earlier. The script attached in this post makes it extremely simple to upgrade such files to NanoLanguage files. The script converts all kinds of ATK 2.0 input files, including two-probe systems, into NanoLanguage scripts, ready to be run!

Compatibility note To run the conversion script requires ATK 2.3 or higher. The generated scripts are compatible with ATK 2.2 and later (and also ATK 2.1 and 2.2 with relatively small modifications). However, we recommend you to use the latest ATK for several reasons (calculation speed, bug fixes, etc, etc)!

Introduction It is our hope and intention, that these generated scripts will make it easier to learn NanoLanguage, and to lower the barrier in learning the new input format. Once you can see how the old keywords translate into NanoLanguage, it will be a simple matter to use the converted scripts as templates for new calculations, with different geometries and/or different parameters. The script is very simple to use: download it into the directory where you keep you keep your atk files. Then, download and install the latest ATK, and run

Code

atk convert_atk_to_nl.py input.atk > script.py

for each input file (here symbolically called input.atk) you wish to convert. Batch processing is also possible, along the lines of (in bash)

Code

for i in *.atk ; do
    atk convert_atk_to_nl.py $i > $i.py
done

Two-probe systems To convert two-probe systems, the input file should be the two-probe file (containing the definition of the central region). The script will automatically attempt to locate, and convert, the electrode files, based on the keywords TwoProbe::LeftElectrode::ATKFile or TwoProbe::LeftElectrode::NetCDFFile (and correspondingly for the right electrode). If the NetCDF keyword is used, the script will look for an ATK input file by the same name, but with the extension .atk. If this file is not found, the conversion will fail. In this case, please edit the two-probe script to match the names of the electrode input files. Two-probe systems will be considered as heterogeneous if the name of the input files for left and right electrode are different. In this case, separate configurations and parameters will be defined for the left and right electrode, respectively, and the multigrid method will be employed in the two-probe calculation. Output control The generated script will, when you run it in ATK, produce verbose output (if you prefer less output, you can modify the verbosity_level defined in the head of the conversion script) a VNL file containing the structure, and a NetCDF checkpoint file. All these files are named after the original input file, but with an additional label "converted" in the name. At the top of the conversion script are a few parameters that furthermore effect the output script:

• include_defaults. If this variable is set to True, the NanoLanguage file will be very explicit, with all parameters specified. If it is False, only parameters which are different from default will be shown, giving simpler and more readable code. Keywords specified in the list explicit_defaults will however always be explicitly printed out in the NanoLanguage code, even if they are assigned default values.
• remove_default_factories. If this parameter is True, empty constructions like basisSetParameters() will be removed, giving much simpler code.
• round_dec. If this is zero, all atom positions are printed "as is", which can give some ugly things like 0.9999999991 instead of 1.0. Setting this parameter to a non-zero (positive) value introduces rounding to the specific number of decimals. 5 seems to work nicely, unless it is of importance that the coordinates are very exact, in which case 8 could be a good value to still avoid values like 4.800000000004. Note that Python is rather clever and does not print trailing zeros (unless specifically asked to). Thus, even if the rounding is set to 5 decimals, a value like 4.800000000004 will be printed simply as 4.8.
• lattice_tolerance. See below.

Specific details The following additional things should be noted about the conversion:

• The script can handle input files for molecules, bulk, and two-probe systems. Electrode files are not converted on their own, but only as part of the two-probe.
• Very limited error checking is performed. The input file is assumed to run properly in ATK 2.0. If it does, the script should be able to convert it.
• Default values are assigned to unspecified parameters using the NanoLanguage standard. Thus, the ATK 2.0 default file is not read and not used.
• K-point keywords are assigned default values corresponding to ATK 2.0 if they are not specified in the input file.
• Note that spin is handled a bit differently in NanoLanguage, so take extra care when converting spin-dependent calculations. The converted script may not exactly correspond to the calculation as defined in ATK 2.0.
• The script fully supports element-specific basis set parameters.
• Relaxation/geometry optimization is supported. In this case, the final configuration will also be stored in the VNL file, with the additional "optimized_geometry" in the sample name.
• All comments in the input files are conserved, and collected at the end of the output script.
• All un-converted keywords are also included in the output script for reference.

In NanoLanguage, it is necessary to specify explicitly the Bravais lattice for bulk systems, while in ATK 2.0 the unit cell was given as just three vectors. The conversion script will attempt to recognize the simplest lattice types:

Code

simple cubic
fcc
bcc
simple tetragonal
simple orthorhombic
rhombohedral
hexagonal

All other lattice types will be represented as Triclinic. This actually has no effect on the calculations, as the lattice type is never used explicitly in NanoLanguage. Note that a tolerance factor is employed in the recognition of the lattice type. This tolerance is used for comparison of angles and lattice constants to each other and known values. The default is 1e-5, which seems to work fine for orthogonal lattices. It might, however, be too low for hexagonal if the lattice vectors are given with few decimals. In that case, it is safe to increase the value to, say, 1e-3. The parameter is easily accessible at the top of the script. Unsupported keywords

• The use of fractional spin is not supported in NanoLanguage. If such keywords are discovered in the input file, the conversion will fail.
• Basis set keywords from the electrode files will be ignored; the same basis set size should anyway always be used for all element in the entire structure, also in ATK 2.0.

• The script cannot yet convert pure analysis scripts; more specifically, the script must contain an atom list (and a unit cell, if it's a bulk system), and so on.

• In fact, no analysis options are, so far, converted. This may be supported in an updated version later on.
• All keywords related to pseudopotentials and ion files are ignored.
• The keywords UnitCell::X0/Y0/Z0 are not supported (they are not used in ATK 2.1 and higher anyway).

• The keyword Relaxation::MaxDisplacement is not supported (it is not used in ATK 2.3 and higher anyway). If you specifically want to use it with ATK 2.2, you can insert it back manually in the generated script. Please refer to the ATK documentation for details.
• Constraints in relaxations are not supported, you need to manually add them by hand afterwards, see the manual.
• The keyword TwoProbe::UseMultigridForElectrostatics is not supported (or rather, it is ignored). In NanoLanguage, the choice between homogeneous and heterogeneous systems is implicit (also see above about multigrid).
• Gate voltage is not supported yet. The corresponding NanoLanguage construction is quite different in nature (see the manual page on gate voltage).

Compatibility notes To make the converted scripts compatible with ATK 2.1 and 2.2 is generally very simple. In fact, most converted scripts will work fine with these versions, and require no changes, except this one: Remove the nlPrint() statements. After that, the first step, if you have an older version of ATK that you wish to use, is to simply test the script! If it fails, try these things to make the script compatible:

• Remove all references to algorithm_parameters. These parameters were introduced in ATK 2.3.
• Change two_center_integral_parameters to two_center_integrals_parameters (an extra "s"). The name of this parameter was changed in ATK 2.3.
• Remove the named parameters optimizer and trust_radius for geometricOptimizationParameters(). The construction was modified in ATK 2.3.

In all cases, these changes should only be necessary if include_defaults was set to True. Final notes You should always inspect the converted file carefully to verify that the conversion was successful, before attempting any calculations. The script has been tested on a large amount of input files, but there may be special situations that have not yet been considered. If the script fails to convert an input file, or the converted script does not correspond to the input, please report the problem in this thread so that we can fix the problem! We hope you will enjoy working with NanoLanguage, and explore and discover the much enhanced flexibility and control that the new input format offers over the old keyword-based input files. This script should hopefully make the transition easier!