******
CASTEP
******

.. py:class:: CASTEP

This interface supports energy and gradient evaluations with the
`CASTEP <http://www.castep.org/>`_ electronic structure package
(version 23.1.1 or later)

A CASTEP :ref:`Theory <theories>` object can be specified as follows::

  my_frag = Fragment(...)

  my_theory = CASTEP(frag=my_frag,
                   functional='lda',
                   ...)

which would then be called as ``theory=my_theory`` in subsequent tasks 
(see :ref:`Tasks <tasks>`).

General options
===============

.. py:attribute:: basis_de_dloge
   
   (default: 0.0)  Derivative of total energy with respect to the natural log of the basis cutoff energy.

   used only if finite_basis_corr : 1  (manual)

   Allowed types of value:

   * A python :py:class:`str` specifying the :py:class:`float` value of the correction and [an optional] unit.

   for example: ``basis_de_dloge='-1.2345 eV'``


.. py:attribute:: basis_precision

   (default: ``'FINE'``) Level of convergence of atomic energies with respect to the plane wave cutoff energy.

   Allowed types of value:

   * A Python :py:class:`str`.  One of: ``'COARSE'``, ``'MEDIUM'``, ``'FINE'``, ``'PRECISE```, ``'EXTREME'``


.. py:attribute:: cut_off_energy

   (default: ``'125 eV'``) Cutoff energy for the plane wave basis sets.

   Allowed types of value:

   * A Python :py:class:`str` value of the energy with [an optional] unit, for example: ``cut_off_energy='500 ha'``


.. py:attribute:: elec_convergence_win

   (default: ``'2'``) The size of the convergence window during a linear response to electric field calculation.

   The linear response convergence criteria must be met for EFIELD_CONVERGENCE_WIN iterations before acceptance.
   
   Allowed types of value:

   * A Python :py:class:`str` or :py:class:`int` value, for example: ``elec_convergence_win=5`` or ``elec_convergence_win='5'``

.. py:attribute:: elec_energy_tol
    
   (default: ``'10e-05 eV'``)  Tolerance for accepting convergence of the total energy in an electronic minimization 
   
    Allowed types of value:
    
    A Python :py:class:`str` value specifying a :py:class:`float` value with [an optional] unit, for example: ``elec_energy_tol='10e-06 eV'``

.. py:attribute:: electronic_minimizer

   Method used to minimize electronic states. 
   
   (default: ``CG``)

   Available options are: ``'SD'``, ``'CG'``

.. py:attribute:: finite_basis_corr
    
   (default: 2) Specifies whether or not to apply a finite basis set correction to energy and stress when cell parameters change.

   Allowed values are:

   ``0`` - no correction, 

   ``1`` - manual correction using ``basis_de_dloge`` 

   ``2`` - automatic correction using ```finite_basis_npoints``` and ```finite_basis_spacing```

.. py:attribute:: finite_basis_npoints

   (default: ``3``) Number of points used to estimate the BASIS_DE_DLOGE in automatic calculation of the finite basis set correction.

   Only used if finite_basis_corr : 2. Integer values are allowed.

.. py:attribute:: finite_basis_spacing

  (default: ``5.0 eV``) : Spacing of cutoff energies used to estimate the BASIS_DE_DLOGE in automatic calculation of the finite basis set correction.

   only used if finite_basis_corr : 2.

   Allowed types of values:

   A Python :py:class:`str` value specifying a :py:class:`float` value with [an optional] unit, for example: ``'10.0 eV'``

.. py:attribute:: fix_occupancy

   (default: ``True``) Specifies whether or not the occupancies of the bands remain fixed.

.. py:attribute:: grid_scale

   (default: ``2``) Size of the standard grid, relative to the diameter of the cutoff sphere.

   Allowed types of values:
  
   A Python :py:class:`float` or :py:class:`str` specifying the float value. for example: ```'2.0'```

.. py:attribute:: maxiter

   (default: 60) Equivalent to max_scf_cycles.  Maximum number of SCF cycles performed in an electronic minimization.
  
   Any integer value is allowed. For example: ```maxiter=20``` or ```maxiter='20'```

.. py:attribute:: metals_method

   (default: ``EDFT``) Determines the electronic minimization method used in the self-consistent calculation.

   Allowed values are ``DM``, ``EDFT``, ``NONE``

.. py:attribute:: mixing_scheme

   (default: ``Broyden``) The mixing scheme used in the density mixing procedure
 
   Allowed values are

   ``Kerker``, ``Linear``, ``Broyden``, ``Pulay``

.. py:attribute:: nbands

   Maximum number of bands at any k-point and spin.

   Allowed types of value: Integer

.. py:attribute:: num_dump_cycles

   (default ``0`` -  no data will be written )

   Number of SCF cycles between updates to the wavefunction and density data file

   Allowed types of value: Integer.

.. py:attribute:: opt_strategy

   (default ``default`` -  Best balance between performance and memory usage)

   Optimization strategy used. 

   Allowed values are ``Speed``, ``Default``, ``Memory``.

.. py:attribute:: input

   (default: ``('_castep.cell', '_castep.param')`` List containing names of CASTEP input files

.. py:attribute:: output

   (default: ``'_castep.out'``) Name of CASTEP output file

.. py:attribute:: pseudopotential

   (default: Default pseudopotential generated on the fly by CASTEP) 

   Input for the CASTEP input ``species_pot``, the data block containing the names of the pseudopotential files associated with each species

   Allowed Types of value:

   A Python :py:class:`str` which specifies either:  

   *  One of the allowed keywords  ```QC5, HARD, MS, C7, C8, C9, NCP9, C17, NCP17, C18, NCP18, C19, NCP19, SOC19, NCP``` . The keyword chooses definition   of the pseudopotential which is to be generated at runtime.

   or:

   *  A comma separated list of the pseudopotential files to be used for each element. Filenames should be in the format ``element_filename``

   For example:  ```pseudopotential= 'H_pseudo.usp, O_pseudo.usp' ``` . If any element is not specified, it is assigned the default value.

.. py:attribute:: rand_seed

   (default: ``0``) Controls the initialization of random number seeds.

   Allowed type of value: integer

   *  If ``0`` is used, the seed for random number generation is selected pseudorandomly.

   * Any other integer value is used as seed for the random number generator.

.. py:attribute:: smearing_width


   (default: ``'300 K'``) width of the Fermi-surface smearing if the system is being treated as a metal

   Allowed type of value:

   A Python :py:class:`str` which specifies a :py:class:`float` value with [an optional] unit: for example, ``smearing_width='275.4 K'``


.. py:attribute:: write_checkpoint

   (default: ``None``) Write periodic backup 
 
   A Python :py:class:`str` :

  ``None``, ``MINIMAL``, ``BOTH``, ``ALL``, ``FULL``

.. py:attribute:: write_formatted_density

   (default: ``False``)  Whether the final electron density is written to an ASCII file called seedname.den_fmt