Difference between revisions of "Tutorial-v.1.0.0"

From salmon
Jump to: navigation, search
(Additional options in configure.py script)
(Input files)
 
(38 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Prerequisites ==
+
== Getting started ==
 +
Welcome to SALMON Tutorial!
  
In this guide, it is assumed that readers have a basic knowledge of Unix and its command line operations.  
+
In this tutorial, we explain the use of SALMON from the very beginning, taking a few samples that cover applications of SALMON in several directions.  
For the installation of SALMON, following packages are required.
+
We assume that you are in the computational environment of UNIX/Linux OS.
 +
First you need to download and install SALMON in your computational environment.
 +
If you have not yet done it, do it following the instruction, [[download-v.1.0.0]] and [[Install and Run-v.1.0.0]].
  
* Fortran90/C compiler. Our package assumes users have one of the following compilers:
+
As described in [[Install and Run-v.1.0.0]], you are required to prepare at least an input file and pseudopotential files to run SALMON.
** GCC (Gnu Compiler Collection)
+
In the following, we present input files for several sample calculations and provide a brief explanation of the namelist variables that appear in the input files.
** Intel Fortran/C Compiler
+
You may modify the input files to execute for your own calculations.
** Fujitsu Compiler (at FX100 / K-Computer)
+
Pseudopotential files of elements that appear in the samples are also attached.
 +
We also present explanations of main output files.
  
* One of the following library packages for linear algebra:
+
We present 6 tutorials.
** BLAS/LAPACK
 
** Intel Math Kernel Library (MKL)
 
** Fujitsu Scientific Subroutine Library 2 (SSL-II)
 
  
* Build tools.
+
First 3 tutorials (Tutorial-1 ~ 3) are for an isolated molecule, acetylene C2H2.  
** CMake
+
If you are interested in learning electron dynamics calculations in isolated systems, please look into these tutorials.
 +
In SALMON, we usually calculate the ground state solution first.
 +
This is illustrated in [[#Tutorial-1: Ground state of C2H2 molecule|Tutorial-1]].
 +
After finishing the ground state calculation, two tutorials of electron dynamics calculations are prepared.
 +
[[#Tutorial-2: Polarizability and photoabsorption of C2H2 molecule|Tutorial-2]]
 +
illustrates the calculation of linear optical responses in real time, obtaining polarizability and photoabsorption of the molecule.
 +
[[#Tutorial-3: Electron dynamics in C2H2 molecule under a pulsed electric field|Tutorial-3]]
 +
illustrates the calculation of electron dynamics in the molecule under a pulsed electric field.
  
If you use other compilers, you may need to change build scripts (CMake). See [[Tutorial-v.1.0.0#Additional options in configure.py script]]
+
Next 2 tutorials (Tutorial-4 ~ 5) are for a crystalline solid, silicon.
If no numerical library is installed on your computer system, you may need to install BLAS/LAPACK by yourself. See Tips for Installation.
+
If you are interested in learning electron dynamics calculations in extended periodic systems, please look into these tutorials.
See [[Troubleshooting of the Installation Process]].
+
Since ground state calculations of small unit-cell systems are not computationally expensive
 +
and a time evolution calculation is usually much more time-consuming than the ground state calculation,
 +
we recommend to run the ground and the time evolution calculations as a single job.
 +
The following two tutorials are organized in that way.
 +
[[#Tutorial-4: Dielectric function of crystalline silicon|Tutorial-4]]
 +
illustrates the calculation of linear response properties of crystalline silicon to obtain the dielectric function.
 +
[[#Tutorial-5: Electron dynamics in crystalline silicon under a pulsed electric field|Tutorial-5]]
 +
illustrates the calculation of electron dynamics in the crystalline silicon induced by a pulsed electric field.
  
If there are any problem to use CMake tool in your environment by you can use the GNU make tools.
+
The final tutorial (Tutorial-6) is for an irradiation and a propagation of a pulsed light in a bulk silicon,
See [[Troubleshooting of the Installation Process]].
+
coupling Maxwell equations for the electromagnetic fields of the pulsed light and the electron dynamics in the unit cells.
 +
This calculation is quite time-consuming and is recommended to execute using massively parallel supercomputers.
 +
[[#Tutorial-6: Pulsed-light propagation through a silicon thin film|Tutorial-6]]
 +
illustrates the calculation of a pulsed, linearly polarized light irradiating normally on a surface of a bulk silicon.
  
== Download ==
+
== C2H2 (isolated molecules) ==
  
The newest version of the SALMON can be downloaded from [[Download]].
+
=== Tutorial-1: Ground state of C2H2 molecule ===
To extract files from the downloaded file ''salmon-<VERSION>.tar.gz'', type the following command in the command-line,
+
In this tutorial, we learn the calculation of the ground state solution of acetylene (C2H2) molecule, solving the static Kohn-Sham equation.
 +
This tutorial will be useful to learn how to set up calculations in SALMON for any isolated systems such as molecules and nanoparticles.
 +
It should be noted that at present it is not possible to carry out the geometry optimization in SALMON.
 +
Therefore, atomic positions of the molecule are specified in the input file and are fixed during the calculations.
  
$ tar –zxvf ./salmon-<VERSION>.tar.gz
+
==== Input files ====
 +
: To run the code, following files are used:
  
After the extraction, the following directories will be created.
+
{| class="wikitable"
 +
| file name      || description
 +
|-
 +
| ''C2H2_gs.inp'' || input file that contains namelist variables and their values         
 +
|-
 +
| ''C_rps.dat'' || pseodupotential file for carbon atom
 +
|-
 +
| ''H_rps.dat'' || pseudopotential file for hydrogen atom
 +
|}
  
SALMON
+
* You may download the above 3 files (zipped file) from:
  |- src        Source codes
 
  |- example    Samples
 
  |- makefiles  GNU Makefiles for building
 
  |- cmakefiles  CMake related files
 
  |- makefiles  GNU Makefiles for building
 
  
== Build ==
+
[[media:C2H2_gs_input.zip| Download zipped input and pseudopotential files]]
  
To compile SALMON to create executable binary files, two options are prepared, CMake and Gnu Make.  
+
* In the input file ''C2H2_gs.inp'', namelists variables are specified. Most of them are mandatory to execute the ground state calculation. We present their explanations below:
If CMake works in your environment, we recommend to use it.
 
If CMake fails in your environment, consider using Gnu Make [[Install_and_Run-v.1.0.0#Build_with_GNU_Makefile]].
 
  
=== Installation of CMake  ===
+
[[Explanations of input files (ground state of C2H2 molecule)-v.1.0.0]]
  
The [https://cmake.org/|CMake CMake] is a cross-platform build tool.
+
: This will help you to prepare an input file for other systems that you want to calculate. A complete list of the namelist variables that can be used in the input file can be found in the downloaded file ''SALMON/manual/input_variables.md''.
In order to build the SALMON from the source code, the CMake of version 3.0.2 or later is required on your system.  
 
  
You can get the binary distribution from the [https://cmake.org/download/  download page].
+
==== Output files ====
First, move to the installation directory of salmon,
+
: After the calculation, following output files are created in the directory that you run the code,
<pre>
 
cd <SALMON_INSTALLATION_DIRECTORY>
 
</pre>
 
and download the binary distribution ( <code>cmake-<VERSION>-<PLATFORM>.tar.gz</code>) appropriate for your platform.
 
You can do it by copy the URL of download link from the browser, and use <code>wget</code> command:
 
<pre>
 
wget https://cmake.org/files/v3.8/cmake-3.8.2-Linux-x86_64.tar.gz
 
</pre>
 
In this document, we will use version 3.8.2 as an example. You can unpack the archive
 
<pre>
 
tar -zxvf cmake-3.8.2-Linux-x86_64.tar.gz
 
</pre>
 
and you will have the binary <code>make-3.8.2-Linux-x86_64/bin/cmake</code>. 
 
To utilize the <code>cmake</code> command, the executable are settled inside the directory specified in your <code>$PATH</code>.
 
  
If you use the bash shell, you edit <code>~/.bashrc</code> and append the line:
+
{| class="wikitable"
<pre>
+
| file name      || description
export PATH=<SALMON_INSTALLATION_DIRECTORY>/cmake-3.8.2-Linux-x86_64/bin:$PATH
+
|-
</pre>
+
| ''C2H2_info.data'' || information on ground state solution             
, and reload the configuration <code>source ~/.bashrc</code>.
+
|-
 +
| ''dns.cube'' || a cube file for electron density
 +
|-
 +
| ''elf.cube'' || electron localization function (ELF)
 +
|-
 +
| ''psi1.cube'', ''psi2.cube'', ... || electron orbitals
 +
|-
 +
| ''dos.data'' || density of states
 +
|-
 +
| ''pdos1.data'', ''pdos2.data'', ... || projected density of states
 +
|-
 +
| ''C2H2_gs.bin'' || binary output file to be used in the real-time calculation
 +
|}
  
=== Build using CMake ===
+
* You may download the above files (zipped file, except for the binary file ''C2H2_gs.bin'') from:
  
First, examine whether CMake is usable in your environment or not.
+
[[media:C2H2_gs_output.zip|Download zipped output files]]
Type the following in Unix command-line:
 
  
$ cmake --version
+
* Main results of the calculation such as orbital energies are included in ''C2H2_info.data''. Explanations of the ''C2H2_info.data'' and other output files are described in:
  
If CMake is not installed in your system, an error message such as <code>cmake: command not found</code> will appear.  
+
[[Explanations of output files (ground state of C2H2 molecule)-v.1.0.0]]
If CMake is installed on your system, the version number will be shown.
 
To build SALMON, CMake of version 3.0.2 or later is required.
 
If CMake is not installed or CMake of the older version is installed in your system, you need to install the new version by yourself.
 
  
The installation of the CMake is simple.
+
==== Images ====
A detailed description of the installation is given in [[Tips_for_Installation#Installation_of_CMake | Installation of CMake]].
+
: We show several image that are created from the output files.
Here we describe a simple method to use the binary distribution of CMake.
 
First, download the '''binary distribution file''' appropriate for your system from https://cmake.org/download/.
 
The filename of the downloaded file will be ''cmake-<VERSION_PLATFORM>.tar.gz''.
 
In standard Unix environment, files for the platform of Linux x86_64 will be appropriate.
 
Next extract the binary executable file of CMake, typing in the command-line as
 
  
  $ tar xvfz cmake-<VERSION_PLATFORM>.tar.gz
+
{| class="wikitable"
 +
| image || files used to create the image
 +
|-
 +
| [[:File:HOMO.png#file|highest occupied molecular orbital (HOMO)]] || ''psi1.cube'', ''psi2.cube'', ...           
 +
|-
 +
| [[:File:Dns.png#file|electron density]] || ''dns.cube''
 +
|-
 +
| [[:File:Elf.png#file|electron localization function]] ||  ''elf.cube''
 +
|}
  
Then you will have the cmake binary file in ''bin'' directory.
+
=== Tutorial-2: Polarizability and photoabsorption of C2H2 molecule ===
For the CMake binary file to be usable, you need to modify the Unix environmental variable ''$PATH'' appropriately.
+
In this tutorial, we learn the linear response calculation in the acetylene (C2H2) molecule, solving the time-dependent Kohn-Sham equation.
 +
The linear response calculation provides the polarizability and the oscillator strength distribution of the molecule.
 +
This tutorial should be carried out after finishing the ground state calculation that was explained in [[#Tutorial-1: Ground state of C2H2 molecule|Tutorial-1]].
 +
In the calculation, an impulsive perturbation is applied to all electrons in the C2H2 molecule along the molecular axis which we take ''z'' axis.
 +
Then a time evolution calculation is carried out without any external fields.
 +
During the calculation, the electric dipole moment is monitored.
 +
After the time evolution calculation, a time-frequency Fourier transformation is carried out for the electric dipole moment to obtain the frequency-dependent polarizability.
 +
The imaginary part of the frequency-dependent polarizability is proportional to the oscillator strength distribution and the photoabsorption cross section.  
  
'''''Description how to modify the $PATH should come here'''''
+
==== Input files ====
 +
: To run the code, the input file ''C2H2_rt_response.inp'' that contains namelist variables and their values for the linear response calculation is required. The binary file ''C2H2_gs.bin'' that is created in the ground state calculation and pseudopotential files are also required. The pseudopotential files should be the same as those used in the ground state calculation.
  
To confirm that CMake of the new version is usable in your environment, type <code>cmake --version</code> in the command-line.
+
{| class="wikitable"
 +
| file name      || description
 +
|-
 +
| ''C2H2_rt_response.inp'' || input file that contains namelist variables and their values         
 +
|-
 +
| ''C_rps.dat'' || pseodupotential file for carbon
 +
|-
 +
| ''H_rps.dat'' || pseudopotential file for hydrogen
 +
|-
 +
| ''C2H2_gs.bin'' || binary file created in the ground state calculation
 +
|}
  
==== Build using CMake specifying archtechture ====
+
* You may download the ''C2H2_rt_response.inp'' file (zipped file) from:
  
Confirming that CMake of version 3.0.2 or later can be usable on your system, proceed the following steps.
+
[[media:C2H2_rt_response_input.zip| Download zipped input file]]
We assume that you are in the directory SALMON.
 
* Create a new temporary directory ''build'' and move to the directory,
 
  
$ mkdir build
+
* In the input file ''C2H2_rt_response.inp'', namelists variables are specified. Most of them are mandatory to execute the linear response calculation. We present their explanations below:
$ cd build
 
  
* Execute the python script ''configure.py'' and then make,
+
[[Explanations of input files (polarizability and photoabsorption of C2H2 molecule)-v.1.0.0]]
 +
 +
: This will help you to prepare the input file for other systems that you want to calculate. A complete list of the namelist variables that can be used in the input file can be found in the downloaded file ''SALMON/manual/input_variables.md''.
  
$ python ../configure.py –arch=ARCHTECTURE
+
==== Output files ====
$ make
+
: After the calculation, following output files are created in the directory that you run the code,
  
Here ''ARCHITECTURE'' specifies the architecture of the CPU in your computer system such as ''intel-avx''.  
+
{| class="wikitable"
You need to choose ''ARCHTECUTRE'' from the following options:
+
| file name      || description
 +
|-
 +
| ''C2H2_lr.data'' || polarizability and oscillator strength distribution as functions of energy           
 +
|-
 +
| ''C2H2_p.data'' || components of dipole moment as functions of time
 +
|}
 +
 
 +
* You may download the above files (zipped file) from:
 +
 
 +
[[media:C2H2_rt_response_output.zip|Download zipped output files]]
 +
 
 +
*Explanations of the output files are given in:
 +
 
 +
[[Explanations of output files (polarizability and photoabsorption of C2H2 molecule)-v.1.0.0]]
 +
 
 +
=== Tutorial-3: Electron dynamics in C2H2 molecule under a pulsed electric field ===
 +
In this tutorial, we learn the calculation of the electron dynamics in the acetylene (C2H2) molecule under a pulsed electric field, solving the time-dependent Kohn-Sham equation.
 +
As outputs of the calculation, such quantities as the total energy and the electric dipole moment of the system as functions of time are calculated.
 +
This tutorial should be carried out after finishing the ground state calculation that was explained in [[#Tutorial-1: Ground state of C2H2 molecule|Tutorial-1]].
 +
In the calculation, a pulsed electric field that has cos^2 envelope shape is applied. The parameters that characterize the pulsed field such as magnitude, frequency, polarization direction, and carrier envelope phase are specified in the input file.
 +
 
 +
==== Input files ====
 +
: To run the code, following files are used. The ''C2H2.data'' file is created in the ground state calculation. Pseudopotential files are already used in the ground state calculation. Therefore, ''C2H2_rt_pulse.inp'' that specifies namelist variables and their values for the pulsed electric field calculation is the only file that the users need to prepare.
  
 
{| class="wikitable"
 
{| class="wikitable"
| arch       || Detail                          || Compiler        || Numerical Library
+
| file name       || description
 
|-
 
|-
| intel-knl || Intel Knights Landing || Intel Compiler || Intel MKL             
+
| ''C2H2_rt_pulse.inp'' || input file that contain namelist variables and their values.         
 
|-
 
|-
| intel-knc || Intel Knights Corner  || Intel Compiler || Intel MKL             
+
| ''C_rps.dat'' || pseodupotential file for Carbon
 
|-
 
|-
| intel-avx || Intel Processer (Ivy-, Sandy-Bridge)  || Intel Compiler || Intel MKL
+
| ''H_rps.dat'' || pseudopotential file for Hydrogen
 
|-
 
|-
| intel-avx2 || Intel Processer (Haswell, Broadwell ..) || Intel Compiler || Intel MKL
+
| ''C2H2.data'' || binary file created in the ground state calculation
 +
|}
 +
 
 +
* You may download the ''C2H2_rt_pulse.inp'' file (zipped file) from:
 +
 
 +
[[media:C2H2_rt_pulse_input.zip| Download zipped input file]]
 +
 
 +
* In the input file ''C2H2_rt_pulse.inp'', namelists variables are specified. Most of them are mandatory to execute the calculation of electron dynamics induced by a pulsed electric field. We present explanations of the namelist variables that appear in the input file in:
 +
 
 +
[[Explanations of input files (C2H2 molecule under a pulsed electric field)-v.1.0.0]]
 +
 +
: This will help you to prepare the input file for other systems and other pulsed electric fields that you want to calculate. A complete list of the namelist variables that can be used in the input file can be found in the downloaded file ''SALMON/manual/input_variables.md''.
 +
 
 +
==== Output files ====
 +
: After the calculation, following output files are created in the directory that you run the code,
 +
 
 +
{| class="wikitable"
 +
| file name      || description
 
|-
 
|-
| fujitsu-fx100 || FX100 Supercomputer || Fujitsu Compiler || SSL-II
+
| ''C2H2_p.data'' || components of the electric dipole moment as functions of time           
 
|-
 
|-
| fujitsu-k || Fujitsu FX100 / K-computer || Fujitsu Compiler || SSL-II
+
| ''C2H2_ps.data'' || power spectrum that is obtained by a time-frequency Fourier transformation of the electric dipole moment
 
|}
 
|}
  
If the build is successful, you will get a file ''salmon.cpu'' at the directory ''salmon/bin''.
+
* You may download the above files (zipped file) from:
If you specify many-core archtechtures, ''intel-knl'' or ''intel-knc'', you find a file ''salmon.mic'' or both files ''salmon.cpu'' and ''salmon.mic''.
 
  
 +
[[media:C2H2_rt_pulse_output.zip|Download zipped output files]]
 +
 +
*Explanations of the files are described in:
 +
 +
[[Explanations of output files (C2H2 molecule under a pulsed electric field)-v.1.0.0]]
 +
 +
== Crystalline silicon (periodic solids) ==
 +
 +
=== Tutorial-4: Dielectric function of crystalline silicon===
 +
In this tutorial, we learn the linear response calculation of the crystalline silicon of a diamond structure.
 +
Calculation is done in a cubic unit cell that contains eight silicon atoms.
 +
Since the ground state calculation costs much less computational time than the time evolution calculation,
 +
both calculations are successively executed.
 +
After finishing the ground state calculation, an impulsive perturbation is applied to all electrons in the unit cell
 +
along ''z'' direction.
 +
Since the dielectric function is isotropic in the diamond structure, calculated dielectric function should not depend
 +
on the direction of the perturbation.
 +
During the time evolution, electric current averaged over the unit cell volume is calculated.
 +
A time-frequency Fourier transformation of the electric current gives us a frequency-dependent conductivity.
 +
The dielectric function may be obtained from the conductivity using a standard relation.
 +
 +
==== Input files ====
 +
: To run the code, following files are used:
 +
 +
{| class="wikitable"
 +
| file name      || description
 +
|-
 +
| ''Si_gs_rt_response.inp'' || input file that contain namelist variables and their values.         
 +
|-
 +
| ''Si_rps.dat'' || pseodupotential file of silicon
 +
|}
  
 +
* You may download the above 2 files (zipped file) from:
  
== Files necessary to run SALMON ==
+
[[media: Si_gs_rt_response_input.zip| Download zipped input and pseudopotential files]]
  
To run SALMON, at least two kinds of files are required for any calculations.
+
* In the input file ''Si_gs_rt_response.inp'', namelists variables are specified. Most of them are mandatory to execute the calculation. We present explanations of the namelist variables that appear in the input file in:
One is an input file, with the filename extension of ''*.inp*'', to be read from the standard input, ''stdin''.  
 
It should be prepared in the Fortran90 namelist format.
 
Pseudopotential files of relevant elements are also required.  
 
Depending on your purpose, some other files may also be necessary.
 
For example, coordinates of atomic positions of the target material may either be written in the input file or prepared as a separate file.
 
  
=== Pseudopotentials ===
+
[[Explanations of input files (dielectric function of crystalline silicon)-v.1.0.0]]
  
SALMON utilizes norm-conserving pseudpotentials.
+
You may find pseudopotentials of some elements in [[Samples]].  
+
: This will help you to prepare the input file for other systems that you want to calculate. A complete list of the namelist variables that can be used in the input file can be found in the downloaded file ''SALMON/manual/input_variables.md''.
SALMON allows using several formats of pseudopotentials that can be easily obtained from websites listed below.
 
  
 +
==== Output files ====
 +
: After the calculation, following output files are created in the directory that you run the code,
  
 
{| class="wikitable"
 
{| class="wikitable"
| pseudopotential || website
+
| file name      || description
 +
|-
 +
| ''Si_gs_info.data'' || information of ground state calculation
 +
|-
 +
| ''Si_eigen.data'' || energy eigenvalues of orbitals
 +
|-
 +
| ''Si_k.data'' || information on k-points
 
|-
 
|-
| Ab-init FHI || http://www.ab-init
+
| ''Si_rt.data'' || electric field, vector potential, and current as functions of time
 +
|-
 +
| ''Si_force.data'' || force acting on atoms
 +
|-
 +
| ''Si_lr.data'' || Fourier spectra of the dielectric functions
 +
|-
 +
| ''Si_gs_rt_response.out'' || standard output file
 
|}
 
|}
  
In the input file, you need to write the filename of the pseudopotential.
+
* You may download the above files (zipped file) from:
Use exactly the same filename as that downloaded from the website or that in the [[Samples]].
+
 
 +
[[media:Si_gs_rt_response_output.zip|Download zipped output files]]
 +
 
 +
* Explanations of the output files are described in:
  
=== input file ===
+
[[Explanation of output fiels (dielectric function of crystalline silicon)-v.1.0.0]]
  
SALMON describes electron dynamics in systems with both isolated and periodic boundary conditions.
+
=== Tutorial-5: Electron dynamics in crystalline silicon under a pulsed electric field ===
The boundary condition is specified by the variable ''iperiodic'' in the namelist ''&system''.
+
In this tutorial, we learn the calculation of electron dynamics in a unit cell of crystalline silicon of a diamond structure.
Calculations are achieved in two steps; first, the ground state calculation is carried out and then electron dynamics calculations in real time are achieved.  
+
Calculation is done in a cubic unit cell that contains eight silicon atoms.
Choice of the calculation mode is specified by the variable ''calc_mode'' in the namelist ''&calculation''.  
+
Since the ground state calculation costs much less computational time than the time evolution calculation,
For isolated systems, the ground state and the electron dynamics calculations should be carried out in two steps.
+
both calculations are successively executed.
First the ground state calculation is achieved specifying ''calc_mode = 'GS' ''.
+
After finishing the ground state calculation, a pulsed electric field that has cos^2 envelope shape is applied.
Then the real-time electron dynamics calculation is achieved specifying ''calc_mode = 'RT' ''.
+
The parameters that characterize the pulsed field such as magnitude, frequency, polarization, and carrier envelope phase
For periodic systems, two calculations can also be carried out in one step specifying ''calc_mode = 'GS_RT' ''.
+
are specified in the input file.
For the isolated systems, ’GS-RT’ is not implemented. However, their calculations are done at once if
 
users prepare appropriate shell scripts.
 
  
There are about 20 groups of main namelists listed below.
+
==== Input files ====
A list of variables in each namelist is provided in the file ''???'' included in the source-file distribution.
+
: To run the code, following files are used:
  
 
{| class="wikitable"
 
{| class="wikitable"
| name of namelist || description  
+
| file name       || description
 
|-
 
|-
| &calculation || specify calculation modes
+
| ''Si_gs_rt_pulse.inp'' || input file that contain namelist variables and their values.         
 
|-
 
|-
| &control || parameters related to general conditions for the calculation
+
| ''Si_rps.dat'' || pseodupotential file for Carbon
 +
|}
 +
 
 +
* You may download the above 2 files (zipped file) from:
 +
 
 +
  [[media:Si_gs_rt_pulse_input.zip| Download zipped input and pseudopotential files]]
 +
 
 +
* In the input file ''Si_gs_rt_pulse.inp'', namelists variables are specified. Most of them are mandatory to execute the calculation. We present explanations of the namelist variables that appear in the input file in:
 +
 
 +
[[Explanation of input files (crystalline silicon under a pulsed electric field)-v.1.0.0]]
 +
 
 +
 +
: This will help you to prepare the input file for other systems that you want to calculate. A complete list of the namelist variables that can be used in the input file can be found in the downloaded file ''SALMON/manual/input_variables.md''.
 +
 
 +
==== Output files ====
 +
: After the calculation, following output files are created in the directory that you run the code,
 +
 
 +
{| class="wikitable"
 +
| file name      || description
 
|-
 
|-
| &units        || specify units of input and output files
+
| ''Si_gs_info.data'' || information of ground state calculation
 
|-
 
|-
| &parallel      || parameters related to parallelization
+
| ''Si_eigen.data'' || energy eigenvalues of orbitals
 
|-
 
|-
| &system      || information related to the system
+
| ''Si_k.data'' || information on k-points
 
|-
 
|-
| &pseudo      || information related to pseudopotentials
+
| ''Si_rt.data'' || electric field, vector potential, and current as functions of time
 
|-
 
|-
| &functional || specify density functional to be used
+
| ''Si_force.data'' || force acting on atoms
 
|-
 
|-
| &rgrid        || parameters related to real space grid 
+
| ''Si_lr.data'' || Fourier transformations of various quantities
 
|-
 
|-
| &kgird      || parameters related to k-points for periodic systems
+
| ''Si_gs_rt_pulse.out'' || standard output file
 +
|}
 +
 
 +
* You may download the above files (zipped file) from:
 +
 
 +
[[media:Si_gs_rt_pulse_output.zip|Download zipped output files]]
 +
 
 +
* Explanations of the output files are described in:
 +
 
 +
[[Explanation of output files (crystalline silicon under a pulsed electric field)-v.1.0.0]]
 +
 
 +
== Maxwell + TDDFT multiscale simulation ==
 +
 
 +
=== Tutorial-6: Pulsed-light propagation through a silicon thin film ===
 +
In this tutorial, we learn the calculation of the propagation of a pulsed light through a thin film of crystalline silicon.
 +
We consider a silicon thin film of ?? nm thickness, and an irradiation of a few-cycle, linearly polarized pulsed light normally on the thin film.
 +
First, to set up initial orbitals, the ground state calculation is carried out.
 +
The pulsed light locates in the vacuum region in front of the thin film.
 +
The parameters that characterize the pulsed light such as magnitude and frequency are specified in the input file.
 +
The calculation ends when the reflected and transmitted pulses reach the vacuum region.
 +
 
 +
==== Input files ====
 +
: To run the code, following files are used:
 +
 
 +
{| class="wikitable"
 +
| file name      || description
 
|-
 
|-
| &tgrid      || parameters related to time evolution
+
| ''Si_gs_rt_multiscale.inp'' || input file that contain namelist variables and their values.         
 
|-
 
|-
| &propagation || specify a choice of the propagation method
+
| ''Si_rps.dat'' || pseodupotential file for silicon
|-
+
|}
| &scf          || parameters related to ground state calculation
+
 
 +
* You may download the above two files (zipped file) from:
 +
 
 +
[[media: Si_gs_rt_multiscale_input.zip| Download zipped input and pseudopotential files]]
 +
 
 +
 
 +
* In the input file ''Si_gs_rt_multiscale.inp'', namelists variables are specified. Most of them are mandatory to execute the calculation. We present explanations of the namelist variables that appear in the input file in:
 +
 
 +
[[Explanation of input files (pulsed-light propagation through a silicon thin film)-v.1.0.0]]
 +
 
 +
 +
: This will help you to prepare the input file for other systems that you want to calculate. A complete list of the namelist variables that can be used in the input file can be found in the downloaded file ''SALMON/manual/input_variables.md''.
 +
 
 +
==== Output files ====
 +
: After the calculation, following output files are created in the directory that you run the code,
 +
 
 +
{| class="wikitable"
 +
| file name      || description
 
|-
 
|-
| &emfield  || parameters of electric fields applied to the system
+
| ''Si_gs_info.data'' || results of the ground state as well as input parameters
 
|-
 
|-
| &linear_response || magnitude of the distortion for linear response
+
| ''Si_eigen.data'' || orbital energies in the ground state calculation
 
|-
 
|-
| &multiscale || parameters related to coupled multiscale calculations of electron dynamics and light propagations
+
| ''Si_k.data'' || information on k-points
 
|-
 
|-
| &analysis || parameters related to output files
+
| ''Si_Ac_xxxxxx.data'' || various quantities at a time as functions of macroscopic position
 
|-
 
|-
| &hartree      || parameters related to Hartree potential calculation of isolated systems
+
| ''Si_Ac_M_xxxxxx.data'' || various quantities at a macroscopic point as functions of time
 
|-
 
|-
| &ewald  || parameters related to Ewald sum that appears in the ground state calculation of periodic systems
+
| ''Si_Ac_vac.data'' || vector potential at vacuum position adjacent to the medium
 
|-
 
|-
| &atomic_coor || Atomic coordinates can be written here
+
| ''Si_gs_rt_multiscale.out'' || standard output file
 
|}
 
|}
  
In [[Samples]], we prepare six samples that cover typical calculations feasible by using SALMON.  
+
* You may download the above files (zipped file) from:
We prepare explanations for the input files that will help to prepare input files of your own interests.
+
 
 +
[[media:Si_gs_rt_multiscale_output.zip|Download zipped output files]]
 +
 
 +
* Explanations of the output files are described in:
 +
 
 +
[[Explanation of output files (pulsed-light propagation through a silicon thin film)-v.1.0.0]]
 +
 
 +
== Namelists and their values ==
 +
 
 +
We here summarize namelists that appear in this Tutorial.
 +
A thorough list of the namelist variables may be found in the downloaded file in
 +
'SALMON/manual/input_variables.md'.
 +
 
 +
=== &units ===
 +
 
 +
Mandatory: none
 +
 
 +
&units
 +
  unit_system='A_eV_fs'
 +
/
 +
 
 +
This namelist specifies the unit system to be used in the input file.
 +
Options are 'A_eV_fs' for Angstrom, eV, and fs, and 'a.u.' or 'au' for atomic units.
 +
If you do not specify it, atomic unit will be used as default.
 +
 
 +
For isolated systems (specified by <code>iperiodic = 0</code> in <code>&system</code>), the unit of 1/eV is used for the output files of DOS and PDOS if <code>unit_system = 'A_eV_fs'</code> is specified, while atomic unit is used if not. For other output files, the Angstrom/eV/fs units are used  irrespective of the namelist value.
 +
 
 +
For periodic systems (specified by <code>iperiodic =3</code> in <code>&system</code>), the unit system specified by this namelist variable is used for most output files. See the first few lines of output files to confirm the unit system adopted in the file.
 +
 
 +
=== &calculation ===
 +
 
 +
Mandatory: calc_mode
 +
 
 +
&calculation
 +
  calc_mode = 'GS'
 +
/
 +
 
 +
The value of the <code>calc_mode</code> should be one of <code>'GS'</code>, <code>'RT'</code>, and <code>'GS-RT'</code>.
 +
For isolated systems (specified by <code>iperiodic = 3</code> in <code>&system</code>), the ground state (<code>'GS'</code>) and the real time (<code>'RT'</code>) calculations should be done separately and sequentially.
 +
For periodic systems (specified by <code>iperiodic = 3</code> in <code>&system</code>), both ground state and real time calculations should be carried out as a single task (<code>calc_mode = 'GS_RT'</code>).
 +
 
 +
For Maxwell + TDDFT multi-scale calculation, add the following namelist.
 +
 
 +
    use_ms_maxwell = 'y'
 +
 
 +
=== &control ===
 +
 
 +
Mandatory: none
 +
 
 +
&control
 +
  sysname = 'C2H2'
 +
/
 +
 
 +
'C2H2' defined by <code>sysname = 'C2H2'</code> will be used in the filenames of output files.
 +
If you do not specify it, the file name will start with 'default'.
  
Here we briefly explain the format of the namelist.
+
=== &functional ===
  
&namelist1
+
  &functional
  variable1 = int_value
+
    xc ='PZ'
  variable2 = 'char_value'
 
 
   /
 
   /
  &namelist2
+
 
   variable1 = real8_value
+
<code>xc ='PZ'</code> indicates that (adiabatic) local density approximation is adopted (Perdew-Zunger: Phys. Rev. B23, 5048 (1981)).
   variable2 = int_value1, int_value2, int_value3
+
This is the default choice.
 +
 
 +
For isolated systems (specified by <code>iperiodic = 0</code> in <code>&system</code>), only the default choice of 'PZ' is available at present.
 +
 
 +
For periodic systems (specified by <code>iperiodic = 3</code> in <code>&system</code>),  the following functionals may be available in addition to 'PZ':
 +
 
 +
xc = 'PZM'
 +
 
 +
Perdew-Zunger LDA with modification to improve sooth connection between high density form and low density one. :J. P. Perdew and Alex Zunger, Phys. Rev. B 23, 5048 (1981).
 +
 
 +
xc = 'TBmBJ'
 +
  cval = 1.0
 +
 
 +
Tran-Blaha meta-GGA exchange with Perdew-Wang correlation. :Fabien Tran and Peter Blaha, Phys. Rev. Lett. 102, 226401 (2009). John P. Perdew and Yue Wang, Phys. Rev. B 45, 13244 (1992). This potential is known to provide a reasonable description for the bandage of various insulators. For this choice, the additional mixing parameter 'cval' may be specified. If cval is set to a minus value, the mixing-parameter will be computed following the formula in the original paper [Phys. Rev. Lett. 102, 226401 (2009)]. The default value for this parameter is 1.0.
 +
 
 +
=== &system ===
 +
 
 +
Mandatory: iperiodic, al, nstate, nelem, natom
 +
 
 +
'''For an isolated molecule (Tutorial-1, 2, 3)''':
 +
 
 +
&system
 +
  iperiodic = 0
 +
   al = 16d0, 16d0, 16d0
 +
  nstate = 5
 +
  nelem = 2
 +
  natom = 4
 +
  nelec = 10
 +
/
 +
 
 +
<code>iperiodic = 0</code> indicates that the isolated boundary condition will be used in the calculation.
 +
<code>al = 16d0, 16d0, 16d0</code> specifies the lengths of three sides of the rectangular parallelepiped where the grid points are prepared.
 +
<code>nstate = 8</code> indicates the number of Kohn-Sham orbitals to be solved.
 +
<code>nelec = 10</code> indicate the number of valence electrons in the system. Since the present code assumes that the system is spin saturated, <code>nstate</code> should be equal to or larger than <code>nelec/2</code>.
 +
<code>nelem = 2</code> and <code>natom = 4</code> indicate the number of elements and the number of atoms in the system, respectively.
 +
 
 +
'''For a periodic system (Tutorial-4, 5)''':
 +
 +
&system
 +
  iperiodic = 3
 +
  al = 10.26d0,10.26d0,10.26d0
 +
  nstate = 32
 +
  nelec = 32
 +
  nelem = 1
 +
  natom = 8
 +
/
 +
 
 +
<code>iperiodic = 3</code> indicates that three dimensional periodic boundary condition (bulk crystal) is assumed.
 +
<code>al = 10.26d0, 10.26d0, 10.26d0</code> specifies the lattice constans of the unit cell.
 +
<code>nstate = 32</code> indicates the number of Kohn-Sham orbitals to be solved.
 +
<code>nelec = 32</code> indicate the number of valence electrons in the system.
 +
<code>nelem = 1</code> and <code>natom = 8</code> indicate the number of elements and the number of atoms in the system, respectively.
 +
 
 +
'''For Maxwell - TDDFT multi scale calculation (Tutorial-6)''':
 +
 
 +
  &system
 +
    iperiodic = 3
 +
    al = 10.26d0,10.26d0,10.26d0
 +
    isym = 8
 +
    crystal_structure = 'diamond'
 +
    nstate = 32
 +
    nelec = 32
 +
    nelem = 1
 +
    natom = 8
 +
  /
 +
 
 +
The difference from the above case is the variables, <code>isym = 8</code> and <code>crystal_structure = 'diamond'</code>,
 +
which indicates that the spatial symmetry of the unit cell is used in the calculation.
 +
Although the use of the symmetry substantially reduces the computational cost, it should be used very carefully.
 +
At present, the spatial symmetry has been implemented only for the case of the diamond structure.
 +
 
 +
=== &pseudo ===
 +
 
 +
Mandatory: pseudo_file, izatom
 +
 
 +
'''For C2H2 molecule''':
 +
 
 +
&pseudo
 +
  izatom(1)=6
 +
  izatom(2)=1
 +
  pseudo_file(1)='C_rps.dat'
 +
  pseudo_file(2)='H_rps.dat'
 +
  lmax_ps(1)=1
 +
  lmax_ps(2)=0
 +
  lloc_ps(1)=1
 +
  lloc_ps(2)=0
 +
/
 +
 
 +
Parameters related to atomic species and pseudopotentials.
 +
<code>izatom(1) = 6</code> specifies the atomic number of the element #1.
 +
<code>pseudo_file(1) = 'C_rps.dat'</code> indicates the filename of the pseudopotential of element #1.
 +
<code>lmax_ps(1) = 1</code> and <code>lloc_ps(1) = 1</code> specify the maximum angular momentum of the pseudopotential projector and the angular momentum of the pseudopotential that will be treated as local, respectively.
 +
 
 +
'''For crystalline Si''':
 +
 
 +
&pseudo
 +
  izatom(1)=14
 +
  pseudo_file(1) = './Si_rps.dat'
 +
  lloc_ps(1)=2
 +
/
 +
 
 +
<code>izatom(1) = 14</code> indicates the atomic number of the element #1.
 +
<code>pseudo_file(1) = 'Si_rps.dat'</code> indicates the  pseudopotential filename of element #1.
 +
<code>lloc_ps(1) = 2</code> indicate the angular momentum of the pseudopotential that will be treated as local.
 +
 
 +
=== &atomic_coor ===
 +
 
 +
Mandatory: atomic_coor or atomic_red_coor (they may be provided as a separate file)
 +
 
 +
'''For C2H2 molecule''':
 +
 
 +
&atomic_coor
 +
'C'    0.000000    0.000000    0.599672  1
 +
'H'    0.000000    0.000000    1.662257  2
 +
'C'    0.000000    0.000000  -0.599672  1
 +
'H'    0.000000    0.000000  -1.662257  2
 +
/
 +
 
 +
Cartesian coordinates of atoms. The first column indicates the element. Next three columns specify Cartesian coordinates of the atoms. The number in the last column labels the element.
 +
 
 +
=== &atomic_red_coor ===
 +
 
 +
Mandatory: atomic_coor or atomic_red_coor (they may be provided as a separate file)
 +
 
 +
'''For a crystalline silicon''':
 +
 
 +
&atomic_red_coor
 +
  'Si'    .0      .0      .0      1
 +
  'Si'    .25    .25    .25    1
 +
  'Si'    .5      .0      .5      1
 +
  'Si'    .0      .5      .5      1
 +
  'Si'    .5      .5      .0      1
 +
  'Si'    .75    .25  .75    1
 +
  'Si'    .25    .75  .75    1
 +
  'Si'    .75    .75  .25    1
 +
/
 +
 
 +
Cartesian coordinates of atoms are specified in a reduced coordinate system. First column indicates the element, next three columns specify reduced Cartesian coordinates of the atoms, and the last column labels the element.
 +
 
 +
=== &rgrid ===
 +
 
 +
Mandatory: dl or num_rgrid
 +
 
 +
This namelist provides grid spacing of Cartesian coordinate system.
 +
<code>dl(3)</code> specify the grid spacing in three Cartesian coordinates.
 +
This is adopted for C2H2 calculation (Tutorial-1).
 +
 
 +
&rgrid
 +
   dl = 0.25d0, 0.25d0, 0.25d0
 
  /
 
  /
  
A block of namelists starts with ''&namelist'' line and ends with ''/'' line.
+
<code>num_rgrid(3)</code> specify the number of grid points in each Cartesian direction.
Between two lines, descriptions of variables and their values appear.  
+
This is adopted for crystalline Is calculation (Tutorial-4, 5, 6).
Note that many variables have their default values so that it is not necessary to give values for all variables.  
+
 
The description of the variables may appear at any position if they are between ''&namelist'' and ''/''.
+
&rgrid
Input files constitute of several blocks of namelists.
+
  num_rgrid = 12,12,12
The blocks can appear in any order.
+
/
 +
 
 +
=== &kgrid ===
 +
 
 +
Mandatory: none
 +
 
 +
This namelist provides grid spacing of k-space for periodic systems.
  
== Run SALMON ==
+
&kgrid
 +
  num_kgrid = 4,4,4
 +
/
  
To run SALMON, the executable file of ''salmon.cpu'' (and ''salmon.mic'' if your system is the many-core machine) should be built from the source file of SALMON as described above. An input file ''inputfile.inp'' and pseudopotential files should also be prepared as mentioned above.
+
=== &scf ===
In order to execute the calculation, for the single process environment, type the following command:
 
  
$ salmon.cpu < inputfile.inp > fileout.out
+
Mandatory: nscf
  
For the multiprocess environment, If the command to execute calculations using MPI is ''mpiexec',  the calculation will start
+
This namelists specify parameters related to the self-consistent field calculation.
  
  $ mpiexec -n NPROC salmon.cpu < inputfile.inp > fileout.out
+
  &scf
 +
  ncg = 4
 +
  nscf = 1000
 +
  convergence = 'norm_rho_dng'
 +
  threshold_norm_rho = 1.d-15
 +
/
  
where NPROC is the number of MPI processes you want to use.
+
<code>ncg = 4</code> is the number of conjugate-gradient iterations in solving the Kohn-Sham equation. Usually this value should be 4 or 5. <code>nscf = 1000</code> is the number of scf iterations. For isolated systems specified by <code>&system/iperiodic = 0</code>, the scf loop in the ground state calculation ends before the number of the scf iterations reaches <code>nscf</code>, if a convergence criterion is satisfied. There are several options to examine the convergence. If the value of <code>norm_rho_dng</code> is specified, the convergence is examined by the squared difference of the electron density,
For the many-core processor (e.g. intel-knl)  environment, the execution command is
 
  
$ mpiexec.hydra -n NPROC salmon.mic < inputfile.inp > fileout.out
+
=== &hartree ===
  
The execution command and the job submission procedure depends much on the local environment.
+
Mandatory: none
We just summarize the general conditions to execute SALMON:
 
  
* salmon runs in parallel environment using MPI.
+
&hartree
* executable files are prepared as ''/salmon/bin/salmon.cpu'' and/or ''/salmon/bin/salmon.mic'' in the standard build procedure.
+
  meo = 3
* to start calculations, ''inputfile.inp'' should be read through ''stdin''.
+
  num_pole_xyz = 2,2,2
 +
/
  
 +
<code>meo</code> specifies the order of multipole expansion of electron density that is used to prepare boundary condition for the Hartree potential.
 +
* <code>meo=1</code>: Monopole expansion (spherical boundary condition).
 +
* <code>meo=2</code>: Multipole expansions around each atom.
 +
* <code>meo=3</code>: Multipole expansion around the center of mass of electrons in cubits that are defined by <code>num_pole_xyz</code>.
 +
<code>num_pole_xyz(3)</code> defines the division of space when <code>meo = 3</code> is specified.
  
 +
A default for <code>meo</code> is <code>3</code>, and defaults for <code>num_pole_xyz</code> are <code>(0,0,0)</code>.
 +
When default is set for <code>num_pole_xyz</code>, the division of space is carried out using a prescribed method.
  
 +
=== &tgrid ===
  
=  Appendix  =
+
Mandatory: dt, Nt
  
== Additional options in configure.py script ==
+
&tgrid
 +
  dt=1.25d-3
 +
  nt=5000
 +
/
  
In executing <code>configure.py</code>, you may manually specify compiler and environment variables instead of specifying the architecture, for example:
+
<code>dt=1.25d-3</code> specifies the time step of the time evolution calculation.
 +
<code>nt=5000</code> specifies the number of time steps in the calculation.
  
$ python ../configure.py FC=mpiifort CC=mpiicc FFLAGS="-xAVX" CFLAGS="-restrict -xAVX"
+
=== &propagation ===
  
The major options of <code>configure.py</code> is expressed as table below:
+
This namelist specifies the numerical method for time evolution calculations of electron orbitals.
{| class="wikitable"
 
| Commandline switch      || Detail                       
 
|-
 
| -a ARCH, --arch=ARCH || Target architecture 
 
|-
 
| --enable-mpi, --disable-mpi  ||  enable/disable MPI parallelization.
 
|-
 
| ---enable-scalapack, --disable-scalapack  ||  enable/disable computations with ScaLAPACK library
 
|-
 
| FC, FFLAGS  ||  User-defined Fortran Compiler, and the compiler options
 
|-
 
| CC, CFLAGS  ||  User-defined C Compiler, and the compiler options
 
|}
 
  
 +
&propagation
 +
  propagator='etrs'
 +
/
  
=== Build for Single processor environment ===
+
<code>propagator = 'etrs'</code> indicates the use of enforced time-reversal symmetry propagator.  [https://doi.org/10.1016/S0010-4655(02)00686-0 M.A.L. Marques, A. Castro, G.F. Bertsch, and A. Rubio, Comput. Phys. Commun., 151 60 (2003)].
  
If you want to build for the single process environment, please specify <code>--disable-mpi</code>.
+
&propagation
 +
  propagator='middlepoint'
 +
/
  
  $ python ../configure.py --arch=<ARCHITECTURE> --disable-mpi
+
<code>propagation='middlepoint'</code> indicates that Hamiltonian at midpoint of two-times is used.
  
=== Build for the GCC/GFortran environemnt ===
+
The default is ''middlepoint''.
  
If you want to build by using GCC/GFortran compiler, you specify:
+
=== &emfield ===
  
$ python ../configure.py FC=gfortran CC=gcc FFLAG=-O3 CFLAG=-O3
+
This namelist specifies the pulse shape of an electric filed applied to the system in time evolution calculations.
 +
We explain below separating two cases, [[#Linear response calculations]] and [[#Pulsed electric field calculations]].
  
== Build by GNU Makefile ==
+
==== Linear response calculations ====
  
If CMake build fails in your environment, you can try Gnu Make for the build process.
+
A weak impulsive field is applied at ''t=0''.
 +
For this case, <code>ae_shape1 = 'impulse'</code> should be described.
  
First, enter to the makefile directory:
+
Mandatory: ae_shape1
  
  $ cd SALMON/makefiles
+
  &emfield
 +
  ae_shape1 = 'impulse'
 +
  epdir_re1 = 0.d0,0.d0,1.d0
 +
/
  
and  you need to choose ''Makefile'' appropriately according to your environment. The available makefiles are
+
<code>epdir_rel(3)</code> specify a unit vector that indicates the direction of the impulse.
* fujitsu
 
* gnu
 
* gnu-without-mpi
 
* intel
 
* intel-avx
 
* intel-avx2
 
* intel-knc
 
* intel-knl
 
* intel-without-mpi
 
  
The <code>-without-mpi</code> specifies the build for the single process environment.
+
For a periodic system specified by <code>iperiodic = 3</code>, one may add <code>trans_longi</code>.
Execute make command with the platform specified makefile:
+
It has the value, <code>'tr'</code>(transverse) or <code>'lo'</code>(longitudinal), that specifies the treatment of the
 +
polarization in the time evolution calculation. The default is <code>'tr'</code>.
 +
 
 +
&emfield
 +
  trans_longi = 'tr'
 +
  ae_shape1 = 'impulse'
 +
  epdir_re1 = 0.,0.,1.
 +
/
 +
 
 +
The magnitude of the impulse of the pulse may be explicitly specified by, for example, <code>e_impulse = 1d-2</code>. The default is '1d-2' in atomic unit.
 +
 
 +
==== Pulsed electric field calculations ====
 +
 
 +
A Pulsed electric field of finite time duration is applied.
 +
For this case, <code>as_shape1</code> should be specified.
 +
It indicates the shape of the envelope of the pulse.
 +
The options include 'Acos2' and 'Ecos2' (See below for other options).
 +
 
 +
Mandatory: ae_shape1, epdir_re1, {rlaser_int1 or amplitude1}, omega1, pulse_tw1, phi_cep1
 +
 
 +
&emfield
 +
  ae_shape1 = 'Ecos2'
 +
  epdir_re1 = 0.d0,0.d0,1.d0
 +
  rlaser_int_wcm2_1 = 1.d8
 +
  omega1=9.28d0
 +
  pulse_tw1=6.d0
 +
  phi_cep1=0.75d0
 +
/
 +
 
 +
<code>ae_shape1 = 'Ecos2'</code> specifies the envelope of the pulsed electric field,
 +
'Ecos2' for the cos^2 envelope for the electric field.
 +
If 'Acos2' is specified, this gives cos^2 envelope for the vector potential.
 +
Note that 'phi_cep1' must be 0.75 (or 0.25) if one employs 'Ecos2' pulse shape, since otherwise the time integral of the electric field does not vanish.
 +
There is no such restriction for the 'Acos2' pulse shape.
 +
 
 +
<code>epdir_re1 = 0.d0,0.d0,1.d0</code> specifies the real part of the unit polarization vector of the pulsed electric field.
 +
If only the real part is specified, it describes a linearly polarized pulse.
 +
Using both real ('epdir_re1') and imaginary ('epdir_im1') parts of the polarization vector, circularly (and general ellipsoidary) polarized pulses may be described.
 +
 +
<code>laser_int_wcm2_1 = 1.d8</code> specifies the maximum intensity of the applied electric field in unit of W/cm^2.
 +
It is also possible to specify the maximum intensity of the pulse by <code>amplitude1</code>.
 +
 
 +
<code>omega1=9.26d0</code> specifies the average photon energy (frequency multiplied with hbar).
 +
 
 +
<code>pulse_tw1=6.d0</code> specifies the pulse duration.
 +
Note that it is not the FWHM but a full duration of the cos^2 envelope.
 +
 
 +
<code>phi_cep1=0.75d0</code> specifies the carrier envelope phase of the pulse.
 +
As noted above, 'phi_cep1' must be 0.75 (or 0.25) if one employs 'Ecos2' pulse shape, since otherwise the time integral of the electric field does not vanish.
 +
There is no such restriction for the 'Acos2' pulse shape.
 +
 
 +
It is possible to use two pulses simultaneously to simulate pump-probe experiments, adding information for two pulses.
 +
To specify the second pulse, change from 1 to 2 in the namelist variables, like <code>ae_shape2</code>.
 +
The time delay between two pulses is specified by the variable 't1_t2'.
 +
 
 +
For a periodic system specified by <code>iperiodic = 3</code>, one may add <code>trans_longi</code>.
 +
It has the value, <code>'tr'</code>(transverse) or <code>'lo'</code>(longitudinal), that specifies the treatment of the
 +
polarization in the time evolution calculation. The default is <code>'tr'</code>.
 +
For a periodic system, it is also specify 'Acos3', 'Acos4', 'Acos6', 'Acos8' for <code>ae_shape1</code>.
 +
 
 +
=== &analysis ===
 +
 
 +
Mandatory: none
 +
 
 +
The following namelists specify whether the output files are created or not after the calculation.
 +
In the ground state calculation of isolated systems (Tutorial-1):
 +
 
 +
&analysis
 +
  out_psi = 'y'
 +
  out_dns = 'y'
 +
  out_dos = 'y'
 +
  out_pdos = 'y'
 +
  out_elf = 'y'
 +
/
 +
 
 +
In the time evolution calculation of isolated systems (Tutorial-3):
 +
 
 +
&analysis
 +
  out_dns_rt = 'y'
 +
  out_elf_rt = 'y'
 +
  out_estatic_rt = 'y'
 +
/
 +
 
 +
In the following namelists, variables related to time-frequency Fourier analysis are specified.
 +
 
 +
&analysis
 +
  nenergy=1000
 +
  de=0.001
 +
/
 +
 
 +
<code>nenergy=1000</code> specifies the number of energy steps, and <code>de=0.001</code> specifies the energy spacing in the time-frequency Fourier transformation.
 +
 
 +
=== &multiscale ===
 +
 
 +
This namelist specifies information necessary for Maxwell - TDDFT multiscale calculations.
 +
 
 +
&multiscale
 +
  fdtddim = '1D'
 +
  twod_shape = 'periodic'
 +
  nx_m  = 4
 +
  ny_m  = 1
 +
  hX_m = 250d0
 +
  nxvacl_m = -2000
 +
  nxvacr_m = 256
 +
/
 +
 
 +
<code>fdtddim</code> specifies the spatial dimension of the macro system. <code>fdtddim='1D'</code> indicates that one-dimensional equation is solved for the macroscopic vector potential.
 +
 
 +
<code>nx_m = 4</code> specifies the number of the macroscopic grid points in for x-direction in the spatial region where the material exists.
 +
 
 +
<code>hx_m = 250d0</code> specifies the grid spacing of the macroscopic grid in x-direction.
 +
 
 +
<code> nxvacl_m = -2000</code> and <code>nxvacr_m = 256</code> indicate the number of grid points in the vacuum region, <code>nxvacl_m</code> for the left and <code>nxvacr_m</code> for the right from the surface of the material.
 +
 
 +
=== &parallel ===
 +
When you execute a job with MPI parallelization, you are not required to specify any parameters that describe the assignment of the parallelization; the assignment is carried out automatically.  You may also specify the parameters explicitly as below.
 +
 
 +
Mandatory: none
 +
 
 +
&parallel
 +
  nproc_ob = 1
 +
  nproc_domain = 1,1,1
 +
  nproc_domain_s = 1,1,1
 +
/
  
  $ make -f Makefile.PLATFORM
+
* <code>nproc_ob</code> specifies the number of MPI parallelization to divide the electron orbitals. The default value is 0 (automatic parallelization).
 +
* <code>nproc_domain(3)</code>specifies the number of MPI parallelization to divide the spatial grids of the electron orbitals in three Cartesian directions. The default values are (0/0/0) (automatic parallelization).
 +
* <code>nproc_domain_s(3)'</code> specifies the number of MPI parallelization to divide the spatial grids related to the electron density in three Cartesian directions. The default values are (0/0/0) (automatic parallelization).
  
The binary file is created in the directory <code>SALMON/bin/</code>.
+
The following conditions must be satisfied.
 +
* The total number of processors must be equal to both <code>nproc_ob * nproc_domain(1) * nproc_domain(2) * nproc_domain(3)</code> and also <code>nproc_domain_s(1) * nproc_domain_s(2) * nproc_domain_s(3)</code>.
 +
* <code>nproc_domain_s(1)</code> is a multiple of <code>nproc_domain(1)</code>, and the same relations to the second and third components.

Latest revision as of 14:11, 23 November 2017

Getting started

Welcome to SALMON Tutorial!

In this tutorial, we explain the use of SALMON from the very beginning, taking a few samples that cover applications of SALMON in several directions. We assume that you are in the computational environment of UNIX/Linux OS. First you need to download and install SALMON in your computational environment. If you have not yet done it, do it following the instruction, download-v.1.0.0 and Install and Run-v.1.0.0.

As described in Install and Run-v.1.0.0, you are required to prepare at least an input file and pseudopotential files to run SALMON. In the following, we present input files for several sample calculations and provide a brief explanation of the namelist variables that appear in the input files. You may modify the input files to execute for your own calculations. Pseudopotential files of elements that appear in the samples are also attached. We also present explanations of main output files.

We present 6 tutorials.

First 3 tutorials (Tutorial-1 ~ 3) are for an isolated molecule, acetylene C2H2. If you are interested in learning electron dynamics calculations in isolated systems, please look into these tutorials. In SALMON, we usually calculate the ground state solution first. This is illustrated in Tutorial-1. After finishing the ground state calculation, two tutorials of electron dynamics calculations are prepared. Tutorial-2 illustrates the calculation of linear optical responses in real time, obtaining polarizability and photoabsorption of the molecule. Tutorial-3 illustrates the calculation of electron dynamics in the molecule under a pulsed electric field.

Next 2 tutorials (Tutorial-4 ~ 5) are for a crystalline solid, silicon. If you are interested in learning electron dynamics calculations in extended periodic systems, please look into these tutorials. Since ground state calculations of small unit-cell systems are not computationally expensive and a time evolution calculation is usually much more time-consuming than the ground state calculation, we recommend to run the ground and the time evolution calculations as a single job. The following two tutorials are organized in that way. Tutorial-4 illustrates the calculation of linear response properties of crystalline silicon to obtain the dielectric function. Tutorial-5 illustrates the calculation of electron dynamics in the crystalline silicon induced by a pulsed electric field.

The final tutorial (Tutorial-6) is for an irradiation and a propagation of a pulsed light in a bulk silicon, coupling Maxwell equations for the electromagnetic fields of the pulsed light and the electron dynamics in the unit cells. This calculation is quite time-consuming and is recommended to execute using massively parallel supercomputers. Tutorial-6 illustrates the calculation of a pulsed, linearly polarized light irradiating normally on a surface of a bulk silicon.

C2H2 (isolated molecules)

Tutorial-1: Ground state of C2H2 molecule

In this tutorial, we learn the calculation of the ground state solution of acetylene (C2H2) molecule, solving the static Kohn-Sham equation. This tutorial will be useful to learn how to set up calculations in SALMON for any isolated systems such as molecules and nanoparticles. It should be noted that at present it is not possible to carry out the geometry optimization in SALMON. Therefore, atomic positions of the molecule are specified in the input file and are fixed during the calculations.

Input files

To run the code, following files are used:
file name description
C2H2_gs.inp input file that contains namelist variables and their values
C_rps.dat pseodupotential file for carbon atom
H_rps.dat pseudopotential file for hydrogen atom
  • You may download the above 3 files (zipped file) from:
 Download zipped input and pseudopotential files
  • In the input file C2H2_gs.inp, namelists variables are specified. Most of them are mandatory to execute the ground state calculation. We present their explanations below:
Explanations of input files (ground state of C2H2 molecule)-v.1.0.0
This will help you to prepare an input file for other systems that you want to calculate. A complete list of the namelist variables that can be used in the input file can be found in the downloaded file SALMON/manual/input_variables.md.

Output files

After the calculation, following output files are created in the directory that you run the code,
file name description
C2H2_info.data information on ground state solution
dns.cube a cube file for electron density
elf.cube electron localization function (ELF)
psi1.cube, psi2.cube, ... electron orbitals
dos.data density of states
pdos1.data, pdos2.data, ... projected density of states
C2H2_gs.bin binary output file to be used in the real-time calculation
  • You may download the above files (zipped file, except for the binary file C2H2_gs.bin) from:
Download zipped output files
  • Main results of the calculation such as orbital energies are included in C2H2_info.data. Explanations of the C2H2_info.data and other output files are described in:
Explanations of output files (ground state of C2H2 molecule)-v.1.0.0

Images

We show several image that are created from the output files.
image files used to create the image
highest occupied molecular orbital (HOMO) psi1.cube, psi2.cube, ...
electron density dns.cube
electron localization function elf.cube

Tutorial-2: Polarizability and photoabsorption of C2H2 molecule

In this tutorial, we learn the linear response calculation in the acetylene (C2H2) molecule, solving the time-dependent Kohn-Sham equation. The linear response calculation provides the polarizability and the oscillator strength distribution of the molecule. This tutorial should be carried out after finishing the ground state calculation that was explained in Tutorial-1. In the calculation, an impulsive perturbation is applied to all electrons in the C2H2 molecule along the molecular axis which we take z axis. Then a time evolution calculation is carried out without any external fields. During the calculation, the electric dipole moment is monitored. After the time evolution calculation, a time-frequency Fourier transformation is carried out for the electric dipole moment to obtain the frequency-dependent polarizability. The imaginary part of the frequency-dependent polarizability is proportional to the oscillator strength distribution and the photoabsorption cross section.

Input files

To run the code, the input file C2H2_rt_response.inp that contains namelist variables and their values for the linear response calculation is required. The binary file C2H2_gs.bin that is created in the ground state calculation and pseudopotential files are also required. The pseudopotential files should be the same as those used in the ground state calculation.
file name description
C2H2_rt_response.inp input file that contains namelist variables and their values
C_rps.dat pseodupotential file for carbon
H_rps.dat pseudopotential file for hydrogen
C2H2_gs.bin binary file created in the ground state calculation
  • You may download the C2H2_rt_response.inp file (zipped file) from:
 Download zipped input file
  • In the input file C2H2_rt_response.inp, namelists variables are specified. Most of them are mandatory to execute the linear response calculation. We present their explanations below:
Explanations of input files (polarizability and photoabsorption of C2H2 molecule)-v.1.0.0

This will help you to prepare the input file for other systems that you want to calculate. A complete list of the namelist variables that can be used in the input file can be found in the downloaded file SALMON/manual/input_variables.md.

Output files

After the calculation, following output files are created in the directory that you run the code,
file name description
C2H2_lr.data polarizability and oscillator strength distribution as functions of energy
C2H2_p.data components of dipole moment as functions of time
  • You may download the above files (zipped file) from:
Download zipped output files
  • Explanations of the output files are given in:
Explanations of output files (polarizability and photoabsorption of C2H2 molecule)-v.1.0.0

Tutorial-3: Electron dynamics in C2H2 molecule under a pulsed electric field

In this tutorial, we learn the calculation of the electron dynamics in the acetylene (C2H2) molecule under a pulsed electric field, solving the time-dependent Kohn-Sham equation. As outputs of the calculation, such quantities as the total energy and the electric dipole moment of the system as functions of time are calculated. This tutorial should be carried out after finishing the ground state calculation that was explained in Tutorial-1. In the calculation, a pulsed electric field that has cos^2 envelope shape is applied. The parameters that characterize the pulsed field such as magnitude, frequency, polarization direction, and carrier envelope phase are specified in the input file.

Input files

To run the code, following files are used. The C2H2.data file is created in the ground state calculation. Pseudopotential files are already used in the ground state calculation. Therefore, C2H2_rt_pulse.inp that specifies namelist variables and their values for the pulsed electric field calculation is the only file that the users need to prepare.
file name description
C2H2_rt_pulse.inp input file that contain namelist variables and their values.
C_rps.dat pseodupotential file for Carbon
H_rps.dat pseudopotential file for Hydrogen
C2H2.data binary file created in the ground state calculation
  • You may download the C2H2_rt_pulse.inp file (zipped file) from:
 Download zipped input file
  • In the input file C2H2_rt_pulse.inp, namelists variables are specified. Most of them are mandatory to execute the calculation of electron dynamics induced by a pulsed electric field. We present explanations of the namelist variables that appear in the input file in:
Explanations of input files (C2H2 molecule under a pulsed electric field)-v.1.0.0

This will help you to prepare the input file for other systems and other pulsed electric fields that you want to calculate. A complete list of the namelist variables that can be used in the input file can be found in the downloaded file SALMON/manual/input_variables.md.

Output files

After the calculation, following output files are created in the directory that you run the code,
file name description
C2H2_p.data components of the electric dipole moment as functions of time
C2H2_ps.data power spectrum that is obtained by a time-frequency Fourier transformation of the electric dipole moment
  • You may download the above files (zipped file) from:
Download zipped output files
  • Explanations of the files are described in:
Explanations of output files (C2H2 molecule under a pulsed electric field)-v.1.0.0

Crystalline silicon (periodic solids)

Tutorial-4: Dielectric function of crystalline silicon

In this tutorial, we learn the linear response calculation of the crystalline silicon of a diamond structure. Calculation is done in a cubic unit cell that contains eight silicon atoms. Since the ground state calculation costs much less computational time than the time evolution calculation, both calculations are successively executed. After finishing the ground state calculation, an impulsive perturbation is applied to all electrons in the unit cell along z direction. Since the dielectric function is isotropic in the diamond structure, calculated dielectric function should not depend on the direction of the perturbation. During the time evolution, electric current averaged over the unit cell volume is calculated. A time-frequency Fourier transformation of the electric current gives us a frequency-dependent conductivity. The dielectric function may be obtained from the conductivity using a standard relation.

Input files

To run the code, following files are used:
file name description
Si_gs_rt_response.inp input file that contain namelist variables and their values.
Si_rps.dat pseodupotential file of silicon
  • You may download the above 2 files (zipped file) from:
 Download zipped input and pseudopotential files
  • In the input file Si_gs_rt_response.inp, namelists variables are specified. Most of them are mandatory to execute the calculation. We present explanations of the namelist variables that appear in the input file in:
Explanations of input files (dielectric function of crystalline silicon)-v.1.0.0


This will help you to prepare the input file for other systems that you want to calculate. A complete list of the namelist variables that can be used in the input file can be found in the downloaded file SALMON/manual/input_variables.md.

Output files

After the calculation, following output files are created in the directory that you run the code,
file name description
Si_gs_info.data information of ground state calculation
Si_eigen.data energy eigenvalues of orbitals
Si_k.data information on k-points
Si_rt.data electric field, vector potential, and current as functions of time
Si_force.data force acting on atoms
Si_lr.data Fourier spectra of the dielectric functions
Si_gs_rt_response.out standard output file
  • You may download the above files (zipped file) from:
Download zipped output files
  • Explanations of the output files are described in:
Explanation of output fiels (dielectric function of crystalline silicon)-v.1.0.0

Tutorial-5: Electron dynamics in crystalline silicon under a pulsed electric field

In this tutorial, we learn the calculation of electron dynamics in a unit cell of crystalline silicon of a diamond structure. Calculation is done in a cubic unit cell that contains eight silicon atoms. Since the ground state calculation costs much less computational time than the time evolution calculation, both calculations are successively executed. After finishing the ground state calculation, a pulsed electric field that has cos^2 envelope shape is applied. The parameters that characterize the pulsed field such as magnitude, frequency, polarization, and carrier envelope phase are specified in the input file.

Input files

To run the code, following files are used:
file name description
Si_gs_rt_pulse.inp input file that contain namelist variables and their values.
Si_rps.dat pseodupotential file for Carbon
  • You may download the above 2 files (zipped file) from:
 Download zipped input and pseudopotential files
  • In the input file Si_gs_rt_pulse.inp, namelists variables are specified. Most of them are mandatory to execute the calculation. We present explanations of the namelist variables that appear in the input file in:
Explanation of input files (crystalline silicon under a pulsed electric field)-v.1.0.0


This will help you to prepare the input file for other systems that you want to calculate. A complete list of the namelist variables that can be used in the input file can be found in the downloaded file SALMON/manual/input_variables.md.

Output files

After the calculation, following output files are created in the directory that you run the code,
file name description
Si_gs_info.data information of ground state calculation
Si_eigen.data energy eigenvalues of orbitals
Si_k.data information on k-points
Si_rt.data electric field, vector potential, and current as functions of time
Si_force.data force acting on atoms
Si_lr.data Fourier transformations of various quantities
Si_gs_rt_pulse.out standard output file
  • You may download the above files (zipped file) from:
Download zipped output files
  • Explanations of the output files are described in:
Explanation of output files (crystalline silicon under a pulsed electric field)-v.1.0.0

Maxwell + TDDFT multiscale simulation

Tutorial-6: Pulsed-light propagation through a silicon thin film

In this tutorial, we learn the calculation of the propagation of a pulsed light through a thin film of crystalline silicon. We consider a silicon thin film of ?? nm thickness, and an irradiation of a few-cycle, linearly polarized pulsed light normally on the thin film. First, to set up initial orbitals, the ground state calculation is carried out. The pulsed light locates in the vacuum region in front of the thin film. The parameters that characterize the pulsed light such as magnitude and frequency are specified in the input file. The calculation ends when the reflected and transmitted pulses reach the vacuum region.

Input files

To run the code, following files are used:
file name description
Si_gs_rt_multiscale.inp input file that contain namelist variables and their values.
Si_rps.dat pseodupotential file for silicon
  • You may download the above two files (zipped file) from:
 Download zipped input and pseudopotential files


  • In the input file Si_gs_rt_multiscale.inp, namelists variables are specified. Most of them are mandatory to execute the calculation. We present explanations of the namelist variables that appear in the input file in:
Explanation of input files (pulsed-light propagation through a silicon thin film)-v.1.0.0


This will help you to prepare the input file for other systems that you want to calculate. A complete list of the namelist variables that can be used in the input file can be found in the downloaded file SALMON/manual/input_variables.md.

Output files

After the calculation, following output files are created in the directory that you run the code,
file name description
Si_gs_info.data results of the ground state as well as input parameters
Si_eigen.data orbital energies in the ground state calculation
Si_k.data information on k-points
Si_Ac_xxxxxx.data various quantities at a time as functions of macroscopic position
Si_Ac_M_xxxxxx.data various quantities at a macroscopic point as functions of time
Si_Ac_vac.data vector potential at vacuum position adjacent to the medium
Si_gs_rt_multiscale.out standard output file
  • You may download the above files (zipped file) from:
Download zipped output files
  • Explanations of the output files are described in:
Explanation of output files (pulsed-light propagation through a silicon thin film)-v.1.0.0

Namelists and their values

We here summarize namelists that appear in this Tutorial. A thorough list of the namelist variables may be found in the downloaded file in 'SALMON/manual/input_variables.md'.

&units

Mandatory: none

&units
  unit_system='A_eV_fs'
/

This namelist specifies the unit system to be used in the input file. Options are 'A_eV_fs' for Angstrom, eV, and fs, and 'a.u.' or 'au' for atomic units. If you do not specify it, atomic unit will be used as default.

For isolated systems (specified by iperiodic = 0 in &system), the unit of 1/eV is used for the output files of DOS and PDOS if unit_system = 'A_eV_fs' is specified, while atomic unit is used if not. For other output files, the Angstrom/eV/fs units are used irrespective of the namelist value.

For periodic systems (specified by iperiodic =3 in &system), the unit system specified by this namelist variable is used for most output files. See the first few lines of output files to confirm the unit system adopted in the file.

&calculation

Mandatory: calc_mode

&calculation
  calc_mode = 'GS'
/

The value of the calc_mode should be one of 'GS', 'RT', and 'GS-RT'. For isolated systems (specified by iperiodic = 3 in &system), the ground state ('GS') and the real time ('RT') calculations should be done separately and sequentially. For periodic systems (specified by iperiodic = 3 in &system), both ground state and real time calculations should be carried out as a single task (calc_mode = 'GS_RT').

For Maxwell + TDDFT multi-scale calculation, add the following namelist.

   use_ms_maxwell = 'y'

&control

Mandatory: none

&control
  sysname = 'C2H2'
/

'C2H2' defined by sysname = 'C2H2' will be used in the filenames of output files. If you do not specify it, the file name will start with 'default'.

&functional

 &functional
   xc ='PZ'
 /

xc ='PZ' indicates that (adiabatic) local density approximation is adopted (Perdew-Zunger: Phys. Rev. B23, 5048 (1981)). This is the default choice.

For isolated systems (specified by iperiodic = 0 in &system), only the default choice of 'PZ' is available at present.

For periodic systems (specified by iperiodic = 3 in &system), the following functionals may be available in addition to 'PZ':

xc = 'PZM'

Perdew-Zunger LDA with modification to improve sooth connection between high density form and low density one. :J. P. Perdew and Alex Zunger, Phys. Rev. B 23, 5048 (1981).

xc = 'TBmBJ'
cval = 1.0

Tran-Blaha meta-GGA exchange with Perdew-Wang correlation. :Fabien Tran and Peter Blaha, Phys. Rev. Lett. 102, 226401 (2009). John P. Perdew and Yue Wang, Phys. Rev. B 45, 13244 (1992). This potential is known to provide a reasonable description for the bandage of various insulators. For this choice, the additional mixing parameter 'cval' may be specified. If cval is set to a minus value, the mixing-parameter will be computed following the formula in the original paper [Phys. Rev. Lett. 102, 226401 (2009)]. The default value for this parameter is 1.0.

&system

Mandatory: iperiodic, al, nstate, nelem, natom

For an isolated molecule (Tutorial-1, 2, 3):

&system
  iperiodic = 0
  al = 16d0, 16d0, 16d0
  nstate = 5
  nelem = 2
  natom = 4
  nelec = 10
/

iperiodic = 0 indicates that the isolated boundary condition will be used in the calculation. al = 16d0, 16d0, 16d0 specifies the lengths of three sides of the rectangular parallelepiped where the grid points are prepared. nstate = 8 indicates the number of Kohn-Sham orbitals to be solved. nelec = 10 indicate the number of valence electrons in the system. Since the present code assumes that the system is spin saturated, nstate should be equal to or larger than nelec/2. nelem = 2 and natom = 4 indicate the number of elements and the number of atoms in the system, respectively.

For a periodic system (Tutorial-4, 5):

&system
  iperiodic = 3
  al = 10.26d0,10.26d0,10.26d0
  nstate = 32
  nelec = 32
  nelem = 1
  natom = 8
/

iperiodic = 3 indicates that three dimensional periodic boundary condition (bulk crystal) is assumed. al = 10.26d0, 10.26d0, 10.26d0 specifies the lattice constans of the unit cell. nstate = 32 indicates the number of Kohn-Sham orbitals to be solved. nelec = 32 indicate the number of valence electrons in the system. nelem = 1 and natom = 8 indicate the number of elements and the number of atoms in the system, respectively.

For Maxwell - TDDFT multi scale calculation (Tutorial-6):

 &system
   iperiodic = 3
   al = 10.26d0,10.26d0,10.26d0
   isym = 8 
   crystal_structure = 'diamond'
   nstate = 32
   nelec = 32
   nelem = 1
   natom = 8
 /

The difference from the above case is the variables, isym = 8 and crystal_structure = 'diamond', which indicates that the spatial symmetry of the unit cell is used in the calculation. Although the use of the symmetry substantially reduces the computational cost, it should be used very carefully. At present, the spatial symmetry has been implemented only for the case of the diamond structure.

&pseudo

Mandatory: pseudo_file, izatom

For C2H2 molecule:

&pseudo
  izatom(1)=6
  izatom(2)=1
  pseudo_file(1)='C_rps.dat'
  pseudo_file(2)='H_rps.dat'
  lmax_ps(1)=1
  lmax_ps(2)=0
  lloc_ps(1)=1
  lloc_ps(2)=0
/

Parameters related to atomic species and pseudopotentials. izatom(1) = 6 specifies the atomic number of the element #1. pseudo_file(1) = 'C_rps.dat' indicates the filename of the pseudopotential of element #1. lmax_ps(1) = 1 and lloc_ps(1) = 1 specify the maximum angular momentum of the pseudopotential projector and the angular momentum of the pseudopotential that will be treated as local, respectively.

For crystalline Si:

&pseudo
  izatom(1)=14
  pseudo_file(1) = './Si_rps.dat'
  lloc_ps(1)=2
/

izatom(1) = 14 indicates the atomic number of the element #1. pseudo_file(1) = 'Si_rps.dat' indicates the pseudopotential filename of element #1. lloc_ps(1) = 2 indicate the angular momentum of the pseudopotential that will be treated as local.

&atomic_coor

Mandatory: atomic_coor or atomic_red_coor (they may be provided as a separate file)

For C2H2 molecule:

&atomic_coor
'C'    0.000000    0.000000    0.599672  1
'H'    0.000000    0.000000    1.662257  2
'C'    0.000000    0.000000   -0.599672  1
'H'    0.000000    0.000000   -1.662257  2
/

Cartesian coordinates of atoms. The first column indicates the element. Next three columns specify Cartesian coordinates of the atoms. The number in the last column labels the element.

&atomic_red_coor

Mandatory: atomic_coor or atomic_red_coor (they may be provided as a separate file)

For a crystalline silicon:

&atomic_red_coor
 'Si'    .0      .0      .0      1
 'Si'    .25    .25    .25    1
 'Si'    .5      .0      .5      1
 'Si'    .0      .5      .5      1
 'Si'    .5      .5      .0      1
 'Si'    .75    .25   .75     1
 'Si'    .25    .75   .75     1
 'Si'    .75    .75   .25     1
/

Cartesian coordinates of atoms are specified in a reduced coordinate system. First column indicates the element, next three columns specify reduced Cartesian coordinates of the atoms, and the last column labels the element.

&rgrid

Mandatory: dl or num_rgrid

This namelist provides grid spacing of Cartesian coordinate system. dl(3) specify the grid spacing in three Cartesian coordinates. This is adopted for C2H2 calculation (Tutorial-1).

&rgrid
  dl = 0.25d0, 0.25d0, 0.25d0
/

num_rgrid(3) specify the number of grid points in each Cartesian direction. This is adopted for crystalline Is calculation (Tutorial-4, 5, 6).

&rgrid
  num_rgrid = 12,12,12
/

&kgrid

Mandatory: none

This namelist provides grid spacing of k-space for periodic systems.

&kgrid
  num_kgrid = 4,4,4
/

&scf

Mandatory: nscf

This namelists specify parameters related to the self-consistent field calculation.

&scf
  ncg = 4
  nscf = 1000
  convergence = 'norm_rho_dng'
  threshold_norm_rho = 1.d-15
/

ncg = 4 is the number of conjugate-gradient iterations in solving the Kohn-Sham equation. Usually this value should be 4 or 5. nscf = 1000 is the number of scf iterations. For isolated systems specified by &system/iperiodic = 0, the scf loop in the ground state calculation ends before the number of the scf iterations reaches nscf, if a convergence criterion is satisfied. There are several options to examine the convergence. If the value of norm_rho_dng is specified, the convergence is examined by the squared difference of the electron density,

&hartree

Mandatory: none

&hartree
  meo = 3
  num_pole_xyz = 2,2,2
/

meo specifies the order of multipole expansion of electron density that is used to prepare boundary condition for the Hartree potential.

  • meo=1: Monopole expansion (spherical boundary condition).
  • meo=2: Multipole expansions around each atom.
  • meo=3: Multipole expansion around the center of mass of electrons in cubits that are defined by num_pole_xyz.

num_pole_xyz(3) defines the division of space when meo = 3 is specified.

A default for meo is 3, and defaults for num_pole_xyz are (0,0,0). When default is set for num_pole_xyz, the division of space is carried out using a prescribed method.

&tgrid

Mandatory: dt, Nt

&tgrid
  dt=1.25d-3
  nt=5000
/

dt=1.25d-3 specifies the time step of the time evolution calculation. nt=5000 specifies the number of time steps in the calculation.

&propagation

This namelist specifies the numerical method for time evolution calculations of electron orbitals.

&propagation
  propagator='etrs'
/

propagator = 'etrs' indicates the use of enforced time-reversal symmetry propagator. M.A.L. Marques, A. Castro, G.F. Bertsch, and A. Rubio, Comput. Phys. Commun., 151 60 (2003).

&propagation
  propagator='middlepoint'
/

propagation='middlepoint' indicates that Hamiltonian at midpoint of two-times is used.

The default is middlepoint.

&emfield

This namelist specifies the pulse shape of an electric filed applied to the system in time evolution calculations. We explain below separating two cases, #Linear response calculations and #Pulsed electric field calculations.

Linear response calculations

A weak impulsive field is applied at t=0. For this case, ae_shape1 = 'impulse' should be described.

Mandatory: ae_shape1

&emfield
  ae_shape1 = 'impulse'
  epdir_re1 = 0.d0,0.d0,1.d0
/

epdir_rel(3) specify a unit vector that indicates the direction of the impulse.

For a periodic system specified by iperiodic = 3, one may add trans_longi. It has the value, 'tr'(transverse) or 'lo'(longitudinal), that specifies the treatment of the polarization in the time evolution calculation. The default is 'tr'.

&emfield
  trans_longi = 'tr'
  ae_shape1 = 'impulse'
  epdir_re1 = 0.,0.,1.
/

The magnitude of the impulse of the pulse may be explicitly specified by, for example, e_impulse = 1d-2. The default is '1d-2' in atomic unit.

Pulsed electric field calculations

A Pulsed electric field of finite time duration is applied. For this case, as_shape1 should be specified. It indicates the shape of the envelope of the pulse. The options include 'Acos2' and 'Ecos2' (See below for other options).

Mandatory: ae_shape1, epdir_re1, {rlaser_int1 or amplitude1}, omega1, pulse_tw1, phi_cep1

&emfield
  ae_shape1 = 'Ecos2'
  epdir_re1 = 0.d0,0.d0,1.d0
  rlaser_int_wcm2_1 = 1.d8
  omega1=9.28d0
  pulse_tw1=6.d0
  phi_cep1=0.75d0
/

ae_shape1 = 'Ecos2' specifies the envelope of the pulsed electric field, 'Ecos2' for the cos^2 envelope for the electric field. If 'Acos2' is specified, this gives cos^2 envelope for the vector potential. Note that 'phi_cep1' must be 0.75 (or 0.25) if one employs 'Ecos2' pulse shape, since otherwise the time integral of the electric field does not vanish. There is no such restriction for the 'Acos2' pulse shape.

epdir_re1 = 0.d0,0.d0,1.d0 specifies the real part of the unit polarization vector of the pulsed electric field. If only the real part is specified, it describes a linearly polarized pulse. Using both real ('epdir_re1') and imaginary ('epdir_im1') parts of the polarization vector, circularly (and general ellipsoidary) polarized pulses may be described.

laser_int_wcm2_1 = 1.d8 specifies the maximum intensity of the applied electric field in unit of W/cm^2. It is also possible to specify the maximum intensity of the pulse by amplitude1.

omega1=9.26d0 specifies the average photon energy (frequency multiplied with hbar).

pulse_tw1=6.d0 specifies the pulse duration. Note that it is not the FWHM but a full duration of the cos^2 envelope.

phi_cep1=0.75d0 specifies the carrier envelope phase of the pulse. As noted above, 'phi_cep1' must be 0.75 (or 0.25) if one employs 'Ecos2' pulse shape, since otherwise the time integral of the electric field does not vanish. There is no such restriction for the 'Acos2' pulse shape.

It is possible to use two pulses simultaneously to simulate pump-probe experiments, adding information for two pulses. To specify the second pulse, change from 1 to 2 in the namelist variables, like ae_shape2. The time delay between two pulses is specified by the variable 't1_t2'.

For a periodic system specified by iperiodic = 3, one may add trans_longi. It has the value, 'tr'(transverse) or 'lo'(longitudinal), that specifies the treatment of the polarization in the time evolution calculation. The default is 'tr'. For a periodic system, it is also specify 'Acos3', 'Acos4', 'Acos6', 'Acos8' for ae_shape1.

&analysis

Mandatory: none

The following namelists specify whether the output files are created or not after the calculation. In the ground state calculation of isolated systems (Tutorial-1):

&analysis
  out_psi = 'y'
  out_dns = 'y'
  out_dos = 'y'
  out_pdos = 'y'
  out_elf = 'y'
/

In the time evolution calculation of isolated systems (Tutorial-3):

&analysis
  out_dns_rt = 'y'
  out_elf_rt = 'y'
  out_estatic_rt = 'y'
/

In the following namelists, variables related to time-frequency Fourier analysis are specified.

&analysis
 nenergy=1000
 de=0.001
/

nenergy=1000 specifies the number of energy steps, and de=0.001 specifies the energy spacing in the time-frequency Fourier transformation.

&multiscale

This namelist specifies information necessary for Maxwell - TDDFT multiscale calculations.

&multiscale
  fdtddim = '1D'
  twod_shape = 'periodic'
  nx_m  = 4
  ny_m  = 1
  hX_m = 250d0
  nxvacl_m = -2000
  nxvacr_m = 256
/

fdtddim specifies the spatial dimension of the macro system. fdtddim='1D' indicates that one-dimensional equation is solved for the macroscopic vector potential.

nx_m = 4 specifies the number of the macroscopic grid points in for x-direction in the spatial region where the material exists.

hx_m = 250d0 specifies the grid spacing of the macroscopic grid in x-direction.

nxvacl_m = -2000 and nxvacr_m = 256 indicate the number of grid points in the vacuum region, nxvacl_m for the left and nxvacr_m for the right from the surface of the material.

&parallel

When you execute a job with MPI parallelization, you are not required to specify any parameters that describe the assignment of the parallelization; the assignment is carried out automatically. You may also specify the parameters explicitly as below.

Mandatory: none

&parallel
  nproc_ob = 1
  nproc_domain = 1,1,1
  nproc_domain_s = 1,1,1
/
  • nproc_ob specifies the number of MPI parallelization to divide the electron orbitals. The default value is 0 (automatic parallelization).
  • nproc_domain(3)specifies the number of MPI parallelization to divide the spatial grids of the electron orbitals in three Cartesian directions. The default values are (0/0/0) (automatic parallelization).
  • nproc_domain_s(3)' specifies the number of MPI parallelization to divide the spatial grids related to the electron density in three Cartesian directions. The default values are (0/0/0) (automatic parallelization).

The following conditions must be satisfied.

  • The total number of processors must be equal to both nproc_ob * nproc_domain(1) * nproc_domain(2) * nproc_domain(3) and also nproc_domain_s(1) * nproc_domain_s(2) * nproc_domain_s(3).
  • nproc_domain_s(1) is a multiple of nproc_domain(1), and the same relations to the second and third components.