# 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
```