Usage Documentation

  1. The input file
  2. Running lisa
  3. Lisa output

  1. The input file

    Table of Contents

    In order to run LISA, one needs to create a single input file with all the necessary input parameters for the desired problem. We have provided a large number of sample input files applying to a variety of different problems in order to help users be able to quickly get started. Therefore, the user should be able to simply modify one of the existing sample files in order to treat their respective problem. The input file is actually written in the Python programming language. Python is a simple, yet extremely powerful, language which is quickly gaining traction within the scientific community. However, the user need not be at all familiar with python in order to use LISA. Below we briefly outline the general rules one needs to know to succesfully create or modify an input file.

    Use of Python in input file
    The input file is a valid python program, and therefore all of the python syntax applies. Generally speaking, the user will only ever need to define a variable, which is trivial. However, it is necessary to know two pertinent details of python. First, a comment is signified by the character #. Anything following # on a given line will not be considered by the program. Second, Python is not a free-form language, meaning that the spacing for the first command on a given line is critical. In the input file, all variables should be defined with no spaces at the beginning of the line (there are a few exceptions to this rule). If this rule is not followed the program will not run.

    The user is free to take advantage of all the features of Python within the input file. For example, one may perform mathematical operations when defining a variable (ie. x=sqrt(3)/2). Additonally, the user may define there own variables which may be used to define other variables that the code requires.

    Basic structure of the input file
    The input file defines a number of variables which depend on the given problem. We seperate the variables into the following categroies for clarity: general parameters, scheme, strucutre, Hamiltonian, forcing terms, interactions, density, and solver. These are considered in detail below, and sample values are given. Certain problems may not require variables from certain categories to be defined.

    General parameters
    This section contains general variables which need to be set for most DMFT applications.

    The maximum number of DMFT iterations to be performed. The calculation may be stopped earlier if the convergence criterion is reached.

    The inverse temperature.

    This variable defines wether or not the calculation should start with a self_energy which is read in from the Sigma file. There will be a number of Sigma files depending on the particular problem being studied (ie. for the single band Hubbard model there will be one Sigma file for the majority spins and one for the minority). For more details see section the LISA output description.

    This variable defines wether or not to use Nambu notation, which is necessary for superconductivity.

    This section contains variables which defines the DMFT "scheme" (ie. single-site, cluster variation of DMFT, Hilbert transform DMFT, etc.).

    Wether to use single-site DMFT (ie. True) or a cluster generalization of DMFT (ie. False). This variable is not used if DMFT_WITH_DENSITY_OF_STATE = True, as only single-site DMFT may be used.

    Performs the DMFT self-consistency condition using a density-of-states (DOS) provided by the user.

    Half_Bandwidths = [sqrt(2),sqrt(2)]
    This variable is only set when DMFT_WITH_DENSITY_OF_STATE = True, and it specifies the half-bandwidth for the Bethe lattice (ie. semi-circular DOS). The example correpsonds to a two-band model (ie. two bands each having a half-bandwidth of sqrt(2)).


    This variable is only set when DMFT_WITH_DENSITY_OF_STATE = True, and it speciefies to use a DOS provided by the user in a file. If this option is used, one obviously does not need to specify Half_Bandwidths which corresponds to the bethe lattice.

    This variable is only set if DMFT_DOS_FILE=True, and it specifies the name of the file which contains the user defined DOS. In this case, the name of the file is dos.input. The first column in the file should be the frequency, and the remaining columns should be the DOS for each given orbital. The file itself defines the number of orbitals to be used in the code for this mode (ie. 3 total columns is a two-band problem). It should be noted that the following line is also necessary in the input file when reading the DOS from a file:

    if DMFT_DOS_FILE: dosfile=[[float(y) for y in s.split()] for s in open(dos_input_file).readlines()]

    This reads in the DOS file and formats it properly. The user does not need to modify this line.

    Crystal Structure
    Dimension_Space =2
    This is the dimension of space (ie. 1, 2, or 3).

    Number_Points_in_Brillouin_Zone = 8
    The number of points for a given dimension in the first Brillouin zone (ie. 64 for two dimensions). This paramter is only used when performing a k-summation using the Riemann summation procedure.

    Lattice_Unit = [(1,0,0) , (0,1,0) ]
    The lattice vectors for the unit cell of interest. The above example corresponds to two spatial dimensions (ie. two vectors are given). It should be noted that the vectors are still given in R3 despite the fact that one is treating a two dimensional problem.

    N_Correlated_Orbitals = 1
    The number of correlated orbitals present in the unit cell.

    Orbital_positions=[ (0,0,0) , (0.5,0.5,0.5) ]
    The positions of all the basis orbitals in the unit cell. The correlated orbitals must be listed BEFORE any uncorrelated orbitals. The positions are given in direct coordinates (ie. in multiples of the lattice vectors). The above case corresponds to a unit cell with two atoms in a three dimensional space (ie. the position of the atom is specified by three numbers).

    Lattice_Tiling_Unit = [ (2,0), (0,2) ]
    This variable defines a supercell. The above example corresponds to a problem with two spatial dimensions in which the original lattice vectors are simply doubled. Integers must be given. It is useful to define a supercell in the case where the unit cell is not large enough to capture a given type of charge/orbital/magnetic ordering. In this case, one still solves an impurity problem for the number of correlated orbitals as speficied in N_Correlated_Orbitals, but the self-consistency condition is performed on the supercell as opposed to the unit cell. In this case the self-energy which is obtained from solving the impurity problem is "embedded" into the supercell. If you do not need to use a supercell, simply specify [(1,0),(0,1)] for the given example (ie. the supercell is identical to the original cell).

    The hopping parameters are specified in this section. This entire section may be omitted if one is doing a DMFT calculation with a DOS.

    Hopping[ (1,0) ] = [[0.5,0.0],[0.0,0.7]]
    This variable specifies the hopping matrix element bewteen the basis orbitals within the unit cell (ie. (0,0) ), and the basis orbitals translated by the vector (1,0) (ie. this vector corresponds to a problem in two spatial dimensions and is given in direct coordinates). The right hand side of the above expression is a matrix (technically this is a list of lists). Given that it is a 2X2 matrix, this example corresponds to a unit cell having two basis orbitals (let us refer to them as alpha/beta). It indicates that the hopping between alpha at (0,0) and (1,0) is 0.5, the hopping between beta at (0,0) and (1,0) is 0.7, and the hopping between alpha and beta is zero. Hopping[(0,0)] would be used to specify the on-site energies. It should be noted that this command can also be written as follows:

    Hopping[ (1,0)  ] = [[0.5,0.0],

    This tends to be helpful in avoiding errors when entering large matrices. This is one of the few examples in which it is acceptable to have space at the beginning of a line.

    Forcing terms
    The variables in this section correspond to static fields which may be added to the Hamiltonian.

    Forcing_F = [0.1, 0.1]
    This variable defines a magnetic field for each orbital within the unit cell. The above example corresponds to the case where there are two orbitals in the unit cell.

    Forcing_AF = [0.1, 0.1]
    This variable defines the magnitude of a magnetic field which will be applied to the supercell. The above example corresponds to the case where there are two orbitals in the unit cell.

    Field_Staggering = [ [1,1], [-1,-1], [-1,-1], [1,1]]
    This variable defines how to stagger the field defined in Forcing_AF on the supercell. In this example, we have a 4X2 matrix. The four rows signifies that there are four unit cell contained within the supercell. The two columns indicates that there are two orbitals within each unit cell. The numbers specified multiply Forcing_AF such that one can specify any desired orderings of the applied field.

    Forcing_SC = [0.0]
    This variable specifies a field which forces a d-wave superconducting state.

    Forcing_DDW = [0.0]
    This variable specifies a field which forces a d-wave density wave.

    Rm_Forcing_after_N_iteration = 1
    This variable specifies at which DMFT iteration the forcing field will be removed. It is often desirable to "kick" the system in a given direction when searching for a given ordering. Therefore it is useful to apply a forcing field for a given number of iterations and see if the system relaxes back to the normal state or if an ordering develops. In this case, the forcing field is removed after one iteration.

    This section specifies wether the calculation will be performed at constant chemical potential or constant density. Formally, the code works with the grand canonical ensemble, so calculations at a constant chemical potential require no extra thought. Constant density calculations work by adjusting the chemical potential at each DMFT iteration during the slef-consistency condition such that the proper density is achieved. Constant density calculations will take slightly longer to converge. Only the first two variables below are pertinent for a constant chemical potential calculation, while the remaining variables must be specified for a constant density calculation.

    Fix_Density = False
    Constant density or constant chemical potential calculation.

    Chemical_potential_init = 0.0
    Initial value of the chemical potential. This value is not changed if Fix_Density=False.

    Density_Required = 0.8
    Desired density for a constant density calculation.

    Precision_Density = 0.01
    The tolerance for the total density.

    Delta_Chemical_Potential = 0.1
    Change in chemical potential that the code uses as it searches for the proper density. This value must be greater than zero.

    Max_loop_mu = 20
    Maximum number of iterations which may be used to find the density.

    Nbre_Iter_wait_adjust_dop = 0
    Number of iterations to wait before adjusting the cheical potential.

    In this section we define which solver is used and variables which are pertinent to the solver.

    Defines which solver to be used. Currently, only QMC_Hirsh_Fye is supported.

    Hirsch-Fye QMC

    Number of points on the real time access used to discretize the Greens function.

    Number of QMC passes.

    Wether or not to compute the susceptibility within QMC.

    U_matrix_anti = [[2,2],[2,2]]
    This variable specifies the interaction between the orbitals within the unit cell having opposite spins. In this case we have two correlated orbitals (let us say alpha/beta). The above matrix specifies the following:

               alpha_dn  beta_dn 
    alpha_up [[ 2 , 2 ],
    beta_up [ 2 , 2 ]]

    In this example the value of the interaction is 2 in all cases.

    U_matrix_para = [[0,1.5],[1.5,0]]
    This has the same format as U_matrix_anti, except it specifies the interaction between orbitals of the same spin. Therefore, the diagonal elements must be zero as two electrons cannot occupy the same spin orbital (ie. Pauli principle). In this case we have made the value slightly smaller indicating that there is exchange present.

  2. Running LISA

    Table of Contents

    There are several modes in which LISA may be run: regular, test, dos/bands, and impurity model.

    Regular mode
    To do a regular run simply do the following:
    lisa.exe input_file
    where lisa.exe is the compiled executable (see installation) and input_file is the name of the input file.

    Test mode
    LISA also may be run in test mode:
    lisa.exe -test input_file

    Test mode simply digests the input file and checks that there are no errors or inconsistencies. Given that the user may need to submit a job to a queu and wait for a processor, it is useful to run in test mode first to make sure the input is consistent and error free.

    Dos/bands mode

    Another mode may be used to calculate the bands and or the DOS of the unperturbed Hamiltonian. In this case we actually provide a seperate executable. This is done such that the main programs for lisa remains uncluttered and easy to read.

    dos_alone.exe -dos input
    dos_alone.exe -bands input

    This is very useful when specifying tight-binding parameters for a complicated Hamiltonian. In this case, it is useful to calcualte the bands/DOS in order to make sure the user has not made any input errors.

    Impurity solver mode

    The final run mode corresponds to using LISA as an impurity solver. It is possible that one may have a code to perform the DMFT self-consistency condition (see, and then it might be desirable to use lisa as an impurity solver. In order to do this, one needs to provide the input file with the following sections: general parameters, interactions, and solver. Additionally, the user must specify the G0_w_INDEX.dat files, which define the impurity model. The following command is used to solve the impurity problem:

    solver_alone.exe input

  3. Lisa output

    Table of Contents

    LISA produces a number of output files, all of which have the naming convention "*_INDEX*.dat". INDEX refers to a set of joint indices for the conserved quantum number (ie. spin up or down) and the non-conserved quantum numbers (ie. orbitals). A possible value for INDEX would be "up_1_1". This corresponds to the spin up Greens function with orbital indices 11. In the case of the frequency functions (ie. see below), all the orbitals within the supercell will be enumerated within INDEX. Alternatively, INDEX for the imaginary time functions will only enumerate orbitals within the unit cell.

    The format of all the files is discussed in detail below. Additionally, LISA writes some information to standard output.

    Standard output
    A variety of details are written to standard output, and we shall describe the important ones. The output begins with an analysis of the input file. First, all of the variables which were present in the input file, but NOT directly requested by LISA are listed. Then, all of the optional variables which were NOT found in the input file are listed along with their default values. The remaining output corresponds to details of the calculation (ie. number of QMC iterations completed, density, number of QMC spins being used, etc.)

    These files correspond to the local frequency Greens function at a given iteration in the calculation. The data in the file is given in the following format:

    Frequency Real(GC) Imag(GC)

    These files contain the moments of the local frequency Greens function (ie. GC_w). A sample file would contain the following:

    1 x 1
    [ (0,0) ]
    1 x 1
    [ (0,0) ]
    1 x 1
    [ (1,0) ]
    1 x 1
    [ (-1.10694,0) ]
    1 x 1
    [ (3.62289,0) ]

    The "1 x 1" terms simply refer to the dimension of the matrix printed on the line which follows. The five values are complex numbers which correspond to the -2, -1, 0, 1, and 2 moments.

    These files contain the local imaginary time Greens function. The format is the following:
    Time GC_t
    Therefore, these files contain two colums, both being real numbers. In constrast to the frequency Greens function, the imaginary time Greens function is stored for every iteration as they are always much smaller than the frequency functions.

    GC_t_INDEX_M1.dat and GC_t_INDEX_M2.dat
    These files contain the first and second moments, respectively, of the imaginary time Greens function. A sample file would be as follows:
    1 x 1
    [ 0.0796510671 ]
    1 x 1
    [ 0.3441088373 ]
    1 x 1
    [ 0.5685278991 ]
    1 x 1
    [ -0.7886543270 ]
    The "1 x 1" terms simply refer to the dimension of the matrix printed on the line which follows. The values correspond to the 1st (2nd) moment of the imaginary time Greens function for a given iteration.

    These files contain values for the corresponding imaginary time functions at the final DMFT iteration.

    Same as GC_w_INDEX.dat but for the bath Greens function.

    Same as GC_w_INDEX_Moments.dat but for the bath Greens function.

    Same as GC_t_INDEX.dat but for the bath Greens function.

    G0_t_INDEX_M1.dat and G0_t_INDEX_M2.dat
    Same as GC_t_INDEX_M1.dat but for the bath Greens function.

    Same as GC_w_INDEX.dat but for the hybridization function.

    Same as GC_w_INDEX_Moments.dat but for the hybridization function.

    Same as GC_w_INDEX.dat but for the self-energy.

    Same as GC_w_INDEX_Moments.dat but for the self-energy.

    The density-density correlations cacluated within QMC. These are calculated for the final DMFT iteration. A sample value in the file is as follows:
    1 1 1 1 0.506899
    where the first four indices correspond to spin-orbitals (ie. each one would vary from 1-4 for a two band Hubbard model) and the last number if the value of the correlation function.