Skip to content

Python package

The KITE package for pre-processing is split up in various subclasses and contains several functions:

StructuralDisorder

class kite.StructuralDisorder(lattice, concentration=0, position=None)

Class that introduces Structural Disorder into the initially built pb.Lattice.
Parameters
lattice: pb.Lattice
The lattice used to build the structural disorder.
concentration: float
Concentration of disorder (can only be different from 0 if position=None).
position: array_like
Exact position of disorder (can only be different from None if concentration=0).
Methods
Method Description
add_vacancy(*disorder) Add vacancy disorder to the lattice.
add_structural_disorder(*disorder) Add structural disorder to the lattice.
add_local_vacancy_disorder(relative_index, sub) Internal function to add one vacancy disorder to chosen position.
add_local_bond_disorder(relative_index_from, [, ...]) Internal function to add one bond disorder between chosen positions.
add_local_onsite_disorder(relative_index, [, ...]) Internal function to add one onsite disorder to chosen position.
map_the_orbital(orb, nodes_map) Internal function to map the orbitals to the NodesMap.

function add_vacancy(*disorder)

Add vacancy disorder to the lattice.

Parameters
Parameter Description
*disorder:str or tuple(array_like, str) Vacancy disorder, in the form of sublattice_name or ([relatice_index], sublattice_name)

functionadd_structural_disorder(*disorder)

Add structural disorder to the lattice.

Parameters
Parameter Description
*disorder:tuple(array_like, str, float) or tuple(array_like, str, array_like, str, array_like) or tuple(array_like, str, array_like, str, float) or tuple(array_like, str, array_like) Vacancy disorder, in the form of ([relatice_index], sublattice_name, onsite_energy) or ([relatice_index_from], sublattice_name_from, [relatice_index_to], sublattice_name_to, onsite_energy)

functionadd_local_vacancy_disorder(relative_index, sub)

Internal function to add one vacancy disorder to chosen position.

Parameters
Parameter Description
relative_index:array_like Relative index of the position to change the onsite energy.
sub:str Name of the sublattice to change the onsite energy.

function add_local_bond_disorder(relative_index_from, from_sub, relative_index_to, to_sub, hoppings)

Internal function to add one bond disorder between chosen positions.

Parameters
Parameter Description
relative_index_from:array_like Relative index of the position from wich the bond connects to change the onsite energy.
from_sub:str Name of the sublattice from wich the bond connects to change the onsite energy.
relative_index_to:array_like Relative index of the position to wich the bond connects to change the onsite energy.
to_sub:str Name of the sublattice to wich the bond connects to change the onsite energy.
hoppings:float or array_like The hopping energy between the different sublattices at the given positions, with the right shape to connect between the orbitals.

function add_local_onsite_disorder(relative_index, sub, value)

AInternal function to add one onsite disorder to chosen position.

Parameters
Parameter Description
relative_index:array_like Relative index of the position to change the onsite energy.
sub:str Name of the sublattice to change the onsite energy.
value:float or array_like The onsite energy of sublattice at the given positions, with the right shape for the orbitals.

function map_the_orbital(orb, nodes_map)

Internal function to map the orbitals to the NodesMap.

Parameters
Parameter Description
orb:str Name of the sublattice to give a unique value.
nodes_map:dict The object that stores the unique values for the sublattices.

Disorder

class kite.Disorder(lattice)

Class that introduces Disorder into the initially built pb.Lattice.

The informations about the disorder are the type, mean value, and standard deviation. The function that you can use in the bulding of the pb.Lattice is add_disorder(). The class method takes care of the shape of the disorder chosen (it needs to be same as the number of orbitals at a given atom), and takes care of the conversion to the c++ orbital-only format.

Parameters
lattice: pb.Lattice
The lattice used to build the disorder.
Methods
Method Description
add_disorder(sublattice [, ...]) Add the disorder to the lattice.
add_local_disorder(sublattice_name [, ...]) Internal function to add the disorder to the positions.

function add_disorder(sublattice, dis_type, mean_value, standard_deviation=0.)

Add the disorder to the lattice.

Parameters
Parameter Description
sublattice:str or list(str) Name of the sublattice to give a unique value.
dis_type:int or list(int) The type of disorder to apply, possible values are "Gaussian", "Uniform", "Deterministic", "gaussian", "uniform" or "deterministic".
dis_mean_valuetype:float or list(float) Mean value of the deformation.
standard_deviation:float or list(float) Standard deviation of the deformation.

functionadd_local_disorder(sublattice_name, dis_type, mean_value, standard_deviation)

Internal function to add the disorder to the positions.

Parameters
Parameter Description
sublattice:list(str) Name of the sublattices to give a unique value.
dis_type:list(int) The type of disorder to apply, possible values are "Gaussian", "Uniform", "Deterministic", "gaussian", "uniform" or "deterministic".
dis_mean_valuetype:list(float) Mean value of the deformation.
standard_deviation:list(float) Standard deviation of the deformation.

Modification

class kite.Modification(magnetic_field=None, flux=None)

Class that modifies the initially built pb.Lattice with a magnetic field.
Parameters
magnetic_field: float
Add the magnetic field to the lattice. The field will point along the second primitive lattice vector of the lattice. The magnetic field is in units of \(Tesla\), if the pb.Lattice is in units of \(nm\). The magnetic field is rounded down to the nearest flux quantum.
flux: float
Add the magnetic flux to the lattice.
Attributes
Attribute Description
magnetic_field:float The added magnetic field to the lattice.
flux:float The added magnetic flux to the lattice. This is not* the exact value used in the calculation, but the value added using the parameter above.

Configuration

class kite.Configuration(divisions=(1, 1, 1), length=(1, 1, 1), boundaries=('open', 'open', 'open'), is_complex=False, precision=1, spectrum_range=None, angles=(0,0,0), custom_local=False, custom_local_print=False)

Define the basic parameters used in the calculation
Parameters
divisions: int or tuple(int, int) or tuple(int, int, int)
Number of decomposition parts of the system.
length: int or tuple(int, int) or tuple(int, int, int)
Number of unit cells in each direction.
boundaries: str or tuple(str, str) or tuple(str, str, str)
Periodic boundary conditions each direction. Possible values are "periodic", "open", "twisted"*(this option needs the extra argument angles and "random"
is_complex: bool
Boolean that reflects whether the type of Hamiltonian is complex or not.
precision: int
Integer which defines the precision of the number used in the calculation, float (0), double (1), long double (2).
spectrum_range: tuple(float, float)

Energy scale which defines the scaling factor of all the energy related parameters. The scaling is done automatically in the background after this definition. If the term is not specified, a rough estimate of the bounds is found.

Warning

Automatic scaling can lead to segmentation-errors due to an error in pybinding.

angles: float or tuple(float, float) or tuple(float, float, float)
The angles used for the twisted boundary conditions when boundary="twist" is selected. The values of anglemust be in the interval \([0, M \cdot 2 \pi]\).
custom_local: bool
Boolean that reflects whether the calculation should use the user-defined local potential.
custom_local_print: bool
Boolean that reflects whether the calculation should use output the values for the local potential for the various sublattices of the pb.Lattice.
Attributes
Attribute Description
energy_scale:float Returns the energy scale of the hopping parameters.
energy_shift:float Returns the energy shift of the hopping parameters around which the spectrum is centered.
comp:int Returns 0 if hamiltonian is real and 1 elsewise.
prec:int Returns 0, 1, 2 if precision if float, double, and long double respectively.
div:int Returns the number of decomposed elements of matrix in \(x\), \(y\) and/or \(z\) direction. Their product gives the total number of threads spawn.
bound:tuple(array_like, array_like) Returns the boundary conditions in each direction, the first argument describes the boundary conditions for the various dimensions with 0 - open boundary condtions, 1 - periodic or twisted boundary conditions, 2 - random boundary conditions, the second gives the angle used if boundary="twist" was chosen.
leng:array_like Return the number of unit cell repetitions in each direction.
type:np.float32 or np.float64 or np.float128 or np.float256 Return the type of the Hamiltonian complex or real, and float, double or long double.
custom_pot:bool Return custom potential flag.
print_custom_pot:bool Return print custom potential flag.
Methods
Method Description
set_type() Internal function to determine the precision to be used during the calculation.

function set_type()

Internal function to determine the precision to be used during the calculation.

Calculation

class kite.Calculation(configuration=None)

Class that contains the required target functions to calculate in later steps.
Parameters
configuration: kite.Configuration
A kite.Configuration that contains the settings for the calculation.
Attributes
Attribute Description
get_dos:dict Returns the requested DOS functions.
get_ldos:dict Returns the requested LDOS functions.
get_arpes:dict Returns the requested ARPES functions.
get_gaussian_wave_packet:dict Returns the requested wave packet time evolution function, with a gaussian wavepacket mutiplied with different plane waves.
get_conductivity_dc:dict Returns the requested DC conductivity functions.
get_conductivity_optical:dict Returns the requested optical conductivity functions.
get_conductivity_optical_nonlinear:dict Returns the requested nonlinear optical conductivity functions.
get_singleshot_conductivity_dc:dict Returns the requested singleshot DC conductivity functions.
Methods
Method Description
dos(num_points, num_moments, [, ...]) Calculate the density of states as a function of energy.
ldos(energy, num_moments, [, ...]) Calculate the local density of states as a function of energy.
arpes(k_vector, weight [, ...]) Calculate the spectral contribution for given k-points and weights.
gaussian_wave_packet(num_points [, ...]) Calculate the time evolution function of a wave packet.
conductivity_dc(direction, [, ...]) Calculate the DC conductivity for a given direction.
conductivity_optical(direction, [, ...]) Calculate optical conductivity for a given direction.
conductivity_optical_nonlinear([...]) Calculate nonlinear optical conductivity for a given direction.
singleshot_conductivity_dc(energy, [...]) Calculate the DC conductivity using KITEx for a given direction and energy.

function dos(num_points, num_moments, num_random, num_disorder=1)

Calculate the density of states as a function of energy.

Parameters
Parameter Description
num_points:int Number of energy point inside the spectrum at which the DOS will be calculated.
num_moments:int Number of polynomials in the Chebyshev expansion.
num_random:int Number of random vectors to use for the stochastic evaluation of trace.
num_disorder:int Number of different disorder realisations.

functionldos(energy, num_moments, position, sublattice, num_disorder=1)

Calculate the local density of states as a function of energy.

Parameters
Parameter Description
energy:array_like List of energy points at which the LDOS will be calculated.
num_moments:int Number of polynomials in the Chebyshev expansion.
position:int Relative index of the unit cell where the LDOS will be calculated.
sublattice:list Name of the sublattice at which the LDOS will be calculated.
num_disorder:str or list Number of different disorder realisations.

functionarpes(k_vector, weight, num_moments, num_disorder=1)

Calculate the spectral contribution for given k-points and weights.

Parameters
Parameter Description
k_vector:array_like List of K points with respect to reciprocal vectors b0 and b1 at which the band structure will be calculated.
weight:array_like List of orbital weights used for ARPES.
num_moments:int Number of polynomials in the Chebyshev expansion.
num_disorder:int Number of different disorder realisations.

functiongaussian_wave_packet(num_points, num_moments, timestep, k_vector, spinor, width, mean_value, num_disorder=1, probing_point=0)

Calculate the time evolution function of a wave packet.

Parameters
Parameter Description
num_points:int Number of time points for the time evolution.
num_moments:int Number of polynomials in the Chebyshev expansion.
timestep:float Timestep for calculation of time evolution.
k_vector:array_like Different wave vectors, components corresponding to vectors b0 and b1.
spinor:array_like Spinors for each of the k vectors.
width:float Width of the gaussian.
mean_value:tuple(float, float) Mean value of the gaussian envelope.
num_disorder:int Number of different disorder realisations.
probing_point:int or array_like Forward probing point, defined with x, y coordinate were the wavepacket will be checked at different timesteps.

functionconductivity_dc(direction, num_points, num_moments, num_random, num_disorder=1, temperature=0)

Calculate the DC conductivity for a given direction.

Parameters
Parameter Description
direction:str Direction in \(xyz\)-coordinates along which the conductivity is calculated, supports "xx", "yy", "zz", "xy", "xz", "yx", "yz", "zx", "zy".
num_points:int Number of energy point inside the spectrum at which the DOS will be calculated.
num_moments:int Number of polynomials in the Chebyshev expansion.
num_random:int Number of random vectors to use for the stochastic evaluation of trace.
num_disorder:int Number of different disorder realisations.
temperature:float Value of the temperature at which we calculate the response. If \(eV\) is used as unit for energy, then \(k_B\cdot T\) is also in \(eV\). To define the temperature in arbitraty units, specify the quantity \(K_B \cdot T\), which has units of energy.

functionconductivity_optical(direction, num_points, num_moments, num_random, num_disorder=1, temperature=0)

Calculate optical conductivity for a given direction.

Parameters
Parameter Description
direction:str Direction in \(xyz\)-coordinates along which the conductivity is calculated, supports "xx", "yy", "zz", "xy", "xz", "yx", "yz", "zx", "zy".
num_points:int Number of energy point inside the spectrum at which the DOS will be calculated.
num_moments:int Number of polynomials in the Chebyshev expansion.
num_random:int Number of random vectors to use for the stochastic evaluation of trace.
num_disorder:int Number of different disorder realisations.
temperature:float Value of the temperature at which we calculate the response. If \(eV\) is used as unit for energy, then \(k_B\cdot T\) is also in \(eV\). To define the temperature in arbitraty units, specify the quantity \(K_B \cdot T\), which has units of energy.

functionconductivity_optical_nonlinear(direction, num_points, num_moments, num_random, num_disorder=1, temperature=0, special=0)

Calculate nonlinear optical conductivity for a given direction.

Parameters
Parameter Description
direction:str Direction in \(xyz\)-coordinates along which the conductivity is calculated, supports all the combinations of the directions "x", "y" and "z" with length 3 like "xxx", "zzz", "xxy", "xxz" etc.
num_points:int Number of energy point inside the spectrum at which the DOS will be calculated.
num_moments:int Number of polynomials in the Chebyshev expansion.
num_random:int Number of random vectors to use for the stochastic evaluation of trace.
num_disorder:int Number of different disorder realisations.
temperature:float Value of the temperature at which we calculate the response. If \(eV\) is used as unit for energy, then \(k_B\cdot T\) is also in \(eV\). To define the temperature in arbitraty units, specify the quantity \(K_B \cdot T\), which has units of energy.
special:int Optional, a parameter that can simplify the calculation for some materials.

functionsingleshot_conductivity_dc(energy, direction, eta, num_moments, num_random, num_disorder=1, preserve_disorder=False)

Calculate the DC conductivity using KITEx for a given direction and energy.

Processing the output of singleshot_conductivity_dc()

singleshot_conductivity_dc() works different from the other target-functions in that a single run with KITEx is sufficient. The results don't have to be processed by KITE-tools. As such, the results are already available in the HDF5-file. You can extract the results from the HDF5-file as explained in the tutorial.

There is also a script that automates this process with, "output.h5" the name of the HDF5-file processed by KITEx:

python3 process_single_shot.py output.h5

this will result in a data-file "output.dat", as explained in the API of KITE-tools.

Parameters
Parameter Description
energy:array_like or float Array or a single value of energies at which singleshot_conductivity_dc will be calculated.
direction:str Direction in \(xyz\)-coordinates along which the conductivity is calculated, supports "xx", "yy" and "zz".
eta:int Parameter that affects the broadening of the kernel function.
num_moments:int Number of polynomials in the Chebyshev expansion.
num_random:int Number of random vectors to use for the stochastic evaluation of trace.
num_disorder:int Number of different disorder realisations.
preserve_disorder:bool Optional.

make_pybinding_model

function kite.make_pybinding_model(lattice, disorder=None, disorder_structural=None, shape=None)

Build a Pybinding model with disorder used in Kite. Bond disorder or magnetic field are not currently supported.

Parameters
Parameter Description
lattice:pb.Lattice Pybinding lattice object that carries the info about the unit cell vectors, unit cell cites, hopping terms and onsite energies.
disorder:kite.Disorder Class that introduces kite.Disorder into the initially built lattice. For more info check the kite.Disorder class.
disorder_structural:kite.StructuralDisorder Class that introduces kite.StructuralDisorder into the initially built lattice. For more info check the kite.StructuralDisorder class.
shape:pb.Shape Optional argument pb.Shape.

estimate_bounds

function kite.estimate_bounds(lattice, disorder=None, disorder_structural=None)

Estimate the bounds for the energy, given the pb.Lattice and/or kite.Disorder and/or kite.StructuralDisorder.

Parameters
Parameter Description
lattice:pb.Lattice Pybinding lattice object that carries the info about the unit cell vectors, unit cell cites, hopping terms and onsite energies.
disorder:kite.Disorder Class that introduces kite.Disorder into the initially built lattice. For more info check the kite.Disorder class.
disorder_structural:kite.StructuralDisorder Class that introduces kite.StructuralDisorder into the initially built lattice. For more info check the kite.StructuralDisorder class.

config_system

function kite.config_system(lattice, config, calculation, modification=None, filename="kite_config.h5", disorder=None, disorder_structural=None)

Export the lattice and related parameters to the *.h5 file.

Parameters
Parameter Description
lattice:pb.Lattice Pybinding lattice object that carries the info about the unit cell vectors, unit cell cites, hopping terms and onsite energies.
config:kite.Configuration kite.Configuration object, basic parameters defining size, precision, energy scale and number of decomposition parts in the calculation.
calculation:kite.Calculation kite.Calculation object that defines the requested functions for the calculation.
modification:kite.Modification If specified kite.Modification object, has the magnetic field selection, either in terms of field, or in the number of flux quantum through the selected system.
filename: str Filename for the output HDF5-file.
disorder:kite.Disorder Class that introduces kite.Disorder into the initially built lattice. For more info check the kite.Disorder class.
disorder_structural:kite.StructuralDisorder Class that introduces kite.StructuralDisorder into the initially built lattice. For more info check the kite.StructuralDisorder class.

LoudDeprecationWarning

Deprecationwarning.