updated the xc workshop tutorial

docs/workshop/07_xc.md

@@ -2,36 +2,36 @@
 
 ## Introduction
 
-These exercises are intended to introduce you to some of the XC functionals available in CASTEP. They will show you how to choose and set up calculations using these  functionals. They will also demonstrate the effect of chosen functional upon different physical properties. 
+These exercises are intended to introduce you to some of the XC functionals available in CASTEP. They will show you how to choose and set up calculations using these functionals. They will also demonstrate the effect of chosen functional upon different physical properties. 
 
 It is important to remember throughout that no XC functional is perfect (as discussed in the XC functional talk). In choosing a functional, we must be guided by an understanding of the XC functional itself and the physics of the system under consideration. It is also important to realise that sometimes ''inappropriate functionals get the 'right' answer for the wrong reasons!'' Some of these exercises will further illustrate this point.
 
 Many of the post-LDA functionals (HF, sX-LDA) are computationally intensive. For that reason, this practical session focusses upon small systems. However, by the end of this session you should be able to set up more complex and demanding systems. 
 
 ### Where To Find Help
  If you want more information about a particular CASTEP keyword, or you want to find if CASTEP has particular functionality, there are a few places you can look.
-There is information on this website: [www.castep.org]( http://www.castep.org).
+There is information on this website under [documentation](../documentation/Getting_Started/intro.md) or you can use the search bar at the top of the page.
 CASTEP has an in built help option to assist with using particular keywords.  Information on using CASTEP can be seen by using: 
 
 ``` 
-$ castep -help 
+$ castep -h
 ```
-To get more information on a particular input file keyword (e.g. `kpoint_mp_grid`) use:
+To get more information on a particular input file keyword (e.g. `kpoints_mp_grid`) use:
 
 ```
-$ castep -help kpoint_mp_grid
+$ castep -h kpoints_mp_grid
 ```
 
 If you don't know the keyword you need to use, then you can search on a particular keyword. This returns a list of keywords that you might be interested in, e.g. to look at all keywords which contain a reference to symmetry.
 
 ```
-$ castep -help search symmetry
+$ castep -s symmetry
 ```
 
 Finally, to list all keywords, use:
 
 ```
-$ castep -help search all
+$ castep -h all
 ```
 
 ## Example 1 - Si: LDA and GGA
@@ -40,9 +40,10 @@ In this first exercise, we shall explore how to use different XC functionals to
 
 1. Get the files required for this exercise : [Si2 files](Si2.tar.gz)
 
-	We shall carry out these calculations on arcus. Transfer the files to arcus, and unzip and untar them. You can use:
+	We shall carry out these calculations on the VM. Copy the files from the `/course_materials` directory to somewhere in your home directory and then unpack them. You can use:
 
 	```
+	cp /course_materials/Si2.tar.gz .
 	tar -xvf Si2.tar.gz
 	```
 
@@ -54,14 +55,14 @@ Amend this to say:
 	spectral_task   bandstructure
 	```
 
-3. We can also choose the XC functional that we wish to employ in the param file. If we set 
+1. We can also choose the XC functional that we wish to employ in the param file. If we set 
 
 	```
 	xc_functional : lda
 	```
 	then we will run a calculation using the LDA. This is the functional that will be employed in the SCF calculation that determines the ground state electronic density.  If we do not specify otherwise, then it will also be used for the band structure calculation. 
 
-4.  Now we shall examine the `.cell` file. Open `Si2.cell`. Later in this tutorial, we shall use non-local functionals. In CASTEP, non-local functionals can only be used with norm-conserving pseudo potentials. (Question: Do you understand as to why this should be so? Ask if you do not.) For this reason, ensure that you are using the norm-conserving pseudo potential library by including:
+2.  Now we shall examine the `.cell` file. Open `Si2.cell`. Later in this tutorial, we shall use non-local functionals. In CASTEP, non-local functionals can only be used with norm-conserving pseudo potentials. (Question: Do you understand as to why this should be so? Ask if you do not.) For this reason, ensure that you are using the norm-conserving pseudo potential library by including:
 
 	```
 	%block species_pot
@@ -70,7 +71,7 @@ Amend this to say:
 	```
 	in your `.cell` file.
  
-5. We will also need to set up an appropriate k-point path for the band structure calculation. We will use the following path:
+3. We will also need to set up an appropriate k-point path for the band structure calculation. We will use the following path:
 
 	```
 	%block spectral_kpoint_path
@@ -83,24 +84,24 @@ Amend this to say:
 	```
 	Add this block to the `.cell` file.
 
-6. Ensure that your calculation is converged with respect to both kinetic energy cut-off and k-point sampling. 
+4. Ensure that your calculation is converged with respect to both kinetic energy cut-off and k-point sampling. 
 
-7. Now run CASTEP on arcus using the 2-atom input files.
+5. Now run CASTEP on the VM using the 2-atom input files.
 	
 	```
-	$ castepsub -n Number Si2 
+	$ mpirun -n Number castep.mpi Si2 
 	```
-	where `Number` should be replaced by the number of processors that you wish to use.
+	where `Number` should be replaced by the number of processors that you wish to use (up to a maximum of 16).
 
 	This should only take a few seconds and produce a readable output file `Si2.castep`. Examine this file and try to understand the meaning of the various parts. In particular check the section following the header which lists all of the input parameters, both explicit and default. Note what default values of the major parameters CASTEP chose where you did not specify them explicitly. (There will be some whose meaning has not been explained. Don't worry about these.) Note down how long the calculation takes for each k-point.
 
 	We will now analyse the band structure. We can produce a plot of this from the Si2.bands file using:
 		
 	```
-	dispersion.pl -xg -bs Si2.bands
+	dispersion.pl -xg -np -bs Si2.bands | xmgrace -
 	```
 
-8. Using the band structure plot, determine the band gap. How does this compare to the experimental value? Can you explain this?
+6. Using the band structure plot, determine the band gap. How does this compare to the experimental value? Can you explain this?
 
 	I recommend that you save the output from this calculation as Si2_lda or similar as later on we wish to compare with GGA and non-local calculations.
 
@@ -133,7 +134,7 @@ We shall now move onto examining what happens with a non-local functional. In pr
 3. Add the following line to the .param file:
 
 	```
-	bs_xc_functional : HF
+	spectral_xc_functional : HF
 	```
 
 	This allows us to specify a different functional for the band structure calculation, which in this case will be a Hartree-Fock calculation. However, we are using a  LDA-derived ground state density to feed into this calculation.
@@ -147,21 +148,25 @@ We shall now move onto examining what happens with a non-local functional. In pr
 6. Repeat steps 1-5, but for screened exchange with LDA correlation (sX-LDA). To do this, in Step 3 set 
 
 	```
-	bs_xc_functional : sX-lda
+	spectral_xc_functional : sX-lda
 	```
 ## Example 3 - FeO and DFT+U
 
 In the XC Functional talk, data were shown illustrating the effect of functional upon the electronic structure of antiferromagnetic FeO. In this example you will learn how to perform DFT+U calculations. 
 
-1. Get the files required for this exercise : [FeO Files](FeO.tar.gz)
+1. Get the files required for this exercise : [FeO Files](FeO.tgz)
  
-	We shall carry out these calculations on arcus. Transfer the files to arcus, and unzip and untar them. 
+	We shall carry out these calculations on the VM. Copy the files from the `/course_materials/FeO` folder to somewhere in your home directory. For example:
+
+	```
+	cp -r /course_materials/FeO .
+	``` 
 
 2. Open the `.cell` file. We are interested in examining an anti-ferromagnetic structure. Note the following in the block where the atomic positions are specified:
 	
 	```
-	Fe 0.0 0.0 0.0 spin=-4.0
-	Fe 0.0 0.0 0.0 spin=4.0
+	Fe 0.0  0.0  0.0 spin=-4.0
+	Fe 1.5 -0.5 -0.5 spin=4.0
 	```
 	This specifies the initial antiferromagnetic spin arrangement, with `spin = `$N_\text{up}-N_\text{down}$ defining the initial spin polarisation on each Fe atom.
 
@@ -188,11 +193,11 @@ In the XC Functional talk, data were shown illustrating the effect of functional
 	```
 5. We will set the XC functional to be the PBE flavour of GGA (`xc_functional : pbe`).  
 
-5. Now run a band structure calculation and produce a band structure plot as before. 
+6. Now run a band structure calculation and produce a band structure plot as before. 
 
 	There are certain features of the band structure plot that you should understand: the dispersive bands are ''sp'' bands derived from ''s'' and ''p'' electrons. The flat non-dispersive bands are derived from Fe ''d'' electrons. Can you explain why the ''d'' bands are so flat?
 
-6. When examining magnetic systems, it is also often useful to examine the spin on each atom. This information can be found in the .castep file in the section 
+7. When examining magnetic systems, it is also often useful to examine the spin on each atom. This information can be found in the .castep file in the section 
 	
 	```
 	Atomic Populations (Mulliken)
@@ -209,7 +214,7 @@ In the XC Functional talk, data were shown illustrating the effect of functional
 	Fe 2 d: 2.5 
 	%endblock hubbard_u
 	```
-	This specifies a Hubbard U parameter of 2.5 eV for each Fe ion in the system. Whilst schemes exist to determine the value of U from first principles, in CASTEP it is simply specified as a parameter. Of course, one could use *ab initio* calculations to determine a value of U *then* specify this in the `.cell` file. 
+	This specifies a Hubbard U parameter of 2.5 eV for each Fe ion in the system. Whilst schemes exist to determine the value of U from first principles, in CASTEP it is simply specified as a parameter. Of course, one could use *ab initio* calculations to determine a value of U *then* specify this in the `.cell` file. Beware, however, of using a value of U value determined for one XC functional or one DFT code with another as they are not transferable between methods.
 
 8. Run a band structure calculation and plot the results. How does this band structure compare to the PBE+U result? Can you explain which features change and which stay the same? What happens to the band gap?
 
@@ -223,7 +228,12 @@ Graphite represents a prototypical example of a layered system in which the laye
 
 1. Get the files required for this exercise : [Graphite files](Graphite.tar.gz)
  
-	As before, we shall carry out these calculations on arcus. Transfer the files to arcus, and unzip and untar them. 
+	As before, we shall carry out these calculations on the VMs. Copy the files from the `/course_materials` directory to somewhere in your home directory and then unpack them. You can use:
+	
+	```
+	cp /course_materials/Graphite.tar.gz .
+	tar -xvf Graphite.tar.gz
+	```
 
 2. Open the `.param` file using a text editor. We will do our first calculation with the PBE GGA functional. Ensure that this is the xc functional specified (see above if you cannot recall how to do this).
 
@@ -273,9 +283,11 @@ Graphite represents a prototypical example of a layered system in which the laye
 
 14. Repeat 10-13 but using the D4 correction scheme. How do the results change?
 
-NOTE1: the TS scheme is not particularly suitable for such a small unit cell, as the code will warn you. The results should therefore be treated with caution. 
+<!-- NOTE1: the TS scheme is not particularly suitable for such a small unit cell, as the code will warn you. The results should therefore be treated with caution.  [I think this is fixed from CASTEP 24 onwards]-->
+
+NOTE: the OBS scheme is not compatible with the PBE functional.
 
-NOTE2: the OBS scheme is not compatible with the PBE functional.
+You can also compare your findings to the other tutorial here on [DFT+D](../tutorials/dispersion_corrections/castep-ase-dispersion-tutorial.md) where the layers of graphite are separated. The Jupyter notebook provided there can also be used on the VMs as an alternative to running CASTEP manually.
 
 ## Further examples