SALMON Manual for Beginners

Prerequisites

In this guide, it is assumed that readers have a basic knowledge on Unix. In the following, most works will be done in the command-line interface of Unix. For the installation of SALMON, following packages are required.

• Fortran90/C compiler with MPI support. Our package assumes users have one of the following compilers:
  • GCC (Gnu Compiler Collection)
  • Intel Fortran/C Compiler
  • Fujitsu Compiler (at FX100 / K-Computer)

• One of the following library packages for linear algebra:
  • BLAS/LAPACK
  • Intel Math Kernel Library (MKL)
  • Fujitsu Scientific Subroutine Library 2 (SSL-II)

• One of the following build tools.
  • CMake
  • Gnu Make

If you use other compilers, you may need to change build scripts (CMake, Makefile). If no numerical library is installed in your computer system, you may need to install BLAS/LAPACK by yourself. See Installation of BLAS/LAPACK.

Download

Newest version of the SALMON can be downloaded from Download. To extract files from the downloaded file salmon-<VERSION>.tar.gz, type the following command in the command-line,

$ tar –zxvf ./salmon-<VERSION>.tar.gz

After the extraction, the following directories will be created.

SALMON
 |- ARTED      Source codes related to periodic systems
 |- GCEED      Source codes related to isolated systems
 |- src        Source codes of core modules
 |- main       Source codes of the main routines
 |- example    Samples
 |- Makefile   Files related to building

Build

To compile SALMON to create executable binary files, two options are prepared, CMake and Gnu Make. If CMake works in your environment, we recommend to use it. If CMake fails in your environment, consider to use Gnu Make.

Build using CMake

First examine whether CMake is usable in your environment or not. Type the following in Unix command-line:

$ cmake --version

If CMake is not installed in your system, error message such as cmake: command not found will appear. If CMake is installed in your system, 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 older version is installed in your system, you need to install the new version by yourself.

The installation of the CMake is simple. A detailed description of the installation is given in Installation of CMake. 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

Then you will have the cmake binary file in bin directory. For the CMake binary file to be usable, you need to modify the Unix environmental variable $PATH appropriately.

Description how to modify the $PATH should come here

To confirm that CMake of the new version is usable in your environment, type cmake --version in the command-line.

Build using CMake specifying archtechture

Confirming that CMake of version 3.0.2 or later can be usable in your system, proceed the following steps. We assume that you are in the directory SALMON.

• Create a new temporary directory build and move to the directory,

$ mkdir build
$ cd build

• Execute the python script configure.py and then make,

$ python ../configure.py –arch=ARCHTECTURE
$ make

Here ARCHTECTURE specifies the architecture of the CPU in your computer system such as intel-avx. You need to choose ARCHTECUTRE from the following options:

arch	Detail	Compiler	Numerical Library
intel-knl	Intel Knights Landing	Intel Compiler	Intel MKL
intel-knc	Intel Knights Corner	Intel Compiler	Intel MKL
intel-avx	Intel Processer (Ivy-, Sandy-Bridge)	Intel Compiler	Intel MKL
intel-avx2	Intel Processer (Haswell, Broadwell ..)	Intel Compiler	Intel MKL
fujitsu-fx100	FX100 Su	Fujitsu Compiler	SSL-II
fujitsu-k	Fujitsu FX100 / K-computer	Fujitsu Compiler	SSL-II

If the build is successful, you will get a file salmon.cpu at the directory .salmon/bin. 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.

Build using Gnu Make

If CMake build fails in your environment, try Gnu Make for the build process. Gnu Make utilize a file, Makefile, which you can find at the directory SALMON/Makefile. First you need to modify Makefile appropriately according to your environment. Edit the Makefile using a text editor. At least you need to change the line that choose the architecture of the system, from line ?? to ??

# This is a makefile for SALMON program.
# please select architecture by deleting “#”
#ARCH = gnu
ARCH = intel
#ARCH = fujitsu
#ARCH = intel-knl

Then use make command in the command-line to build the executable file.

$ make

Files necessary to run SALMON

To run SALMON, at least two kinds of files are required for any calculations. One is an input file, with the filename extension of *.inp*, to be read through 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

SALMON utilizes norm-conserving pseudpotentials. You may find pseudopotentials of some elements in Samples. SALMON allows to use several formats of pseudpotentials that can be easily obtained from websites listed below.

pseudopotential	website
Ab-init FHI	http://www.ab-init

In the input file, you need to write the filename of the pseudopotential. Use exactly the same filename as that downloaded from the website or that in the Samples.

input file

Input file should be written using Fortran90 namelist format such as

&system
  iperiodic = 0
  al = 16d0, 16d0, 16d0
  nstate = 5
  nelem = 2
  natom = 4
  file_atom='coo.data'
/

where the system in &system indicates the name of the namelist. In iperiodic = 0, iperiodic is the variable name and 0 is the value. A group of namelists starts with &namelist line and ends with / line. Between two lines, descriptions of variables and their values appear. Note that many variables have their default values, so 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 /. Usually several groups of namelists are included in the input file. The order of the groups can be arbitrary.

SALMON describes electron dynamics in systems with both isolated and periodic boundary conditions. The boundary condition is specified by the variable iperiodic in &system. Calculations are achieved in two steps; first the ground state calculation is carried out and then electron dynamics calculations in real time are achieved. Choice of the calculation mode is specified by the variable calc_mode in &calculation. For isolated system, the ground state and the electron dynamics calculations should be carried out in two steps. For periodic system, two calculations should be carried out in one step. Therefore, we prepare three options in the calc_mode, 'GS', 'RT', and 'GS_RT'.

There are about 20 groups of namelists.

name of namelist	description
&units	specify units of input and output files
&calculation	specify the type of calculation, GS (ground state), RT (real-time), and GS-RT (ground state and real time)
&parallel	related to parallelization
&system	system information
&pseudo	specify pseudopotential
&rgrid	parameters related to real space grid
&scf	parameters related to ground state calculation
&hartree	construct Hartree potential
&group_fundamental
&group_file

In Samples, we prepare six samples that cover typical calculations by SALMON. We prepare explanation for the input files that will help to prepare input files of your own interests.