====== Exercise 0 ======

In this exercise you will learn how to use the bash terminal, to do a __minimal__ installation of CP2K, which will be used to perform the molecular dynamics simulations, and to install a few useful programs required to analyse the simulations.

<note tip>
First of all, you have to make sure that your Windows or Mac machine has the packages required to install CP2K and other software that will be used.
\\
If your machine is running a Mac OS X, you will need to install XQuartz and XCode.
\\
If instead it is running on Windows you will need to install Cygwin.
</note>

===== 0.1a Installation of Cygwin on Windows =====

If your machine is running windows you will need to install Cygwin. [[http://www.cygwin.com|Cygwin]] is a large collection of GNU and Open Source tools which provides functionality similar to a Linux distribution on Windows.\\

For 32 bit Windows execute  [[http://cygwin.com/setup-x86.exe|setup_x86.exe]] and follow the rest of directions in the wizard.

For 64 bit Windows [[http://cygwin.com/setup-x86_64.exe|setup_x86_64.exe]] can be used.\\

When installing Cygwin make sure you install the following additional packages:\\
  *Devel
    *“bison”
    *“byacc”
    *“gcc-fortran”
    *“gcc-g++”
    *“make”
  *Libs 
      *“lapack”
      *“liblapack-devel”
      *“liblapack0”
  *Python
  *Vim\\
Please operate according to the wizard to finish the Cygwin installation.\\

===== 0.1b Installation of XCode and XQuartz  on Mac OSX =====

If you are running on a Mac OS X you need to install XCode and XQuartz.

Download and install [[https://www.xquartz.org/|XQuartz]] unless you already have it on your machine.

Also, you need to install XCode from the apple store or from the following link: [[https://developer.apple.com/xcode/|XCode]].


===== 0.2 Using the terminal =====

Throughout this course you will need to use the terminal or command line. Below there's a list of basic commands that you will need to use. Spend some time to become familiar with them. If you have a Mac open the Apple terminal, whereas if you are running Windows, start Cygwin.

Let's start with a list of useful commands that you need to use in the terminal environment -- just type them into the command line and confirm with ''RETURN''.
<code bash>
ls             # get list of files in the current directory
mkdir MD_course   # make directory 'MD_course'
cd             # change into your home directory
cd MD_course      # change into directory 'MD_course'
cd ..          # go up one directory
pwd            # print path to the current working directory

</code>

Below you find a command that will open a file using a text editor called vim. You will need to edit input files throughout the course in order to run MD simulations with CP2K. You can use any text editor, vim is one of them. Other text editors, which may be simpler to use, are [[https://atom.io/|Atom]] (plus the [[https://atom.io/packages/line-ending-selector-unix|line-ending-selector-unix]] plugin) or [[https://notepad-plus-plus.org/|Notepad++]]. 

In this simple example, we will open a new file with ''vim'', write some text, save and close this file. On the terminal type:

<code bash>
vim myfile      # opens 'myfile' in vim
</code>

Type ''i'' to go to insert mode, then insert some text.
Now go to normal mode by typing ''ESC''. In normal mode you can save and quit a file by typing '':wq''.
Now copy ''myfile'' to the ''MD_course'' directory using the ''cp'' command. To do this type:

<code bash>
cp myfile MD_course
</code>


===== 0.2a CP2K Installation on Windows =====

Download CP2K using git command or from [[https://github.com/cp2k/cp2k.git | github website]]:\\
<code>
git clone --recursive https://github.com/cp2k/cp2k.git cp2k
</code>

After downloading using git or extract the zip file from [[https://github.com/cp2k/cp2k.git | CP2K-github]] you will find it in the directory ''cp2k''.

In order to compile cp2k one has to specify an arch file to indicate which compilers and libraries to use.
Change directory to ''cp2k/arch''. Once you are in this directory open a new file called ''Cygwin-i686-gfortran.sopt''

Copy the following lines and paste into the newly opened ''Cygwin-i686-gfortran.sopt'' file:\\
<file>
CC       = cc
CPP      = 

FC       = gfortran
LD       = gfortran

AR       = ar -r

CPPFLAGS = 
DFLAGS   = -D__GFORTRAN -D__FFTSG
FCFLAGS  = -g -O2 -funroll-loops -ftree-vectorize -march=native -ffree-form $(DFLAGS) 
LDFLAGS  = $(FCFLAGS) 
LIBS     = -llapack -lblas

OBJECTS_ARCHITECTURE = machine_gfortran.o
</file>
Save this file (again if you use vim type ''ESC'' and then ':wq').\\
Run the ''make'' command as follows in order to compile cp2k:\\
<code>
make ARCH=Cygwin-i686-gfortran VERSION=sopt
</code>

If you find ''cp2k.sopt'' in ''cp2k/exe'' directory, then compilation is successfully done.
===== 0.2b CP2K Installation on Mac OS X =====

Download CP2K using git command or from [[https://github.com/cp2k/cp2k.git | github website]]:\\
<code>
git clone --recursive https://github.com/cp2k/cp2k.git cp2k
</code>


After the code you will find it in the directory ''cp2k''.

In order to compile cp2k one has to specify an arch file to indicate which compilers and libraries to use.
Change directory to ''cp2k/arch''. Once you are in this directory open a new file called ''Darwin-IntelMacintosh-gfortran.sopt'', copy and paste the following lines into this file.

<file>
CC       = gcc
CPP      =
FC       = gfortran
LD       = gfortran
AR       = ar -r
RANLIB   = ranlib
DFLAGS   = -D__NO_STATM_ACCESS -D__ACCELERATE
FCFLAGS  = -O2 -funroll-loops \
           -ftree-vectorize -ffree-form $(DFLAGS)
LDFLAGS  = $(FCFLAGS)
LIBS     = -framework Accelerate

</file>
Save it as ''Darwin-IntelMacintosh-gfortran.sopt'' in the ''cp2k/arch'' directory alongside the other ARCH files.\\
Launch the Terminal and change the working directory to ''cp2k/Makefiles''. Type make command as follows:\\
<code>
make ARCH=Darwin-IntelMacintosh-gfortran VERSION=sopt
</code>
It may take quite a while until a compilation is completed. 
 
If you find ''cp2k.sopt'' in ''cp2k/exe'' directory, then compilation is successfully done.

===== 0.3 First CP2K simulation =====
It is possible to run cp2k from any directory on your own machine by adding a line to your ''.bashrc'' file, without having to specify the location of the ''cp2k.sopt'' file. 

To do this change to the directory where the ''cp2k.sopt'' binary is located and type ''pwd''. Copy the output of this command and edit the ''.bashrc'' file located on your home directory:
To edit the ''.bashrc'' file type
<code>
vim ~/.bashrc
</code>
Add the following line, replacing ''/path_of_cp2k_binary/'' with the actual path where ''cp2k.sopt'' is located.
<code>
export PATH=${PATH}:/path_of_cp2k_binary/
</code>
Save the ''.bashrc'' file and quit. You can do this by typing '':wq'' in normal mode if you use vim.
In the terminal after typing 
<code>
source ~/.bashrc
</code>
you can run cp2k from any directory. To do this enter
<code>
cp2k.sopt --help
</code>

Which should give you the output

<code>
 cp2k.sopt [-c|--check] [-e|--echo] [-h|--help] [--html-manual]
           [-i] <input_file>
           [-mpi-mapping|--mpi-mapping] <method>
           [-o] <output_file>
           [-r|-run] [--xml]

 starts the CP2K program, see <https://www.cp2k.org/>

 The easiest way is cp2k.sopt <input_file>

 The following options can be used:

  -i <input_file>   : provides an input file name, if it is the last
                      argument, the -i flag is not needed
  -o <output_file>  : provides an output file name [default: screen]

 These switches skip the simulation, unless [-r|-run] is specified:

  --check, -c       : performs a syntax check of the <input_file>
  --echo, -e        : echos the <input_file>, and make all defaults explicit
                      The input is also checked, but only a failure is reported
  --help, -h        : writes this message
  --html-manual     : writes a HTML reference manual of the CP2K input
                      in the current directory. The file index.html is a good
                      starting point for browsing
  --license         : prints the CP2K license
  --mpi-mapping     : applies a given MPI reordering to CP2K
  --run, -r         : forces a CP2K run regardless of other specified flags
  --version, -v     : prints the CP2K version and the SVN revision number
  --xml             : dumps the whole CP2K input structure as a XML file
                      xml2htm generates a HTML manual from this XML file
</code>

Now, make a new directory, for instance called ''exercise0''. Download and extract the file {{argon.zip|}} into this directory and run cp2k by typing
<code>
cp2k.sopt -i argon.inp -o out_ex0.out
</code>
You just ran a short Molecular Dynamics trajectory of liquid argon. 


===== 0.4 Visualization with VMD =====

We will visualize this trajectory with VMD, a molecular visualization program. First of all, download and install VMD for your operating system as indicated [[http://www.ks.uiuc.edu/Development/Download/download.cgi?PackageName=VMD|here]].

Open VMD. From ''File -> New molecule...'' open the file with the ''.xyz'' extension. Go to ''Graphics -> Representations..'' and change the Drawing Method to VDW. On the VMD shell type the following commands to define the unit cell of the system and wrap the atoms back to their original unit cell.
<code>
pbc set {17.158 17.158 17.158} -all
pbc box
pbc wrap -all
</code>

A snapshot of the molecular dynamics trajectory should approximately look like this:

{{:exercises:2018_uzh_acpc2:argon_liq_first_sim.png?400 |}}


===== 0.5 Plotting tools =====

Throughout the course you will also need to plot some graphs. You can use any tool you like for that. ''gnuplot'' and ''Xmgrace'' are two programmes often used in Linux environments that are rather easy to use, but you can also use ''MS Office'', ''Numbers'', the plotting library of python ''Matplotlib'', etc. Take care to install any of these software on your machine as needed.