%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% READ BEFORE BEGINNING %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Some useful information about AFLOWpi and files needed below.


In each Directory there are three to four files:

1. Input or "Reference" Input file. 
  
   AFLOWpi features three methods to construct calculations. The first uses a "reference" input file
   which is an input file to a calculation engine (currently QE only) with certain parameters replaced
   with AFLOWpi keywords. For Example:

   ATOMIC_SPECIES
   _AFLOWPI_A_   _AFLOWPI_AMASS_  _AFLOWPI_APSEUDO_
   _AFLOWPI_B_   _AFLOWPI_BMASS_  _AFLOWPI_BPSEUDO_
   _AFLOWPI_C1_  _AFLOWPI_C1MASS_ _AFLOWPI_C1PSEUDO_
   _AFLOWPI_C2_  _AFLOWPI_C2MASS_ _AFLOWPI_C2PSEUDO_
   _AFLOWPI_C3_  _AFLOWPI_C3MASS_ _AFLOWPI_C3PSEUDO_
   ATOMIC_POSITIONS {crystal}
   _AFLOWPI_A_  0.0 0.0 0.0
   _AFLOWPI_B_  0.5 0.5 0.5
   _AFLOWPI_C1_ 0.5 0.5 0.0
   _AFLOWPI_C2_ 0.0 0.5 0.5
   _AFLOWPI_C3_ 0.5 0.0 0.5


   Users are free to include additional keywords in an AFLOWpi "reference" input file. Keywords
   with the pattern _AFLOWPI_<A-Z><0-9>_, _AFLOWPI_<A-Z><0-9>MASS_, and _AFLOWPI_<A-Z><0-9>PSEUDO_,  
   are reserved for species labels, atomic masses, and pseudopotential file names. the "scfs" method
   of building a calculation set require those three keywords per atomic species. 

   For instance:

   celldm(1) = _AFLOWPI_D3_    

   would not be allowed but 

   celldm(1) = _AFLOWPI_CELLDM3_ would be fine


   
   The other method used to construct a calculation set is  "from_file" where a list of input file names
   or input file string can be used to construct a calculation set. The list of input files can be any length.
   No keywords are required for this method of constructing a calculation set.


2. AFLOWpi workflow script

   Each AFLOWpi workflow script contains helpful comments to explain what each command is doing.

   In the workflow script, the user tells AFLOWpi to:

   A.) Initiate the framework by specifying the Project name the set name and the AFLOWpi 
       configuration file that is to be used for this AFLOWpi session. (Config files are 
       mostly reusable for different AFLOWpi sessions)
   B.) Build a calculation set using one of the methods available. In the case of the "scfs" method,
       the keywords specifed in the "reference" input file are given one or more value(s). 
   C.) Issue commands that add steps to the workflow on all calculations in the set
   D.) Issue the command to submit the calculations. If on a local environment this means starting
       the first calculation immediately after AFLOWpi has constructed the workflow when the workflow
       script is run via python.

   The examples provided with AFLOWpi are designed to run quickly. Accuracy of results is not the goal
   of these examples (although many will give accurate results)

   Some kind of self-consistent calculation must always come first in any workflow (scf,relax,vc-relax)

   Subsequent steps in a workflow can be any order the user wishes. Note that the order the user specifies
   the workflow is the order it will run. Plotting methods use data from previous steps as such:

   1 calcs.scf()
   2 calcs.dos()     
     calcs.plot.dos()                  #this will plot dos calulated in step #2
   3 calcs.bands()
     calcs.plot.dos()                  #this will plot dos calulated in step #2
     calcs.plot.bands(DOSPlot='APDOS') #this will plot bands from step #3 and APDOS from step #2
   4 calcs.vcrelax()
     calcs.plot.dos()                  #this will plot dos calulated in step #2
     calcs.plot.bands(DOSPlot='APDOS') #this will plot bands from step #3 and APDOS from step #2
   5 calcs.dos() 
     calcs.plot.bands(DOSPlot='APDOS') !!WARNING!! this will plot bands from step #3 and APDOS from step #5 !!WARNING!
     				       !!WARNING!! which may have been calculated with different structure. !!WARNING!
   6 calcs.bands()                               
     calcs.plot.dos()                  #this will plot DOS from step #5
     calcs.plot.opdos()                #this will plot orbital projected DOS from step #5
     calcs.plot.bands()                #this will plot bands from step #6 and APDOS from step #5


   Attention to the order of the workflow is important. calculation sets and their workflow data can be loaded
   After the calculations have finished and figures can be regenerated with different parameters when run with the
   runlocal=True flag in the plotting method. See the example in Intermediate/CHANGE_PLOT/ for details.



3. AFLOWpi configuration file

   The configuration file contains information about the location of files needed to run the calculation:

   A.) The locationexecutables of the calculation engine being used. In the case of Quantum Espresso it
       would be <espresso_dir>/bin/
   B.) The location of the work or scratch directory where the calculations will be run
   C.) The location of the directory where the pseudopotentials to be used are stored. AFLOWpi comes with
       three pseudopotential sets. PBE USPP, PBESOL USPP, and PBE NCPP. These pseudoptentials have been 
       tested throughly and are trusted. That being said they may suitable for your specific system or project
       so as always when doing real science....USE PSEUDOPOTENTIALS WITH CAUTION AND ALWAYS TEST!
   D.) Additional parameters are included in the configuration files. It is encouraged that you take a look
       at them. A full list of available parameters are included in the AFLOWpi release publication:

       PUT PAPER INFO HERE! PUT PAPER INFO HERE! PUT PAPER INFO HERE! PUT PAPER INFO HERE! PUT PAPER INFO HERE!
       PUT PAPER INFO HERE! PUT PAPER INFO HERE! PUT PAPER INFO HERE! PUT PAPER INFO HERE! PUT PAPER INFO HERE!
       PUT PAPER INFO HERE! PUT PAPER INFO HERE! PUT PAPER INFO HERE! PUT PAPER INFO HERE! PUT PAPER INFO HERE!

4. "Reference" cluster submission script (optional)

   This "reference" submission script does not require any special keywords. The file path to this file is specified
   in the AFLOWpi config file. It is the standard cluster submission file for a given cluster system. 
   (currently PBS and SLURM are supported. We are working towards supporting more cluster submission systems.
   If your cluster system is not currently supported you are encouraged to email the developer(s) for assistance)

   When AFLOWpi creates cluster submission files from the "reference" a command to enter the directory for that 
   particular calculation and the command to initiate the calculation are appended to the end of the "reference"
   cluster submission file. 

   In some cases certain parameters (stderr,stdout, and job name) are automatically changed by AFLOWpi. This is
   for organizational purposes.

   If running AFLOWpi locally, this file is not needed.


I recommend at least browsing each of the examples in this "Beginner" directory to get an idea of how to 
use some of the featurs of AFLOWpi and also to familiarize yourself with the 3-4 files that are needed to
run the AFLOWpi framework.