README.srt

AFM_plot
========

Having the spectroscopies of a AFM in a set of directories called
'grid_point_X' containing all the POSCAR.nn, CONTCAR,nn and OUTCAR,nn files, 
recursively gathers the information to generate the plots EvsZ, FvsZ, Delta_W
vs Z and generates the geoemetry .xyz file of every spectroscopy, ready to be
opened with Jmol (as coment line is  a Jmols script).

execute the script as: 

AFM_plot.py (input_file(s))

input_file(s) is(are) optional. If not given, the script will look for the
default 'inp.afm' file in the folder. If it does not exist will use the parameters
by default.  More than one input file can be given in order to provide the inputs
in batches, but if the same keyword is given more than once in the diferent
input_files, the one at the very end will override the previous ones. So the
order in which the input files are given matters.

INPUT: inp.afm containing any of the input keywords
OUTPUT: 

Keywords for the inp.afm file:
------------------------------

Mandatory keywords
..................
- grid_points <int> <int> <int> ... ::  Number of the grid points to be plotted

Optional keywords
.................
- smoothing <float> (default = 0.0001) :: Spline smoothinf factor

- z_min <float> (default = 10 ) :: minimum z value to do the E fitting

- z_max <float> (default = 100) :: maximum z value to do the E fitting

- omega_exp <float> (default = -5) :: Delta omega used to generate the whole image

- datfile <str> (default = 'Evsz.dat') :: Data filename wich includes E vs Z
  data values OUTCAR.X names

- tip_name <str> (default = 'AFM tip') :: Name of the tip

- tip_length <float> (default = 6.0 ) :: Distance between the apex and the most upper fixed tip atom

- surface_length <float> (default = 6.0 ) :: Distance between the bottom and the top atoms of the surface

- add_labels <bool> (default = False)  ::  If to add labels to the graphs 

- label_interval <int> (default = 5)   :: Add label every 'label_interval' steps

- prefix <str> (default = 'wip') ::  Prefix for every output plot

- show_graphs <bool>   (default = True):: If to show the graphs of each grid
  point before saving them. Here z and smoothing can be tweaked to compute the
  forces and delta omega in the desired intervals

- save_graphs <bool>   (default = True):: If to save the graphs of each grid point

- only_forces <bool> (default = False) ::  Only will show the forces 

- do_full_image <bool> (default = True):: If to compute the full AFM image. It
  does not mean it will be shown unless show_afmimage keyword is set to True as
  well

- show_afmimage <bool> (default = True)::  If to show the final AFM image before saving it 

- save_afmimage <bool> (default = True)::  If to save the final AFM image

- save_forces <bool> (default = False)::  If to save the forces of each grid
  point in a text file

- autosave <bool> (default = True)::  If to save along the way the fitting
  parameters. Also checks if a previous autosaved file exists, and if so uses
  it.

- force_initial <bool> (default = False) :: If True will force to use the inial
  z_min, z_max, and smoothing values even when an existing autosaved file
  exist. But fitting values will be saved at the end if autosaved is True

- include_retractions <bool> (default = True) :: The script will look for ret_
  folders in each grid_point_X folder and will extract the energies and
  calculate the forces at each retraction

- overwrite <bool> (default = False) :: Even when <outdatfile> is present, it will overwrite it and
  extract the E vs Z from the OUTCARs. Useful to recalculate Z or update E vs Z files when new
  calculations are present

NOTE: Booleans can be given as [(True, yes, 1...) | (False, no, 0...)]