|
|
| Line 1: |
Line 1: |
| − | # SALMON: Scalable Ab-initio Light-Matter simulator for Optics and Nanoscience
| |
| | | | |
| − | SALMON is an open-source software based on first-principles time-dependent density functional theory
| |
| − | to describe optical responses and electron dynamics in matters induced by light electromagnetic fields.
| |
| − |
| |
| − | SALMON has been developed in such a way that it runs optimally in the following supercomputer platforms:
| |
| − |
| |
| − | - K-computer
| |
| − | - Fujitsu FX100 supercomputer system
| |
| − | - Linux PC Cluster with x86-64 CPU
| |
| − | - Linux PC Cluster with Intel Xeon Phi processor
| |
| − |
| |
| − | For more information, please visit our website.
| |
| − |
| |
| − | http://salmon-tddft.jp/
| |
| − |
| |
| − | ## License
| |
| − |
| |
| − | SALMON is available under Apache License version 2.0.
| |
| − |
| |
| − | Copyright 2017 SALMON developers
| |
| − |
| |
| − | Licensed under the Apache License, Version 2.0 (the "License");
| |
| − | you may not use this file except in compliance with the License.
| |
| − | You may obtain a copy of the License at
| |
| − |
| |
| − | http://www.apache.org/licenses/LICENSE-2.0
| |
| − |
| |
| − | Unless required by applicable law or agreed to in writing, software
| |
| − | distributed under the License is distributed on an "AS IS" BASIS,
| |
| − | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
| |
| − | See the License for the specific language governing permissions and
| |
| − | limitations under the License.
| |
| − |
| |
| − |
| |
| − | # Files
| |
| − |
| |
| − | This package is composed of the following files:
| |
| − |
| |
| − | - configure.py
| |
| − | The python script to build SALMON. It uses CMake for the build process, and is the default choice for the build process.
| |
| − |
| |
| − | - CMakeList.txt
| |
| − | CMake script that is used in configure.py.
| |
| − |
| |
| − | - cmakefiles (directory)
| |
| − | CMake related files.
| |
| − |
| |
| − | - examples (directory)
| |
| − | A few sample calculations using SALMON are included.
| |
| − | Detailed explanations of these examples are described in the web site, http://salmon-tddft.jp/wiki/Exercises.
| |
| − |
| |
| − | - LICENCE
| |
| − | License document of SALMON.
| |
| − |
| |
| − | - makefiles
| |
| − | GNU Makefiles to build SALMON.
| |
| − |
| |
| − | - manual
| |
| − | A list of namalist variables that is usable in input files.
| |
| − |
| |
| − | - README.md
| |
| − | This file.
| |
| − |
| |
| − | - src
| |
| − | Source code files of SALMON.
| |
| − |
| |
| − | - testsuites
| |
| − | Files that are used in the automatic test of SALMON.
| |
| − | It can also be used to examine if the build process is successful in the user’s environment.
| |
| − |
| |
| − | - tools
| |
| − | Some tools and utilities related to SALMON.
| |
| − |
| |
| − | # Install and Run
| |
| − |
| |
| − | == Prerequisites ==
| |
| − |
| |
| − | In this guide, it is assumed that readers have a basic knowledge of Unix and its command line operations.
| |
| − | For the installation of SALMON, following packages are required.
| |
| − |
| |
| − | * Fortran90/C compiler. SALMON 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)
| |
| − |
| |
| − | * Build tools.
| |
| − | ** CMake
| |
| − |
| |
| − | If you use other compilers, you may need to change build scripts (CMake). See [[#Additional options in configure.py script]].
| |
| − | If no numerical library is installed on your computer system, you may need to install BLAS/LAPACK by yourself.
| |
| − | See [[Troubleshooting of the Installation Process]].
| |
| − |
| |
| − | For the installation of SALMON, we adopt the CMake tools as the first option.
| |
| − | If there were any problems to use CMake tools in your environment, you may use the GNU make tools.
| |
| − | See [[Troubleshooting of the Installation Process]].
| |
| − |
| |
| − | == Download ==
| |
| − |
| |
| − | The newest version of 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
| |
| − | |- src Source codes
| |
| − | |- example Samples
| |
| − | |- makefiles GNU Makefiles for building
| |
| − | |- cmakefiles CMake related files
| |
| − | |- makefiles GNU Makefiles for building
| |
| − |
| |
| − | == Build ==
| |
| − |
| |
| − | To compile SALMON to create executable the binary files, we adopt to use CMake tools as the first option.
| |
| − | In case you fail to build SALMON using CMake in your environment, we may use Gnu Make. See [[#Build using GNU Makefile]].
| |
| − |
| |
| − | === Checking CMake availability ===
| |
| − |
| |
| − | 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, an error message such as <code>cmake: command not found</code> will appear.
| |
| − | 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 you confirm that CMake of version 3.0.2 or later is installed in your system, proceed to [[#Build using CMake]].
| |
| − | However, we realize that old versions of CMake are installed in many systems.
| |
| − | If CMake is not installed or CMake of older versions is installed in your system, you need to install the new version by yourself.
| |
| − | It is a simple procedure and explained below.
| |
| − |
| |
| − | === Installation of CMake ===
| |
| − |
| |
| − | [https://cmake.org/|CMake CMake] is a cross-platform build tool.
| |
| − | The simplest way to make CMake usable in your environment is to get the binary distribution of CMake from the [https://cmake.org/download/ download page]. The file name of the binary distribution will be <code>cmake-<VERSION>-<PLATFORM>.tar.gz</code>). In standard Unix environment, a file for the platform of Linux x86_64 will be appropriate.
| |
| − |
| |
| − | To download the file, proceed as follows: We assume that you are in the directory that you extracted files from the downloaded file of SALMON,
| |
| − | and that you will use the version 3.8.2. First get the URL of the download link from your browser, and use <code>wget</code> command in your Unix command-line.
| |
| − | <pre>
| |
| − | $ wget https://cmake.org/files/v3.8/cmake-3.8.2-Linux-x86_64.tar.gz
| |
| − | </pre>
| |
| − | Next, unpack the archive by
| |
| − | <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> in your directory.
| |
| − |
| |
| − | To make the <code>cmake</code> command usable in your command-line, you need to modify the environment variable <code>$PATH</code> so that the executable of CMake are settled inside the directory specified in your <code>$PATH</code>.
| |
| − | If you use the bash shell, you need to modify the file <code>~/.bashrc</code> that specifies the <code>$PATH</code> variable. It can be done by typing the following command in your login directory,
| |
| − | <pre>
| |
| − | $ export PATH=<SALMON_INSTALLATION_DIRECTORY>/cmake-3.8.2-Linux-x86_64/bin:$PATH
| |
| − | </pre>
| |
| − | and then reload the configuration by typing:
| |
| − | <pre>
| |
| − | $ source ~/.bashrc
| |
| − | </pre>
| |
| − |
| |
| − | === Build using CMake ===
| |
| − |
| |
| − | Confirming that CMake of version 3.0.2 or later can be usable in your environment, 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=ARCHITECTURE --prefix=../
| |
| − | $ make
| |
| − | $ make install
| |
| − |
| |
| − | In executing the python script, you need to specify ''ARCHITECTURE'' that indicates the architecture of the CPU in your computer system such as ''intel-avx''. The options of the ''ARCHITECUTRE'' are as follows:
| |
| − |
| |
| − | {| class="wikitable"
| |
| − | | 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
| |
| − | |-
| |
| − | | intel-avx512 || Intel Processer (Skylake-SP) || Intel Compiler || Intel MKL
| |
| − | |-
| |
| − | | fujitsu-fx100 || FX100 Supercomputer || 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 architechtures, ''intel-knl'' or ''intel-knc'', you find a file ''salmon.mic'' or both files ''salmon.cpu'' and ''salmon.mic''.
| |
| − |
| |
| − | === Build for single process calculations ===
| |
| − |
| |
| − | In default, the python script assumes parallel execution.
| |
| − | If you use a single processor machine, specify <code>--disable-mpi</code> in executing the python script:
| |
| − |
| |
| − | $ python ../configure.py --arch=<ARCHITECTURE> --disable-mpi
| |
| − |
| |
| − | == 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 ''*.inp*'' that should be read from the standard input ''stdin''.
| |
| − | This file 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 be either 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 the samples prepared in [[Exercises]].
| |
| − | In SALMON, several formats of pseudopotentials may be usable.
| |
| − | Pseudopotentials with an extension ''.fhi'' can be obtained from the website listed below.
| |
| − | (This is a part of previous atomic data files for the ABINIT code.)
| |
| − |
| |
| − | {| class="wikitable"
| |
| − | | pseudopotential || website
| |
| − | |-
| |
| − | | Pseudopotentials for the ABINIT code || https://www.abinit.org/sites/default/files/PrevAtomicData/psp-links/psp-links/lda_fhi
| |
| − | |}
| |
| − |
| |
| − | Filenames of the pseudopotentials should be written in the input file.
| |
| − |
| |
| − | === input file ===
| |
| − |
| |
| − | Input files are composed of several blocks of namelists,
| |
| − |
| |
| − | &namelist1
| |
| − | variable1 = int_value
| |
| − | variable2 = 'char_value'
| |
| − | /
| |
| − | &namelist2
| |
| − | variable1 = real8_value
| |
| − | variable2 = int_value1, int_value2, int_value3
| |
| − | /
| |
| − |
| |
| − | A block of namelists starts with ''&namelist'' line and ends with ''/'' line.
| |
| − | The blocks may appear in any order.
| |
| − |
| |
| − | Between two lines of ''&namelist'' and ''/'', descriptions of variables and their values appear.
| |
| − | Note that many variables have their default values so that it is not necessary to give values for all variables.
| |
| − | Descriptions of the variables may appear at any position if they are between ''&namelist'' and ''/''.
| |
| − |
| |
| − | SALMON describes electron dynamics in systems with both isolated and periodic boundary conditions.
| |
| − | The boundary condition is specified by the variable ''iperiodic'' in the namelist ''&system''.
| |
| − |
| |
| − | Calculations are usually achieved in two steps; first, the ground state calculation is carried out and then electron dynamics calculations in real time is carried out. A choice of the calculation mode is specified by the variable ''calc_mode'' in the namelist ''&calculation''.
| |
| − | For isolated systems, the ground state and the electron dynamics calculations should be carried out as two separate executions.
| |
| − | First the ground state calculation is carried out specifying ''calc_mode = 'GS' ''.
| |
| − | Then the real-time electron dynamics calculation is carried out specifying ''calc_mode = 'RT' ''.
| |
| − | For periodic systems, two calculations should be carried out as a single execution specifying ''calc_mode = 'GS_RT' ''.
| |
| − |
| |
| − | In [[Exercises]], we prepare six exercises that cover typical calculations feasible by SALMON.
| |
| − | We prepare explanations of the input files of the exercises that will help to prepare input files of your own interests.
| |
| − |
| |
| − | There are more than 20 groups of namelists. A complete list of namelist variables is given in the file ''SALMON/manual/input_variables.md''.
| |
| − | Namelist variables that are used in our exercises are explained at [[Input variables]].
| |
| − |
| |
| − | == Run SALMON ==
| |
| − |
| |
| − | Before running SALMON, the following preparations are required as described above: 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. An input file ''inputfile.inp'' and pseudopotential files should also be prepared.
| |
| − |
| |
| − | The execution of the calculation can be done as follows: In single process environment, type the following command:
| |
| − |
| |
| − | $ salmon.cpu < inputfile.inp > fileout.out
| |
| − |
| |
| − | In multiprocess environment in which the command to execute parallel calculations using MPI is ''mpiexec'', type the following command:
| |
| − |
| |
| − | $ mpiexec -n NPROC salmon.cpu < inputfile.inp > fileout.out
| |
| − |
| |
| − | where NPROC is the number of MPI processes that you will use.
| |
| − | In many-core processor (e.g. intel-knl) environment, the execution command is
| |
| − |
| |
| − | $ mpiexec.hydra -n NPROC salmon.mic < inputfile.inp > fileout.out
| |
| − |
| |
| − | The execution command and the job submission procedure depends much on local environment. We summarize general conditions to execute SALMON:
| |
| − |
| |
| − | * SALMON runs in both single-process and multi-process environments using MPI.
| |
| − | * executable files are prepared as ''/salmon/bin/salmon.cpu'' and/or ''/salmon/bin/salmon.mic'' in the standard build procedure.
| |
| − | * to start calculations, ''inputfile.inp'' should be read through ''stdin''.
| |
| − |
| |
| − | = Appendix =
| |
| − |
| |
| − | == Additional options in configure.py script ==
| |
| − |
| |
| − | === Manual specifications of compiler and environment variables ===
| |
| − |
| |
| − | In executing <code>configure.py</code>, you may manually specify compiler and environment variables instead of specifying the architecture, for example:
| |
| − |
| |
| − | $ python ../configure.py FC=mpiifort CC=mpiicc FFLAGS="-xAVX" CFLAGS="-restrict -xAVX"
| |
| − |
| |
| − | The major options of <code>configure.py</code> are as follows:
| |
| − | {| 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
| |
| − | |}
| |
| − |
| |
| − | === Build for single process calculations ===
| |
| − |
| |
| − | If you use a single processor machine, specify <code>--disable-mpi</code> in executing the python script:
| |
| − |
| |
| − | $ python ../configure.py --arch=<ARCHITECTURE> --disable-mpi
| |
| − |
| |
| − | === Build in GCC/GFortran environemnt ===
| |
| − |
| |
| − | If you use GCC/GFortran compiler, specify the following flags in executing the python script:
| |
| − |
| |
| − | $ python ../configure.py FC=gfortran CC=gcc FFLAG=-O3 CFLAG=-O3
| |
| − |
| |
| − | == Build using GNU Makefile ==
| |
| − |
| |
| − | If CMake build fails in your environment, we recommend you to try to use Gnu Make for the build process.
| |
| − | First, enter the directory ''makefiles'':
| |
| − |
| |
| − | $ cd SALMON/makefiles
| |
| − |
| |
| − | In the directory, ''Makefile'' files are prepared for several architectures:
| |
| − | * fujitsu
| |
| − | * gnu
| |
| − | * gnu-without-mpi
| |
| − | * intel
| |
| − | * intel-avx
| |
| − | * intel-avx2
| |
| − | * intel-knc
| |
| − | * intel-knl
| |
| − | * intel-without-mpi
| |
| − |
| |
| − | ''Makefile'' files with <code>-without-mpi</code> indicate that they are for single processor environment.
| |
| − | Choose ''Makefile'' appropriate for your environment, and execute the make command:
| |
| − |
| |
| − | $ make -f Makefile.PLATFORM
| |
| − |
| |
| − | If the make proceeds successful, a binary file is created in the directory <code>SALMON/bin/</code>.
| |
