Main programs documentation =========================== This section will give a presentation of the main programs (their capabilities, their limitations, their purpose). For a practical introduction to the programs see the **tutorial**. .. Warning:: Those programs are intended to work with input files strictly given by the Wannier90_ code. The reason being that those input files have clean, ordered, and complete structure perfectly suited for providing the following programs with vital informations. If the user creates its own input files for feeding one of the program below, we cannot ensure that the answer given by the program will be accurate or even correct. .. Note:: All the programs described below make use of the numpy_ utility for the Python_ programming language. For one other program (visualize_defect_influence.py), mayavi_ is also required. 1. Program `visualize_defect_influence.py` : -------------------------------------------- **purpose** 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\ :sub:`z`\"-type Wannier Function is compared to a "p\ :sub:`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. **use** 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 **limitations and assumptions** 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 **what the program outputs** 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. 2. Program `rotate_conductor.py` : ---------------------------------- **purpose** 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. **use** 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 **limitations and assumptions** It is important to realize that this program was first intended for producing Hamiltonian matrices that are "rotationally equivalent" to a given original Hamiltonian matrix. By "rotationally equivalent" we mean that the lead parts of the system have rotational symmetries. We cannot guarantee that this program will fit the user needs if those needs are outside the realm of the orginal purpose. **what the program outputs** 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". 3. Program `compactify_conductor.py` : -------------------------------------- **purpose** 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. **use** 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 **limitations and assumptions** Just like in the case of `visualize_defect_influence.py`, the user needs to modify 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 that, in turn, tells the code which are the matrix elements to "compactify". **what the program outputs** 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. 4. Program `cut_conductor.py` : ------------------------------- **purpose** 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. **use** 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 **limitations and assumptions** This program assumes that the system is ordered in such a way that the "defect" lies in the "middle" of the Hamiltonian matrix. As a consequence, the N first Wannier Functions to the left of the Hamiltonian matrix are supposed to correspond to the left-most lead unit cell if N is the number of Wannier Functions in **one** lead unit cell. The same is true for the "right" unit cells. This fact explains why it is better to "compactify" the Hamiltonian matrix first, so as to gather all the "defect" Wannier Functions in the "middle" of the matrix. **what the program outputs** 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. 5. Program `system_builder.py` : -------------------------------- .. Note:: This program is by far the most important of the main programs. With it, the user will be in a position to create any Large Scale structure from elementary "building blocks". Those building blocks correspond to any "defect" Hamiltonian matrices that the user wishes to insert in the structure. Those Hamiltonian matrices can be produced either by use of some or all of the main programs in this package or can be user defined. Please have a look at the **limitations and assumptions** section for more details about the format of the Hamiltonian matrices. **purpose** This program uses a set of directories containing the Hamiltonian matrices of the different defects and uses them for building the Hamiltonian matrix of a system that can contain as many defects as the user wants. Of course the obvious limitation comes from the size of the Large Scale Hamiltonian matrix. **use** 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. **limitations and assumptions** 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. **what the program outputs** 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. .. Warning:: When building the Large Scale structure, the program joins the defect Hamiltonian matrices together. In doing so, the program is **implicitly** suggesting that the Wannier Function **signs** (Wannier Functions are complex in general but in this case they are real and so a sign uncertainty remains) are known to be consistent from one Hamiltonian matrix to another. This is a **strong** statement, since the Wannier90_ code generally gives *random* signs when it computes the Wannier Functions. As a consequence, it is **the user responsibility** to ensure that the signs of the Wannier Functions are consistent from one defect Hamiltonian matrix to another. In the case of a Silicon Nanowire for example, all the Wannier Functions of the Valence manifold are bonding |sgr|-like in character. As a consequence one could enforce all the Wannier Functions to be "positive" by computing the integral of the Wannier Functions over space and force it to be positive quantity. In this case, there are no worries of sign mismatch when connecting the Hamiltonian matrices of two distinct defects. .. _Python: http://www.python.org .. _Wannier90: http://www.wannier.org .. _numpy: http://numpy.scipy.org/ .. _mayavi: http://code.enthought.com/projects/mayavi/ .. |sgr| unicode:: U+003C3