Getting started#
AiiDA is a sophisticated framework with great ability to prepare, submit, manage calculations and preserve their provenance. The workflow of running lengthy, complex density functional theory calculations on clusters can be automated and simplified.
I would strongly encourage any user to familiarize themselves with AiiDA before using this plugin, otherwise a lot of things would not make sense.
The aiida_core
package has good documentation located at readthedocs.
The user should also be familiar with running CASTEP manually using file interface.
Tutorials for CASTEP can be found at http://www.castep.org/CASTEP/OnlineTutorials.
Installation#
We will skip the guide for installation of AiiDA here.
Please refer to their documentation to install aiida_core
and all the dependencies.
The easiest way to try out this plugin is perhaps to use Quantum Mobile - a virtual machines based on Ubuntu Linux and shipped with AiiDA installed and ready to use.
Note
The latest version (2.x.x) of aiida-castep
only works with aiida_core
version 2.x.x.
Please make sure the right version is installed. Also, you are most likely to need to work
within a virtual environment (including conda environments).
To install from the Python Package Index (PyPI):
pip install aiida-castep
This will install the latest package released with its dependencies.
Alternatively, to clone the repository from the repository:
git clone git@github.com:zhubonan/aiida-castep.git
Then pip can be used to install the plugin:
pip install -e <path_to_this_plugin>
This way the entrypoints can be properly registered to allow aiida_core
discover the plugin.
The optional -e
flag makes the installation editable.
If aiida_core
is not installed, it will be installed as a dependency.
You should be able to see several calculations registered as castep.<name>
using AiiDA’s command-line interface:
verdi plugin list aiida.calculations
the results should look like:
Registered entry points for aiida.calculations:
* arithmetic.add
* castep.castep
* castep.ts
* templatereplacer
Generate CASTEP help information#
This plugin will check for mistakes in parameters supplied to CASTEP and automatically
write the keyword-value pair to the correct input file.
A dictionary containing all keywords and where they should be is used internally and stored
as a json file on the disk.
Although a pre-generated file is included, you may want generate one for the lastest
version of CASTEP.
The json file should be stored as $HOME/.castep_help_info_<version>.json
.
To generate the file, use command:
verdi data castep-helper generate
By default, castep.serial
executable will be used of it is available in PATH
..
This can be overridden using optional argument -e <path_to_executable>
.
For details, refer to the internal help using the --help
flag.
Stored help information can be accessed using this interface as well,
imitating the behavior of castep.serial -h
and castep.serial -s
.
Note
The CASTEP executable is not a perquisite other than for generating the help dictionary. But if you do have one on the local computer, dryrun tests can done locally to further test the inputs and retrieved number of k-points required and estimate memory usage.
Test the plugin#
Tests for the plugin is written using pytest
so all you need to do is type:
pytest aiida_castep
from the project’s root directory.
Note
Of course this needs pytest
to be installed. This can be done by pip install aiida-castep[testing]
.
You may also need to (re)install aiida with pip install aiida_core[testing]
.
Using the plugin#
Within the AiiDA framework a calculation is performed by playing a CalcJob
process.
A number of nodes are passed to the process as the input.
The provenance of the calculation is stored as a CalcJobNode
which links to the input and output nodes.
For a typical CASTEP calculation, like most density functional theory calculations, needs the following inputs:
A
Dict
node withPARAM
andCELL
fields. Each fields is a dictionary define the keys goes into the param and cell files.A
KpointsData
node defines the kpoints. Both explicit kpoints and kpoints grid are supported.A
StructureData
node define the atomic structure for calculation.Nodes that defines the pseudo potential. An shortcut
use_pseudos_from_family
function may be called to simplify the process once the structure is known. The pseudopotentials can be any combination ofOTFGData
,UspData
,UpfData
nodes.An optional
Dict
node with link namesettings
can be supplied to defines extra properties such as initial spins and use of symbolic link in restart calculations.
The simply the process, a ProcessBuilder
instance can be used to define the inputs under interactive python shell.
Finally, the calculation can be submitted by the aiida.engine.submit
or the aiida.engine.run_get_node
function.
Generated input files#
Some meta data are included as comments in the input cell and param files. This includes the generation time, AiiDA user, pk, uuid, label and description of the calculation node and input nodes used. All keywords are written in lower case. In addition, the following keys are set automatically:
iprint is set to 1 by default. iprint = 2 may work but not fully tested yet.
If not set explicitly, comment will be set as the label of the calculation node to keep things tracked.
run_time will be set to 95% of the requested wall-time by default unless it will be less than 180 seconds. This is to avoid running out of time while writing the checkpoint file. CASTEP does try to be intelligent and stop if it thinks the next iteration (geometry optimisation, phonons e.t.c) will exceed the time limit. To completely disable time limit control, set it to 0 explicitly in
Dict
node.Consistency of spins are checked. Keyword spin in
<seed>.param
will be set automatically, if not already defined, using the initial spins set for<seed>.cell
file.