Main programs documentation¶

This program uses the *_tran_info.dat file given by the Wannier90 code and makes use of the constraints function defined in the constraints.py Python module in the utilities directory.

With those two files, the program tries to extract the “on-site” matrix elements of the Wannier Functions and plots the deviations of those matrix elements with respect to given reference values.

The reference value of a given Wannier Function is taken to be the “on-site” matrix element of an “equivalent” Wannier Function that belongs to the left-most unit cell of the system.

By “equivalent” we mean a Wannier Function that is geometrically equivalent in the two orthogonal directions to the direction of conduction, and equivalent in “nature” (a “p_z“-type Wannier Function is compared to a “p_z“-type, etc...). We try not to compare apples and oranges...

The left-most unit cell being the farther away from the defect (which belongs to the central region), we expect the “on-site” elements of the Wannier Functions in this cell to be little influenced by the defect. As a consequence their “on-site” matrix elements should be “bulk-like” and so suited for playing the role of a reference value.

The program is called from the command-line. The possible options are

[prompt] python visualize_defect_influence.py [options]

[options]
-f, --file,  this corresponds  to the name of the *_tran_info.dat file
-p, --print, a boolean to decide whether an ouput of the deviations is
             desired

Like every program built for a purpose, this latter one has been built on assumptions and is limited in its capacities.

The first assumption made by the program is that the user has been modifying the constraints function inside the constraints.py module. This function will help the program to distinguish between Wannier Functions belonging to the system backbone and Wannier Functions belonging to the “defect”. It is imperative that the user modifies this function in order to describe properly the positions of the system’s defect Wannier Functions.

The program will try to determine what is the “equivalent” Wannier Function in the left-most unit cell for a given Wannier Function in the system. For this, the program basically projects the coordinates of the Wannier Function centre onto the left-most unit cell. Then it tries to find the Wannier Function in this unit cell which is the closest geometrically. Moreover we also make sure that the “on-site” matrix elements are also “close” in absolute value. If a Wannier Function in the left-most unit cell satisfies those criteria, then it will considered to be a potential “equivalent” Wannier Function. When all the potential candidate “equivalent” Wannier Functions have been found, we select the one that is both closest in geometric distance and matrix element value.

The program also assumes that the list of Wannier Functions given by the file *_tran_info.dat, is given in the properly sorted order. If the user uses the file produced by the Wannier90 code, there should not be any problem.

Finally, in order to plot the Wannier Functions and deviations of the matrix elements, the program makes use of a very powerful and open-source third-party program called mayavi2. So the user needs to make sure that this program has been installed on his/her computer and is “importable” in from within another Python program. On Ubuntu systems, the installation of this program is as simple as

[prompt] sudo apt-get install mayavi2

The program will always produce a 3D plot of the structure (atoms represented by white/light gray balls all of the same size) and the deviations to the “on-site” matrix elements (in color with sizes changing with the deviation). Basically the more pronounced the color and the bigger the ball, the bigger the deviation is from the reference value.

Optionally (with command-line option -p or --print), the user can request a file containing diverse informations, among which is the deviation for each Wannier Function’s “on-site” element.

The goal of this program is to “rotate” an Hamiltonian matrix. By “rotate”, we mean that, given the order of the Wannier Function basis used to express the original Hamiltonian basis, the program will rotate the Wannier Functions in real-space and re-order the basis. Once the basis has been re-ordered, then a new Hamiltonian matrix, expressed in this “rotated” basis, can be computed.

In order to have a feeling for what the program is doing, imagine a Carbon Nanotube or a Silicon Nanowire having a defect in its center. Then one can compute the Hamiltonian matrix of that whole system by having Wannier90 do it for you (“lcr”-type quantum conductance calculation). Now this Hamiltonian matrix (contained in seedname_htC.dat) has been expressed in a basis of Wannier Functions ordered internally by Wannier90 for maximum transferability. Imagine now that the lead part of the system has a 60-degre rotational symmetry about the main axis. We would like to be able to express the Hamiltonian matrix of the “60-degre rotated” system. Then this is exactly what this program is doing.

The program is called from the command-line. The possible options are

[prompt] python rotate_conductor.py [options]

[options]
-f, --file,   this corresponds  to the name of the *_tran_info.dat file
-m, --matrix, string corresponding to the name of the Hamiltonian matrix
              file
-a, --angle,  angle in radians for the rotation about the main axis
-d, --delta,  optional parameter used internally to group the Wannier
              Functions together. This parameter is completely equivalent
              to the tran_group_threshold parameter in Wannier90

The program will give 2 outputs:

• a file containing the rotated Hamiltonian matrix in the same format as the one in Wannier90
• a file corresponding to the new *_tran_info.dat file. This is necessary since both the atoms and the Hamiltonian matrix have been “rotated”.

The purpose here is to gather all the matrix elements involving at least one Wannier Function belonging to the “defect” region. Once gathered, the Wannier Function basis in which the Hamiltonian matrix is expressed is re-ordered in such a way to insert the “defect” Wannier Functions in the “middle” of the new basis.

The goal in doing so is to “compactify” the Hamiltonian matrix and so enhance transferability. Indeed, transferability is dictated by the length of the left and right leads on both side of the defect region. The longer those lead regions are, the more transferable the matrix will be when connecting it to other Hamiltonian matrices that have similar lead structures.

The program is called from the command-line. The possible options are

[prompt] python compactify_conductor.py [options]

[options]
-f, --file,   this corresponds  to the name of the *_tran_info.dat file
-m, --matrix, string corresponding to the name of the Hamiltonian matrix
              file

The program gives 2 output files:

• One which contains the “compactified” Hamiltonian matrix (in the same format as the one in Wannier90
• a file corresponding to the new *_tran_info.dat file. This is necessary since the order of the Wannier Function basis has been altered.

This program takes a Hamiltonian matrix and removes as many lead unit cells on each side of the “defect” as the user wants to. The purpose here is to produce “shorter” Hamiltonian matrices that will enable the user to build Large Scale structures with a higher density of defects per unit length.

For optimal use, it is best to have “compactified” the Hamiltonian matrix in a previous step (using compactify_conductor.py) even though this is ablsolutely not a requirement.

The program is called from the command-line. The possible options are

[prompt] python cut_conductor.py [options]

[options]
-f, --file,     this corresponds  to the name of the *_tran_info.dat file
-m, --matrix,   string corresponding to the name of the Hamiltonian matrix
                file
-p, --positions a boolean to tell the code whether the user wants the atomic
                positions to be printed out or not. Default is "False"
-a, --all       a boolean to decide whether all the possible Hamiltonian
                matrices resulting from all the possible ways to cut the
                original Hamiltonian matrix are to be outputed

The program will produce one or many directories. In each of those directories, there will be at least one file corresponding to a reduced Hamiltonian matrix (an Hamiltonian matrix resulting from the “cut” of the original Hamiltonian matrix). The names for the directories are quite obvious. For example 0_left_1_right means that this directory contains the Hamiltonian matrix resulting from the operation of removing 1 unit cell to the right of the original matrix.

Optionally, the user can request to also produce the atomic positions in XYZ format for the reduced system. Those positions are simply the original atomic positions of the conductor part of the system from which one or many unit cells have been removed to the left and/or to the right.

The program is called from the command-line. The possible options are

[prompt] python system_builder.py [options]

[options]
-c, --custom,  this tells the code that the user wishes to input the sequence
               of defect(s) him/her-self
-r, --random,  this tells the code that a random sequence of defects will be
               constructed
-p, --path,    this is a string corresponding to the full path to the directory
               containing all the defect(s) directories

Beyond those 3 command-line options, the user will be walked through a set of questions enabling the code to acquire sufficient information about the system and build it.

It is important to be aware of all the assumptions/requirements for the program to work correctly.

First of all, the programs needs a root directory. The full path to this root directory should be given to the program through the “-p” command line option. By default, the program takes the current working directory “./” to be the root directory unless the user provides the full path him/her-self.

Second, the root directory should contain a set of directories, one for each distinct defect. Each of those directories should contain at most 2 files. The first one should correspond to the Hamiltonian matrix of the defect. This file should end with _htC.dat. Optionnaly another file corresponding to the atomic positions of the defect and ending with .xyz can be present. The optional position file is given in XYZ format with the extra information of the system’s length at the beginning of the second line.

This program will outputs all the necessary files for an LCR-type of calculation with Wannier90. Just move into this directory and from there type:

wannier90.x random_system

or

wannier90.x custom_system

depending on what type of system the user built.