Useful Tips

After NanoDCAL is installed successfully, you have several ways to obtain useful information about how to run and where to find commands. In particular, the Input reference section lists all the possible input controls; the Theory section presents the theoretical formulation inside nanodcal. In this Section, we discuss the nanodcal on-line help tips.

Within the command window of Matlab, type:


you will see one and half pages of help information in the Matlab command window and they are organized with subtitles “Basic Usage” and “More Usage Information”. In the Basic Usage, there are several commands that allow you to obtain the most important information concerning NanoDCAL, as well as how to initiate a NanoDCAL run. By typing:

nanodcal -parameter

You will receive the entire list of input parameter categories of NanoDCAL. Clicking the hyperlinks in the list, you can quickly find all the input, run time control and other necessary parameters for running NanoDCAL. Next, by typing:

nanodcal -basis

A periodic table appears. Clicking an atomic symbol, you will see further information about the LCAO basis, pseudopotential, and what tests have been done on this atom. More discussions on LCAO basis functions can be found below. By typing:

nanodcal filename

you will start a NanoDCAL run using the input file filename. How to prepare an input file will be discussed throughout this manual, or you can find it in the input parameter category “More Usage Information” by clicking the nanodcal -help startmodes hyperlink.

In the More Usage Information, there are several hyperlinks whose meaning are self-explanatory. Please click them to read the short descriptions. Typically, desired information can be found by just a couple of clicks.

Inputs to NanoDCAL

NanoDCAL needs three inputs to run:

  • LCAO basis set and pseudopotentials;

  • atomic positions of the nanostructure;

  • control parameters for the calculation.

LCAO basis set and pseudopotentials

As the first input, one needs to specify what atoms are there. An atom in NanoDCAL is characterized by atomic orbital of valence electrons (s, p, d, f) and by pseudopotentials that define the atomic core. DFT implementation in NanoDCAL uses a linear combination of atomic orbital (LCAO) basis to expand all the physical operators. The reason for using LCAO is due the need for constructing NEGF. Plane waves provide a complete basis set and are commonly used in solid state DFT implementations, but plane waves produce very large and dense matrices preventing efficient calculations of NEGF. For transport calculations, LCAO basis set provides a reasonable compromise between computation and accuracy. Nanoacademic has prepared tested LCAO basis functions and pseudopotentials for most atoms in the periodic table. This database was constructed by using the Nanoacademic atomic package nanobase [NABASE].

After NanoDCAL is installed (see Installation), you can find the atomic database in the /neutralatomdatabase directory. The atomic data are in files having names like Au_DZP.nad. Even though the file extension is ‘nad’ (for neutral atom data), these are MAT-files and can be loaded into Matlab for inspection. In the command window of Matlab, type:

Au = load(‘Au_DZP.nad’,‘-mat’)

An equivalent way to load and look at this data is:

load -mat C_DZP.nad

You can find the details for the basis function Au_DZP.nad. A lot of information are contained in, and you can follow the above commands to inspect them.

To use the atomic database, please type:

nanodcal -basis

A periodic table shows up and you can click the atomic symbols to find out what LCAO basis functions are available and what tests have been done. For example, by clicking “O” for oxygen, you get the following four lines:


This means there are four slightly different basis functions for oxygen, all are double-zeta-polarized (DZP). The first three were generated using LDA. The first basis set is tested using solid state environment MgO crystal lattice; the second using ZnO crystal lattice; the third tested using a molecular set; and the fourth is prepared by PBE exchange-correlation potential and tested on a molecular set. Of course, all these atomic data have been used in many other systems for research problems and they do not differ that much. But careful testing using some typical examples is still important. By clicking “brief”, “short” or “full” descriptions, you can find increasingly more details of the basis function and pseudopotential. Much of the displayed information is self-explanatory, but some information requires a degree of understanding on the pseudopotential and basis function generation procedure by the nanobase atomic package [NABASE].


By clicking copy or NAD, the particular basis function is copied to the current or the /neutralatomdata subdirectory for use, respectively. Note it is important to click copy or NAD, otherwise the needed basis functions will not be there for your calculation. The reason users are required to do this step is to ensure that it is the users who decide the most suitable basis functions according to the chemical environment of their research problem. After copy or NAD is clicked, you will find a file named O_DZP.mat in your subdirectory.

The basis function and pseudopotential database were obtained by solving the relativistic Dirac equation for single neutral atoms [NABASE]. It is extremely important to realize that any LCAO implementation uses a finite basis set and careful checks of basis functions must be done to ensure accuracy. You can find what tests have been done by reading the summary.pdf mentioned above. The default basis used by NanoDCAL is double-zeta polarized (DZP) orbital. Nanoacademic has also prepared other kinds of orbital for some atoms. These include single-zeta (SZ, SZP), double-zeta (DZ), etc.

If the tests performed by us already cover your needs, please move on. On the other hand, if you need to generate basis functions and pseudopotentials according to the chemical environment of your specific problem, please use nanobase. We emphasize that it is the user’s responsibility to make sure that basis set and pseudopotentials are appropriate for their specific application.

Atomic positions of device structure

As the second input to NanoDCAL, one needs to specify atomic positions of the device structure. For two-probe device structures, you should have two leads sandwiching a device scattering region. The scattering region also contains several layers of lead atoms to screen interactions, see Refs. [TGW01, WHL06] and Theory section of nanodcal for a detailed discussion on this point.

You can prepare the atomic position input file in the format provided in the /examples directory and discussed in Section Basic input file. There are several tools to easily build device structures, like the Atomic Simulation Environment. After atomic position files for scattering region as well as leads are prepared, in principle one should relax the scattering region structure by total energy minimization. The device electrodes take perfect bulk atomic structure, one may or may not need to relax them. NanoDCAL provides a total energy structural optimization tool. We also suggest that you obtain one of the many existing total energy software for such optimizations.

Control parameters

As the third input to NanoDCAL, one needs to specify what is to be calculated, how the calculation should proceed, what exchange-correlation functional to use, what quantity to mix in the self-consistent iteration, etc. This is the control and it involves all the capabilities of NanoDCAL. By issuing the command:

nanodcal -parameter

the entire list of input parameter categories are shown. You can click and follow the links to find details of all the input parameters. Please make a quick glance to them but their use can only become familiar after some practice. Again, the Input reference section lists all the parameters.

Most of the control parameters have a default value. For typical research projects, you actually do not need to alter the defaults. If a particular control parameter does not appear in the various *.input files, nanodcal uses its default value. If this default makes no sense in conjunction with other control parameters, a warning/error message will appear on the computer screen. You need to fix the problem before moving on.


There are a number of very important parameters which do not have defaults such as that describing the length of the scattering region of the device. It is the users’ responsibility to set correct values for them. Please refer to the Input reference section for all possible parameters.

The easiest way to learn commonly needed control parameters is to look at the example input files in the /examples directory. There are many subdirectories there and each contains a number of examples. Using these examples, one should be able to quickly learn how to set up new research projects. In each example, please start with the input file named scf.input that contains input parameters to run the self-consistent procedure. There may be other *.input files, for instance band.input for computing band structure; transmission.input for computing transmission coefficients; scatteringstates.input for computing scattering states, etc.. But scf.input must be run first to obtain the self-consistent Hamiltonian and density matrix before others can be run. Use the edit command in Matlab to open these input files, you will find that most input parameters are self-explanatory. With these input files open, you can come back to this manual for explanations.

In any *.input file, a parameter is given by a line in the following format:

keyWord = keyValue

where keyWord is the name of the control parameter; and keyValue is the value of this parameter. This format follows the style of Matlab. For instance, the following lines of keywords indicate that the calculation does not involve any spin, the voltages to be applied to the first and second lead are zero and 1 volt, respectively:

system.spinType = ‘NoSpin’

system.voltageOfLead1 = 0

system.voltageOfLead2 = 1

Default units

Users can specify units in various *.input files using keyWord such as:

calculation.control.lengthUnit = 1.0 ‘au’
calculation.control.energyUnit = 1.0 ‘au’

If not specified, NanoDCAL uses a default unit. Table 1 summarizes the units.

Table 1 Default and allowed units in nanodcal. Default units are automatically used if key- Word associated with units is not specified in the scf.input. (1au length = 0.529 angstroms; 1au energy = 27.2 eV).

Default unit

Other allowed units



system.energyUnit = 1.0 au






system.lengthUnit = 1.0 au




The example directory

There is an /examples directory in NanoDCAL which contains about 80 examples showing how to use various capabilities of the software. It is strongly suggested that one begins by running at least some of them. The examples are organized into groups each corresponds to one type of system (except the Group10, see Section Two Probe Devices). These examples can be also grouped according to the used functionality of NanoDCAL, as specified in the README file of the /examples directory.

Each group of examples also contain its own README file providing further information. In the README files, if one uses the mouse or the “shift+arrow” keys to mark a string, e.g. nanodcal -help, and then press the F9 key, the Matlab will automatically perform the marked string as if that string has been typed in the command window.

Table 2 shows the examples according to the functionality. Table 3 shows the usage for cNA_LCAO public function. These public functions are useful for monitoring calculated data and post analysis.

Table 2 Examples for various computation in the /examples directory of nanodcal. The first number in the labelling is the group number, the second number is the example number inside that group, namely, example 4.13 means the 13th example inside group 4.


Example #

Harris field (non-self-consistent)


SCF calculation

1.1, 1.10, 1.12, 2.1, 3.1, 4.1

post-SCF calculation


total energy calculation

1.7, 2.9, 3.5, 4.7

band structure calculation

1.2, 2.2, 2.3, 2.4, 5.1, 6.1, 9.2, 9.4

complex-band structure

2.5, 6.2

scattering states calculation

3.7, 3.8, 3.9, 4.8,

4.9, 4.10, 7.3, 7.4, 8.3, 8.4

density of states analysis

1.4, 2.7, 3.3, 4.3, 5.3, 6.4, 7.2, 8.2

electronic charge analysis

1.3, 2.6, 3.2, 4.2, 5.2, 6.3, 7.1, 8.1

potential and voltage drop

1.5, 1.6, 2.8, 3.4, 4.4, 4.5, 4.6

transmission calculation

4.11, 8.5

transmission channel analysis

2.10, 3.6

conductance calculation

4.12, 8.6

current-voltage curve

4.13, 4.14

basis optimization or

9.1, 9.3

calculation with variable basis

Table 3 Examples for cNA_LCAO public function usage.

cNA_LCAO public function \(\ \ \ \ \ \ \ \ \ \ \ \)

Example #





show public data


Interaction with the outside world

NanoDCAL is a flexible tool for modeling materials and electronics. As you will see in the following chapters, in addition to the powerful functionality already implemented inside, NanoDCAL also interacts with the outside world by several ways.

  • Plug-in calculators. In nanodcal, important computation methods can be provided by users through the plug-in calculators. Important data structures associated with the calculators can also be modified externally. Simply setting some parameters in the input file without any modification of nanodcal itself, users can apply their own calculators or modify data during the self consistent procedure. Interacting with nanodcal this way allows users to expand the computational methods beyond those of nanodcal.

  • system.hamiltonian. In nanodcal, Hamiltonian data of the system can be provided by users through the input parameter system.hamiltonian. Nanodcal calculates the Hamiltonian data of physical systems by DFT, NEGF-DFT or other methods. For users already having their own data and just wish to analyze physical properties, they can apply system.hamiltonian functionality to achieve the goal. For example, one may already have a tight binding Hamiltonian and nanodcal can simply use it to calculate transport properties. More information will be provided in Section User Defined Hamiltonian.

  • calculation.SCF.donatorObject. In nanodcal, the initial data for self-consistent calculation can be provided by users through the donatorObject which can be a saved cNA_LCAO object, a Hamiltonian structure, a density matrix structure, or a real space charge density structure. A good initial data can be helpful for achieving faster convergence in SCF runs. More information is discussed in Section Basic standard output and in the Input reference.

  • Basis optimization. Nanodcal interacts with the atomic package nanobase to optimize LCAO basis functions. Since one cannot use infinite number of atomic orbital as basis set, optimization of LCAO function becomes important for obtaining accurate results. Some discussions about basis functions are found in section LCAO basis set and pseudopotentials above and various part of this manual. A combined application of both packages is necessary to achieve basis optimization. More information can be found in Section Basis Optimization.

  • The nanodcal function. Nanodcal can be called from within other software in several ways. (i) Calling nanodcal from another software to obtain an output object of cNA_LCAO class and use it outside nanodcal. (ii) Calling nanodcal from another software to use the methods of nanodcal to deal with an existing cNA_LCAO object. (iii) Calling nanodcal from another software to perform calculations based on data obtained outside nanodcal. Using nanodcal as a plug-in to a third party software is achieved by:

    [objectoutput =] nanodcal(inputfilename)

    where inputfilename is the name of an input file in which input parameters for calculations are defined; the objectoutput is an object of class cNA_LCAO.

[NABASE] (1,2,3)

Nanobase is an atomic package of Nanoacademic Technologies. It can be obtained from Nanobase solves single relativistic all electron atom to generate norm conserving non-local pseudopotential and the corresponding pseudo-atomic orbital (PAO); it then confines the PAOs for application in the nanodcal quantum transport package. Nanobase is developed in Matlab with a small part in C. The PAO functions serve as the linear combination of atomic orbital (LCAO) basis set for expanding wave functions and other physical operators in the density functional theory (DFT) calculation.


Taylor, J., Guo, H., & Wang, J. (2001). Ab initio modeling of quantum transport properties of molecular electronic devices. Physical Review B, 63(24), 245407.


Waldron, D., Timoshevskii, V., Hu, Y., Xia, K., & Guo, H. (2006). First Principles Modeling of Tunnel Magnetoresistance of Fe/MgO/Fe trilayers. Physical Review Letters, 97(22), 226802.