A bash tool to aid in convergence testing of CASTEP calculations, similar to castepconv but built in bash with plotting and analysis (optionally) in python.

CASTEP Converger is currently in alpha, so comes with no warranty.

Castep_converger needs a working CASTEP binary in order to run single point calculations for the convergence tests, as well as bash running on a Linux system. Python is also used for the post test analysis of the output data file <SEED>_converger.dat, though a users own scripts can be easily used with this data file.

The python script to plot the results requires matplotlib, pandas & numpy. However, python plotting can be ignored in favor of a plotting tool of choice using the space delimited <SEED>_converger.dat file (where first row gives column names).

Some fairly standard bash tools are used internally, namely bc, grep, awk, head, tail & sed (specifically GNU sed, which is standard in most Linux distros).

To use CASTEP converger simply copy castep_converger.sh into a directory on your $PATH or directly into the directory that contains the seed files for the convergence test.

To run CASTEP_converger a directory must contain two seed files <SEED>.cell and <SEED>.param as well as an input file which contains all the parameters. The filename of the input file can optionally be specified with a command line input to castep_converger.sh, if not specified the default of castep_converger.input will be used.

An example input file, castep_converger.inputs, is in the main directory of this repo. This input file contains all parameters set to their default value.

A full example is given in the Example directory, where it is assumed castep_converger.sh has been placed in the same directory or on the $PATH. A full set of inputs for a simple Si cell can be found in Example/Si_inputs. The convergence test can be ran by calling castep_converger.sh from within that directory. This test will run two jobs asynchronously where both are mpi parellised over two cores (based on the parameters set in the castep_converger.inputs file).

An example of the output of this convergence calculation is the files in Examples/Si_outputs, where the python script generated by CASTEP converger (Si_converger.py) can be ran to generate plots of the convergence tests.

The output file Si_converger.dat contains a space delimited data file containing the cutoff energy, kpoint grid and convergence parameters where the first row gives column values. This is used by the python script as a source of data for the plot, but can be used as an input to a plotting program of choice.

The input file can contain various parameters for running convergence testing, most will revert to defaults if not given in the input file however seed and castep_cmd should always be given.

Inputs should be given as KEY = VALUE pairs, where the = is used as the delimiter between the key and value. A # symbol as the FIRST character in the line marks that line as a comment in the input file. Note, partial line comments are not available in the input file, e.g. seed=Si # BAD COMMENT is invalid.

All input options are given with default values in the castep_converger.inputs file in the repo root directory and described below.

Required parameters:

• seed :: The seed for the input .cell and .param files to use as the base of the convergence test.
• castep_cmd :: The command that should be used to call CASTEP for all the runs used in the convergence test. This should be a command that is on the PATH. Examples include:
  • castep_cmd = castep.serial
  • castep_cmd = mpirun --bind-to none -n 6 castep.mpi
  • castep_cmd = srun -n 32 --exclusive --ntasks-per-core=1 --use-min-nodes --distribution=pack --hint=nomultithread
• Depending on the type of calculation being ran cutoff, kpoint and/or fine Gmax parameters will also be required.

Main options to set for the type of run being carried out:

• num_processes :: default 1 :: The number of CASTEP calls to run asynchronously. E.g. if set to 3 then 3 CASTEP converger will attempt to have 3 CASTEP processes running at once, i.e. it will have 3 instances of castep_cmd seed running at all times.
• run_cutoff :: default true :: Run cutoff convergence test by fixing kpoints and fine Gmax and varying cut off energy. If true cutoff parameters must also be given, see later section.
• run_kpoint :: default true :: Run kpoint convergence test by fixing cut off energy and fine Gmax and varying kpoint grid. If true kpoint parameters must also be given, see later section.
• run_fine_gmax :: default true :: Run fine Gmax convergence test by fixing cut off energy and kpoint grid and varying fine Gmax. If true fine Gmax parameters must also be given, see later section.

The following parameters govern exactly what is used as a convergence parameter and what will be output to the final data file and analysed in the generated python script:

• converge_energy :: default true :: Look at the energy per ion in each output file as a convergence parameter.
• converge_force :: default true :: Look at the maximum force on an ion as a convergence parameter.
• converge_stress :: default true :: Look at maximum stress as a convergence parameter.
• converge_collinear_spin :: default false :: Look at the integrated spin densities as a convergence parameter. Can only be used with a collinear spin calculation and with converge_vector_spin = false.
• converge_vector_spin :: default false :: Look at the Euclidean distance between spin vectors over each convergence step as a convergence parameter. Can only be used with a vector spin calculation and with converge_collinear_spin = false.

The following parameters may need to be set depending on preferences and environment:

• reuse :: default false :: If true CASTEP will try and use check files from previous runs as continuation points. This may reduce runtime, but can also cause some issues if convergence is not achieved. This also requires checkfiles to be written for all calculations (which can be quite large).
• default_delete :: default false :: If set to true CASTEP converger will automatically delete any files it finds for non-completed CASTEP calculations in order to re-run. If set to false it will ask before doing so. It could be useful to set this to true if working on a cluster for example, but it could permanently destroy data so use with care.
• supress_excess_files :: default true :: Should any output files from CASTEP other than the .castep file be suppressed (e.g. .check, .geom & .band files etc). This is as we generally do not use them with a convergence test. Warning this cannot be set to false if reuseis set to true.

The following parameters should all be left to true in most cases:

• run_generation :: default true :: Generate files for a convergence test.
• run_castep :: default true :: Run CASTEP to calculate values for a convergence test (from generated inputs).
• run_data_analysis :: default true :: Get data from CASTEP output files generating the output data file and generate python script for easy analysis.

The following parameters only effect the lines showing the desired convergence parameter in the python script used for analysis:

• energy_tol :: default 0.0002 :: The convergence tolerance of energy (per ion) in energy units per ion.
• force_tol :: default 0.05 :: The convergence tolerance of force in force units.
• stress_tol :: default 0.1 :: The convergence tolerance of stress in stress units.

The following are for the bounds that should be used for cutoff convergence tests (N.B. there are no defaults for these parameters):

• cutoff_min :: Minimum cut off energy (in eV) that should be used in the cut off energy convergence test.
• cutoff_max :: Maximum cut off energy (in eV) that should be used in the cut off energy convergence test.
• cutoff_step :: The step size (in eV) of the cut off energy for cut off convergence tests.
• cutoff_kpoint :: The kpoint grid that should be used in all cutoff convergence tests. Should be given as a $k_{x}$ $k_{y}$ $k_{z}$ single space separated list. See below for example.

E.g. if we want to use a 5x5x5 kpoint grid in a cutoff convergence test from 200eV to 500eV in steps of 50eV we would give the parameters

cutoff_min    = 200
cutoff_max    = 500
cutoff_step   = 50
cutoff_kpoint = 5 5 5

The following parameters are used for the kpoint grid convergence tests (N.B. there are no defaults for these parameters):

• kpoint_grid_min :: The smallest kpoint grid used in the convergence test. Should be given as a $k_{x}$ $k_{y}$ $k_{z}$ single space separated list. See below for example.
• kpoint_grid_step :: The number of kpoints to be added to the smallest value in kpoint_grid_min to scale the kpoint grid up. See below for an example.
• kpoint_grid_max :: The maximum value of the smallest element in the kpoint grid to use in the convergence test. See below for an example.
• kpoint_cutoff :: The cutoff energy (in eV) to be used over all kpoint convergence tests.

For example if we set

kpoint_grid_min = 1 2 3
kpoint_grid_step = 2
kpoint_grid_max = 7

Then the kpoint grids 1 2 3, 3 6 9, 5 10 15 and 7 14 21 will be considered by the convergence test. N.B. if required the kpoint value will be rounded up to the nearest integer.

The fine Gmax/fine grid scale parameters that should be used for all kpoint and cut off energy convergence tests can be set with the parameters:

• cut_kpt_fine_Gmax :: default -1 :: A fine Gmax value to use for all cut off and kpoint convergence tests. Setting to -1 ignores this value. Must be set to -1 if cut_kpt_fine_grid_scale is not set to -1.
• cut_kpt_fine_grid_scale :: default 1.75 :: The fine grid scale for the all cut off and kpoint convergence tests. Defaults to 1.75 which is the CASTEP default. Setting to -1 ignores this value. Must be set to -1 if cut_kpt_fine_Gmax is not set to -1.

N.B. if both cut_kpt_fine_Gmax = -1 and cut_kpt_fine_grid_scale then fine Gmax and fine grid scale will be ignored in all convergence tests (just using whatever is in the <SEED>.param file.

To converge the fine Gmax we can either explicitly vary the fine Gmax (as this is the parameter that is transferable to other cells once converged) or vary the fine grid scale (which sets fine Gmax based on the cut off energy). The parameters for fine Gmax/fine grid scale convergence are given below:

• fine_gmax_min :: default -1 :: The minimum fine Gmax (in 1/Ang) to use in Gmax convergence calculation.
• fine_gmax_max :: default -1 :: The maximum fine Gmax (in 1/Ang) to use in Gmax convergence calculation.
• fine_gmax_step :: default -1 :: The step size (in 1/Ang) to use when performing convergence calculation.
• fine_grid_min :: default -1 :: The minimum fine grid scale to use in fine grid scale convergence calculation.
• fine_grid_max :: default -1 :: The maximum fine grid scale to use in fine grid scale convergence calculation.
• fine_grid_step :: default -1 :: The step size of fine grid scale to use in fine grid scale convergence calculation.
• fine_gmax_cutoff :: The cut off energy (in eV) to use over all fine grid scale or fine Gmax convergence calculations.
• fine_gmax_kpoint :: The kpoint grid to use over all fine grid scale or fine Gmax convergence calculations. Should be given as a $k_{x}$ $k_{y}$ $k_{z}$ single space separated list. See below for example.

As only a fine Gmax or fine grid scale convergence test can be ran at once, only one set of parameters should be given with a value that is not -1. For example, to run a fine grid scale convergence steps from a fine grid scale of 2 to 4 in steps of 0.5 using a cut off energy of 400 eV and a 3x3x3 kpoint grid we would give the inputs

fine_gmax_cutoff = 400
fine_gmax_kpoint = 3 3 3
fine_gmax_min = -1
fine_gmax_max = -1
fine_gmax_step = -1
fine_grid_min = 2
fine_grid_max = 4
fine_grid_step = 0.5

Or if we wanted to run a convergence test for fine Gmax from 20 1/Ang to 40 1/Ang in steps of 2.5 1/Ang at a cutoff of 300 eV and 4x4x4 kpoint grid we would give the inputs

fine_gmax_cutoff = 300
fine_gmax_kpoint = 4 4 4
fine_gmax_min = 20
fine_gmax_max = 40
fine_gmax_step = 2.5
fine_grid_min = -1
fine_grid_max = -1
fine_grid_step = -1