Parameters for describing physical systems
system.object
keyword: system.object
possible values: a file name of a saved cNanodcal object
default value: [] (empty)
description: If it is not empty, the system is defined by the input object. In this case, all other parameters related to the system in the input file will not be used.
an example:
system.object = 'NanodcalObject.mat'
system.name
keyword: system.name
possible values: any string
default value: ‘dcalSystem’
description: a string provided by user to label the system and it is not used in the calculation.
an example:
system.name = 'Si-nanowire'
system.spinType
keyword: system.spinType
possible values: ‘NoSpin’, ‘CollinearSpin’, ‘GeneralSpin’
default value: ‘NoSpin’
description: within the framework of non-relativistic theory, spin should be an intrinsic physical property of the system rather than an input parameter. Usually, some knowledge about the type of spin is known before the calculation and this priori knowledge can be used to save computation time. From the computational point of view, the parameter spinType is needed.
We first define a vector of spin polarization which, of course, is along the direction of the polarization. Its amplitude is defined as a ratio of (N_p-N_ap)/(N_p+N_ap), where N_p (N_ap) is the number of electrons whose spin are (anti) parallel to the spin polarization. By considering the N above as the charge density, spin polarization can also be viewed as a function of position in the system.
‘NoSpin’ is used for a system in which spin polarization is zero; ‘CollinearSpin’ is used for a system in which spin polarizations at different places are all along the same direction (either parallel or anti-parallel); ‘GeneralSpin’ is used for a system in which spin polarizations at different places have their own directions, or there is no a priori knowledge about the spins in the system.
an example:
system.spinType = 'NoSpin'
system.centralCellVectors
keyword: system.centralCellVectors
possible values: 3 x 3 or 1 x 6 or 1 x 3 double matrix
default value: (1) For a system without leads, the system will be considered as a molecule when the parameter centralCellVectors is not given, and it will be determined by nanodcal automatically. (2) For a system with leads, the parameter centralCellVectors may be automatically determined by the geometry of the leads and the buffer layers. (3) There is no default value for a periodic system, it must be given, otherwise the system will be considered as a molecule by nanodcal.
description: This parameter defines the three base vectors of the central cell, either the primitive or super cell for a periodic system or the central scattering region for an open system, which is with a shape of parallelepiped. When the parameter is a 3 x 3 double matrix, its each column forms one of the three basis vectors. When the parameter is a 1 x 6 double matrix, it defines the three basis vectors by their lengths a,b,c; and the angles between them, alpha, beta, gamma. The convention is that the a-axis is collinear with x-axis, and the b-axis lies in the xy-plane. When the parameter is a 1 x 3 double matrix, the alpha, beta, gamma angles are all equal to pi/2.
The default unit for angle is degree.
an example:
system.centralCellVectors = ...
[[1.3 0 0]' [0 1.6 0]' [0 0 2.5]']
system.atomBlock
keyword: system.atomBlock
possible values: N (the number of atoms in the central cell)
default value: no default value, must be input
description: all neutral atom properties related to the atoms which consist in the central cell are defined in this block. This line must immediately be followed by another (N+2) lines: one line of headers, N data lines for all of the N atoms, and finally a line with a single word ‘end’ to indicate the end of the atomic data block.
The first four headers in the header line must be (not necessarily in order) ‘X’, ‘Y’, ‘Z’, and ‘AtomType’. The value of [X Y Z] describes the position of each site in the system (see also the parameter system.atomCoordinateFormat). The value of ‘AtomType’ describes what atomic species is located in that site, it is normally the symbol of the atomic element.
Another header must be given is ‘OrbitalType’ which describes what atomic orbitals of the atoms are used as the wavefunction basis in the LCAO calculation. It is normally ‘SZ’, ‘SZP’, ‘DZ’, or ‘DZP’. While ‘AtomType’ and ‘OrbitalType’ could be any string specified by an user, the pre-calculated data file of the corresponding neutral atom must be named as ‘AtomType_OrbitalType.nad’, or ‘AtomType_OrbitalType.mat’, and located in where defined by the parameter neutralAtomDataDirectory. See manual for more information about the data files concerning the neutral atoms.
The value of ‘OrbitalType’ of each individual atom can be specified differently, i.e., all atoms can have their own unique basis different from each other, even if they have the same ‘AtomType’. If all the atoms have the same ‘OrbitalType’, the ‘OrbitalType’ can be specified elsewhere in one shot for all the atoms by the parameter system.orbitalType.
Other possible headers are ‘SpinPolarization’, ‘SpinPolarization_x’, ‘SpinPolarization_y’, ‘SpinPolarization_z’; ‘SpinPolarization_r’, ‘SpinPolarization_theta’, ‘SpinPolarization_phi’; etc. ‘SpinPolarization’ is used for ‘CollinearSpin’ system to describe the initial polarization of the atom. The set of ‘SpinPolarization_x’, ‘SpinPolarization_y’, and ‘SpinPolarization_z’ and the set of ‘SpinPolarization_r’, ‘SpinPolarization_theta’, and ‘SpinPolarization_phi’ are used for ‘GeneralSpin’ system to describe the initial polarization of the atom.
The default unit of angle is degree.
an example:
system.atomBlock = 2
AtomType OrbitalType X Y Z SpinPolarization
Fe DZP 0.000000 0.000000 0.000000 0.200000
Fe DZP 2.610100 2.610100 2.610100 0.200000
end
system.atomFile
keyword: system.atomFile
possible values: any string representing the name of an input atomfile
default value: no default value
description: In this alternative input mode, the content of the data block of system.atomBlock is written into a separate file (See the description of system.atomBlock). The file atomFile contains (N+2) lines where N is the number of atoms in the central cell. While the first line is the integer N, the rest (N+1) lines are exactly the same as those defined in the block of system.atomBlock. The line of ‘end’ is needed when there are extra data lines after the (N+2) line in the file. This input value will not be used when system.atomBlock is given.
an example:
system.atomFile = 'system.xyz'
system.atomCoordinateFormat
keyword: system.atomCoordinateFormat
possible values: ‘cartesian’ or ‘fractional’
default value: ‘cartesian’
description: The format of the atomic coordinates defined in system.atomBlock or system.atomFile. If ‘cartesian’, the coordinates are defined in the normal cartesian system. If ‘fractional’, the coordinates are defined on the basis of system.atomFractionalCoordinateBaseVectors.
an example:
system.atomCoordinateFormat = 'fractional'
system.orbitalType
keyword: system.orbitalType
possible values: any string
default value: ‘AtomicData’
description: orbitalType describes what atomic orbitals of the atoms are used as the wavefunction basis in the LCAO calculations. See relevant part of the description of system.atomBlock. The input value will not be used when the information of orbital type has been given in system.atomBlock or in the file of system.atomFile.
an example:
system.orbitalType = 'DZP'
system.neutralAtomDataDirectory
keyword: system.neutralAtomDataDirectory
possible values: any string representing the directory where the calculated neutral atom data are saved.
default value: the current directory
description: The is directory where the neutral atom (basis) files needed for the calculation are saved.
an example:
system.neutralAtomDataDirectory = '../neutralatomdata'
system.numberOfLeads
keyword: system.numberOfLeads
possible values: 0, 2 (number of leads in the system)
default value: 0
description: the number of leads (probes) in the system.
an example:
system.numberOfLeads = 2
system.typeOfLead1, system.typeOfLead2, …
keyword: system.typeOfLead1, system.typeOfLead2, …
possible values: ‘top’, ‘bottom’, ‘front’, ‘back’, ‘left’, and ‘right’
default value: no default value, must be given
description: the value must be given for each of the leads in the system. It describes the relative position of the lead to the central scattering region. More precisely, ‘left’ means the direction of [ 0 0 -1] ‘right’ means the direction of [ 0 0 1] ‘top’ means the direction of [ 0 1 0] ‘bottom’ means the direction of [ 0 -1 0] ‘front’ means the direction of [-1 0 0] ‘back’ means the direction of [ 1 0 0]
In two-probe calculations, the pair of ‘left’ and ‘right’ is recommended for possible better computation efficiency.
an example:
system.typeOfLead1 = 'left'
system.typeOfLead2 = 'right'
system.voltageOfLead1, system.voltageOfLead2
keyword: system.voltageOfLead1, system.voltageOfLead2
possible values: V, a double value
default value: 0
description: the bias voltage applied to the lead, in the unit of Volt. The change of chemical potential of the lead due to the bias voltage is -eV.
an example:
system.voltageOfLead1 = 0
system.voltageOfLead2 = 1.2
system.spinDirectionOfLead1, system.spinDirectionOfLead2
keyword: system.spinDirectionOfLead1, system.spinDirectionOfLead2
possible values: a 3 x 1 array, a 2 x 1 array, or a number
default value: the direction of the total spin of a lead which is calculated as a periodic bulk system
description: If a lead which is a periodic bulk structure has freedom to change the direction of its total spin, this input parameter gives the desired direction of the total spin of that lead when it is used as a part of the device system.
When it is a 3 x 1 array, this input is a directional vector (not necessarily normalized) defined in cartesian coordinates. When it is a 2 x 1 array, this input is a directional vector defined in spherical coordinate system, i.e, [theta, phi]. When it is a number s, it means the the direction is [0, 0, s].
an example:
system.spinDirectionOfLead1 = [0 0 1]
system.spinDirectionOfLead2 = [0 0 -1]
system.objectOfLead1, system.objectOfLead2
keyword: system.objectOfLead1, system.objectOfLead2
possible values: a file name of a saved cNanodcal object of the lead, or an input file name based on which the lead object can be calculated
default value: no default value, must be input
description: The calculation of a system with leads can be performed in two steps. The first step is to perform calculation for each lead which is considered equivalently as an infinite periodic system. In the second step, the physical properties (potential, density etc.) of the leads are used as boundary conditions applied to the central scattering region of the device. In this scenario, this input value is normally a filename of the calculated and saved results of the leads. This input can also be just another input file which initiates a complete calculation of the leads. Please note that all information about the leads are described indirectly by this input file. Please also note that if this input is another input file for a lead calculation, the current directory will be changed to that of the lead input file when performing the calculation for the lead.
an example:
system.objectOfLead1 = ../leftlead/NanodcalObject.mat
system.objectOfLead2 = ../rightlead/NanodcalObject.mat
system.numberOfGates
keyword: system.numberOfGates
possible values: an integer
default value: 0
description: the number of gates in the system. Gates are capacitively coupled to the device scattering region. They affect the device by providing effective boundary conditions to the electrostatic potential.
Note: if a gate is applied, the opposite side must be applied with a lead or another gate.
an example:
system.numberOfGates = 0
system.typeOfGate1, system.typeOfGate2
keyword: system.typeOfGate1, system.typeOfGate2
possible values: ‘top’, ‘bottom’, ‘front’, ‘back’, ‘left’, and ‘right’
default value: no default value, must be specified
description: the value must be given for each of the gates in the system. It describes the relative position of the gate to the central scattering region. More precisely, ‘left’ means the direction of [ 0 0 -1] ‘right’ means the direction of [ 0 0 1] ‘top’ means the direction of [ 0 1 0] ‘bottom’ means the direction of [ 0 -1 0] ‘front’ means the direction of [-1 0 0] ‘back’ means the direction of [ 1 0 0]
an example:
system.typeOfGate1 = 'top'
system.typeOfGate2 = 'bottom'
system.voltageOfGate1, system.voltageOfGate2
keyword: system.voltageOfGate1, system.voltageOfGate2
possible values: a double matrix, or a file name with an extension of .txt or .mat
default value: 0
description: this parameter supplys information about the distribution of the gate voltage values on the gate area located at the boundary of the system. The distribution of the gate voltage values may be given directly as an m by n double matrix, or given in a text file where are the m x n gate voltage values listed in m rows and n columns, or given in a matlab file in which is saved the variable Vg of the m by n double matrix.
The gate voltage values are in the unit of Volt.
Note 1: When the dimension of the input is m by n, the gate area is divided into m*n small regions, and each of the m*n input values are assigned to the corresponding small region. More specifically, for a ‘left’ or ‘right’ gate, the gate area, being defined by centralCellVector1 and centralCellVector2, will be equally divided into m portions along centralCellVector1 and n portions along centralCellVector2. There will be in total m*n small areas. The m*n input values are then assigned to the corresponding m*n small areas. For a ‘top’ or ‘bottom’ gate, the gate area will be equally divided into m portions along centralCellVector3 and n portions along centralCellVector1. For a ‘front’ or ‘back’ gate, the gate area will be equally divided into m portions along centralCellVector2 and n portions along centralCellVector3.
Note 2: the corresponding energy shift is -eVg.
Note 3: see the description of the parameter system.objectOfNoGate for more information.
an example:
system.voltageOfGate1 = -3
system.voltageOfGate2 = 0
system.objectOfNoGate
keyword: system.objectOfNoGate
possible values: a file name of a saved cNanodcal object
default value: []
description: The gate effect is simulated in nanodcal by setting a proper gate-induced boundary value to the Hartree potential when solving the Poisson equation. Nanodcal will set the boundary value under a gate as a superposition of the gate voltage defined through the parameter system.voltageOfGate and the corresponding boundary value taken from the calculation for the corresponding system without any gates. This parameter gives the file name of the calculated object for the corresponding system without any gates.
If it is empty, nanodcal will set the boundary value under a gate directly as the gate voltage defined through the parameter system.voltageOfGate.
an example:
system.objectOfNoGate = '../0Vg/NanodcalObject.mat'
system.hamiltonian
keyword: system.hamiltonian
possible values: a file name of an user provided hamiltonian matrix
default value: \([\ ]\) (empty)
description: If it is not empty, the system is defined by the input Hamiltonian matrix. In this case, all other parameters related to the system in the input file will not be used. In addition, since the real space wavefunction basis have not been given explicitly, any calculation related to real space wavefunction can not be performed.
The input file can be either a mat-file or xml-file, or text file, but must be in the same format as nanodcal output file Hamiltonian.mat or Hamiltonian.xml, or Hamiltonian.txt.
an example:
system.hamiltonian = :math:`[\ ]`
system.atomPositionShift
keyword: system.atomPositionShift
possible values: a 3\(\times\)1 double matrix
default value: [0 0 0]
description: In nanodcal calculations, we suggest that users put all the atoms inside the central cell box. This parameter helps to shift all the coordinates which are defined in the system.atomFile or system.atomBlock, by a constant vector. In other words, the real coordinates of atoms used by nanodcal will be the original ones plus this input parameter.
an example:
system.atomPositionShift = [9 8 7]
system.atomFractionalCoordinateBaseVectors
keyword: system.atomFractionalCoordinateBaseVectors
possible values: 3\(\times\)3 or 1\(\times\)6 or 1\(\times\)3 double matrix
default value: system.centralCellVectors
description: When system.atomCoordinateFormat is fractional, this parameter gives the three base vectors with which the fractional coordinates are defined. When the parameter is a 3\(\times\)3 double matrix, its each column forms one of the three basis vectors. When this parameter is a 1\(\times\)6 double matrix, it defines the three basis vectors by giving their lengths, a, b, and c, and the angles between them, alpha, beta, and gamma, with the convention that the a-axis is collinear with the x-axis, and the b-axis lies in the xy-plane. When the parameter is a 1\(\times\)3 double matrix, the alpha, beta, and gamma are all assumed to be \(\pi\)/2.
The default unit of angle is degree.
an example:
system.atomFractionalCoordinateBaseVectors = ...
[[1.3 0 0] [0 1.6 0] [0 0 2.5]]
system.atomPositionPrecision
keyword: system.atomPositionPrecision
possible values: a small number
default value: 1e-3 Bohr
description: Used as a criterion in symmetry analysis. If the distance of two atoms or their images is less than this parameter, the atoms are considered to occupy the same site.
an example:
system.atomPositionPrecision = 1e-6
system.numberOfElectrons
keyword: system.numberOfElectrons
possible values: a double value
default value: calculated automatically by nanodcal
description: the number of electrons in (the central cell of) the system. This value will be generated automatically by nanodcal and normally, there is no need for an user to input it. However, this input offers the opportunity to calculate a charged system.
an example:
system.numberOfElectrons = 88