CRYSTAL17 - How to install The package CRYSTAL17 consists of two programs: - crystal computes the energy, analytical gradient and wave function for a given geometry, which can also be fully optimized. It also computes a number of energy-based and response quantities, such as vibrational frequencies and spectra, dielectric response, … - properties computes one electron properties (electrostatic potential, charge density, ...) analyses the wave function in direct and reciprocal space transforms the Bloch functions (BF) into Wannier functions (localization of BF) and much more… CRYSTAL can run in three different modes: crystal sequential execution Pcrystal replicated data parallel execution MPPcrystal distributed data parallel execution The following instructions mainly refer to crystal (i.e. sequential execution) but also some information is given about parallel execution and to the use of provided scripts (runcry17, runprop17, runmpi17, runmpi_prop17). properties can read wf information computed by crystal unformatted (file fort.9) or formatted (file fort.98). Formatted data written in file fort.98 can be moved from one platform to another. Conventions used in the following: "ARCH" string to identify the operating system and/or the compiler (Linux-gfortran, Linux-ifort, MacOsX) "VERSION" string to identify the crystal version (now v1.0.1) d12 extension of file meant to be input to crystal d3 extension of file meant to be input to properties INSTALLATION ON UNIX/LINUX SYSTEMS Installation instructions are given for UNIX/Linux operating systems. Examples are in C shell. 0. log in as a generic user, and cd to your home directory 1. make the crystal root directory - it is called $CRY2K17_ROOT in the following 2. change directory to $CRY2K17_ROOT 3. After having got the user and passwd, point your browser to: http://www.crystalsolutions.eu/ Login and then download the executable suitable for your architecture (the name of the files may change, crystal17_v1_0_x, if minor modifications are introduced) Examples: crystal17_v1_0_2_Linux-ifort17_XE_openmpi-2.1_emt64.exe.tar.gz crystal17_v1_0_2_MacOsx-ifort17_exe.tar.gz 4. decompress the files: gunzip crystal17_v1_0_2_Linux-ifort17_XE_openmpi-2.1_emt64.exe.tar.gz gunzip crystal17_v1_0_2_MacOsx-ifort17_exe.tar.gz should now have: crystal17_v1_0_2_Linux-ifort17_XE_openmpi-2.1_emt64.exe.tar crystal17_v1_0_2_MacOsx-ifort17_exe.tar 5. untar the files (a complete subtree will be created having the CRYSTAL17 directory as a root): tar -xvf crystal17_v1_0_2_Linux-ifort17_XE_openmpi-2.1_emt64.exe.tar tar -xvf crystal17_v1_0_2_MacOsx-ifort17_exe.tar 6. The directory bin contains a sub-directory for each type of executable, identified by a string (ARCH), and for each release (the first one being v1.0.1). Type the command: ls -l -R The result should be: ./bin: total 8 drwxr-xr-x 3 cry98 crygrp 4146 Mar 11 15:39 Linux-ifort17_XE_openmpi-2.1_emt64/ drwxr-xr-x 3 cry98 crygrp 4096 Mar 11 15:40 MacOsX-ifort17/ ./bin/Linux-ifort17_XE_openmpi-2.1_emt64: total 4 drwxr-xr-x 2 cry98 crygrp 4096 Mar 9 16:50 v1_0_2/ ./bin/Linux-ifort17_XE_openmpi-2.1_emt64/v1_0_2: total 26192 -rwxr-xr-x 1 cry98 crygrp 9744178 Mar 9 16:45 crystal* -rwxr-xr-x 1 cry98 crygrp 10896205 Mar 9 16:50 Pcrystal* -rwxr-xr-x 1 cry98 crygrp 6129715 Mar 9 16:46 properties* -rwxr-xr-x 1 cry98 crygrp 6129715 Mar 9 16:46 Pproperties* ./bin/MacOsX-ifort17: total 4 drwxr-xr-x 2 cry98 crygrp 4096 Mar 11 12:57 v1_0_2/ ./bin/MacOsX-ifort17/v1_0_2: total 15440 -rwxr-xr-x 1 cry98 crygrp 9745360 Mar 11 12:56 crystal* -rwxr-xr-x 1 cry98 crygrp 6031424 Mar 11 12:57 properties* ********** Points 7. and 8. below refer to the CrGra2006 visualization package CRYSPLOT is a newer, web-oriented visualization tool that has similar capabilities as crgra2006, but is easier to use and suggested for CRYSTAL17 users. It doesn’t need any installation, and can be used directly from the web browser by accessing to http://crysplot.crystalsolutions.eu If you don’t want to install CrGra2006 you can skip the two next items. ********* 7. Installation of the package CRGRA2006 (Not necessary to install and run CRYSTAL17) The package for visualization of bands, doss, maps, from the data written in file fort.25 by the program properties can be downloaded from http://www.crystal.unito.it/crgra2006/crgra2006.html No modifications to read CRYSTAL17 data. A standard postscript visualizer, called by the command gv, is assumed to be installed on the machine. 8. type the commands: gunzip Crgra2006.tar.gz tar -xvf Crgra2006.tar ls -l -R Crgra2006 The result of the last command is: band06* script to draw bands band.con* example of control file to draw bands doss06* script to draw density of states (doss) doss.con* example of control file to draw doss maps06* script to draw contourline maps maps.con* example of control file to draw maps mptparam.dat data to draw atoms on the maps defps.dat* data to draw atoms on the maps multi.maps* example of control file to draw difference maps multi.con example of control file to draw difference maps bin/Linux-ifort directory - contain executables doc/ directory - contain Crgra2006.pdf, User' manual src/ directory - contain fortran source files SETTING OF ENVIRONMENTAL VARIABLE AND SHELL SCRIPTS Testing instructions are given for UNIX/Linux operating systems. Examples are in C shell. 1. Point your browser to : http://www.crystal.unito.it/utils/utils17.zip and download the file into the CRYSTAL root directory, $CRY2K17_ROOT 2. decompress and untar the file: gunzip utils17.tar.gz tar -xvf utils17.tar type the command: ls utils17 the result is the list of shell: runcry17 C shell script to run crystal [and properties] runmpi17 template to prepare a script to run Pcrystal runprop17 C shell script to run properties runmpi_prop17 template to prepare a script to run Pproperties cry2k17.cshrc C shell to define CRYSTAL17 environmental variables cry2k17.bashrc bash to define CRYSTAL17 environmental variables cd to utils17 directory, if needed make executable all scripts by typing chmod +x run* 3. From now on, the example is for C shell. If bash is your default shell please refer to cry2k17.bashrc file Backup the cry2k17.cshrc file by copying as cry2k17.old.cshrc Edit the cry2k17.cshrc shell to define the local value of the environmental variables: variable name meaning name used in the example CRY2K17_ROOT CRYSTAL17 root directory CRYSTAL17 CRY2K17_ARCH ARCH string to identify the executable Linux-ifort17_XE_openmpi-2.1_emt64 CRY2K17_SCRDIR temporary directory for scratch files $HOME 4. [copy the file cry2k17.cshrc to the user home directory], and type the command: source cry2k17.cshrc 5. for a permanent setting of CRYSTAL17 environmental variables and path, insert in .cshrc (or .bashrc) the line: source cry2k17.cshrc (or source cry2k17.bashrc) TESTING OF CRYSTAL17 ON UNIX/LINUX SYSTEMS In order to run crystal and properties all previous steps should have been taken successfully. 1. From the root directory of CRYSTAL17, $CRY2K17_ROOT, type the command: ls to check your installation. The result should be: bin/ directory with executables utils17/ direcyory with utilities Crgra2006/ directory with graphic package 2. make the directory test_cases and move into it 3. download input test cases from: http://www.crystal.unito.it/test_cases/inputs_wf.tar.gz For tests on geometry optimization and vibrational frequencies calculation see the CRYSTAL tutorials home page: http://www.crystal.unito.it/tutorials/index.html or move to http://www.crystal.unito.it ==> documentation ==> test cases and download input files. 4. decompress and untar the files: gunzip *.gz tar -xvf inputs.......tar. From the directory $CRY2K17_ROOT/test_cases type the command: ls -F you should find the following directories: inputs/ directory with CRYSTAL17 inputs to crystal (*.d12) and properties (*.d3) 5. Starting from the root directory of the crystal program, the suggested directory tree, used in the execution scripts runcry17 and runprop17 has the following structure: crystal_root -----bin---ARCH1----VERSION1----crystal[,Pcrystal] | | properties[,Pproperties] | ARCH2----VERSION1----crystal[,Pproperties] | properties test_cases---inputs--- test01.d12 | | test02.d12 | | ......... | |---outputs---ARCH1----VERSION1---test01.out | | | | test02.out | | | | . . . . . | | | VERSION2 --test01.out | | | test02.out | | | . . . . . | | |---ARCH2---VERSION1---test01.out | | | | test02.out | | | | . . . . . | | | VERSION2---test01.out | | | test02.out | | | . . . . . | | |--- . . . . | | |test_opt |---inputs ---test1.d12 | | | |---outputs ---ARCH1----VERSION1---test01.out | | | | test02.out | | | | . . . . . | | |---ARCH2----VERSION1---test01.out | | | |test_freq|---inputs . . . . | | | |---outputs . . . . | | | |test_xxxx|---inputs . . . . | | | |---outputs . . . . . . . . . . .. . . . utils17—— cry2k17.cshrc | cry2k17.bashrc | runcry17 | runprop17 | runmpi17 | runmpi_prop17 Crgra2006---- 6. Serial execution using scripts to test the program with the test cases input supplied, make from $CRY2K17_ROOT the directory test: mkdir test_first In order for crystal and properties to read input file from the test dataset you should set these two variables: setenv CRY2K17_INP "$CRY2K17_ROOT/test_cases/inputs" setenv CRY2K17_PROP "$CRY2K17_ROOT/test_cases/inputs" or (bash) export CRY2K17_INP=$CRY2K17_ROOT/test_cases/inputs export CRY2K17_PROP=$CRY2K17_ROOT/test_cases/inputs If you do not set the two variables, input and output are supposed to be into the current directory. Test11 is MgO bulk, and provides also data for the properties program. Bands, Density of states, charge density maps are also computed and visualize, assuming there is a postscript visualizer "gv" to run test11, bulk MgO, type: runcry17 test11 The program crystal and properties are executed. In the current directory the following files will be written: test11.out standard output (crystal+properties) test11.f9 unformatted wf data (written by crystal) test11.f98 formatted wf data (written by crystal) [ if Crgra2006 was installed: test11.band06.ps postscript file - bands test11.doss06.ps postscript file - doss test11.maps06.ps postscript file - charge density map] To check the execution, issue the command to find the string "GY(HF" (see CRYSTAL17 User's Manual, Appendix, "Relevant Strings"): grep "GY(HF" test11.out the correct answer should be: TOTAL ENERGY(HF)(AU)( 7) -2.7466419186124E+02 DE-3.1E-09 tst 2.9E-10 PX 2.5E-04 That string contains the total energy/cell of bulk MgO. 7. Parallel execution using scripts Crystal provides two scripts, runmpi17 and runmpi_prop17, useful for the parallel execution of the Pcrystal and Pproperties executables, respectively. If your system adopts a queue system, like pbs, you might need to write a specific script for the queueing system. Nevertheless, these scripts can be useful as a guide. Only a few parts might need customisation in the runmpi17 and runmpi_prop17 scripts. Let us see in detail the case of runmpi17, runmpi_prop17 works in a completely analogous way. The first point to be inspected can be found around line 180: set MPIDIR = /opt/openmpi-1.6.3/bin set MPIBIN = mpirun here the user must point to the specific MPI library (that can be also mpich, impi, …) installed on his/her system. This generally has to be the same distribution and version used to build the executables (be it the distributed executable or the one compiled in loco from the precompiled objects). The “Job launching line”: ${MPIDIR}/${MPIBIN} -machinefile $CRY17P_MACH/machines.LINUX -np $NPROCS $TMPDIR/Pcrystal < $TMPDIR/INPUT >>& $OUTDIR/$OUTFILE that is found around line 420 of the script, does not generally need to be customised but the user might have to do it, according to specific MPI installations. The next step is to provide two files, situated in the directory defined by the $CRY17P_MACH environment variable, which contain the list of nodes involved. The first, called machines.LINUX (if the name has to be changed, it must be changed also in the command line above) contains the list of computing nodes where the job will run. According to the specific dialect of the used MPI implementation, additional options (such as the maximum number of cores per node to be used) can be provided. In the case when the scratch disk is not shared among nodes, the nodes.par file must contain a similar list as above, plus the hostname of the launching node (if the launching node is not a computing node). This file is used by the script to create temporary directories in all the nodes and copy via ssh (scp command) the needed files (input, executables, restart units, wavefunction, output units) to and from the launching directory and the scratch directories on the nodes. Note that permissions to create such directory and access it must be granted on all nodes included the launching node. If the system features shared a disk, then the nodes.par file can contain only one line.