Caesar; a utility for calculating the vibrational free energy of periodic crystals

Caesar calculates the vibrational free energy, and a number of related vibrational properties, of periodic crystals.

Purpose of Module

Caesar is intended to provide a vibrational method which is more accurate than the widely-used harmonic approximation [Hoja_ea] and the more sophisticated effective harmonic approximation [Errea_ea], but which is computationally inexpensive enough to be integrated into high-throughput workflows.

Caesar can calculate vibrational properties using several vibrational methods. The Caesar Harmonic Calculation Library performs calculations under the harmonic approximation [Hoja_ea]. The Caesar Anharmonic Calculation Library performs calculations under the vibrational self-consistent harmonic approximation (VSCHA) [Errea_ea] or using vibrational self-consistent field theory (VSCF) [Christiansen].

In order to perform vibrational calculations, Caesar must interface with an electronic structure code. A wide range of electronic structure codes can be used, via the Caesar electronic structure interface.

[Hoja_ea](1, 2) First-principles modelling of molecular crystals: structures and stabilities, temperature and pressure. https://doi.org/10.1002/wcms.1294
[Errea_ea](1, 2) Anharmonic free energies and phonon dispersions from the stochastic self-consistent harmomic approximation: Application to platinum and palladium hydrides. https://doi.org/10.1103/PhysRevB.89.064302
[Christiansen]Vibrational structure theory: new vibrational wave function methods for calculation of anharmonic vibrational energies and vibrational contributions to molecular properties. https://doi.org/10.1039/B618764A

Building and Testing

The details of how to build and testing Caesar are given in the Caesar README.txt file.

Details of how the documentation and unit tests were written are presented in Caesar - Documentation and Testing.

Compilation

An out-of-source build is recommended. For this, a clean build directory should be made, and then CMake and Make should be run from the build directory, e.g. as

mkdir build
cd build
cmake [options] path_to_src
make

where [options] are the desired CMake configuration options, and path_to_src is the path to the caesar/src directory.

Caesar has been tested using version 10.1 of the gfortran compiler.

Dependencies

Caesar requires the spglib crystal symmetry library. CMake will search LIB for spglib’s lib directory, and will search PATH for spglib’s include directory.

Caesar also requires the BLAS and LAPACK linear algebra libraries. These are located using CMake’s FindLAPACK utility, which searches a range of standard install locations and can be configured using additional CMake configuration options.

These dependencies can be suppressed by setting the CMake options LINK_TO_SPGLIB and LINK_TO_LAPACK to false, although this will disable many of Caesar’s features.

Documentation and Helptext

The software documentation for Caesar can be generated using Ford. This should be generated in the doc directory, by calling

ford caesar.md

Documentation will be generated in the doc/ford directory, and doc/ford/index.html can be viewed by using an html reader (e.g. a web browser).

Caesar also has its own helptext system, which can be accessed through the caesar executable by calling caesar --help. This system includes helptext for each of the modes in which Caesar can be called, including details of the input settings for each mode.

Unit Tests

The unit tests for Caesar are generated using pFUnit. When building with tests, pFUnit becomes a dependency of Caesar, and CMake will search PATH for pFUnit’s bin directory.

Unit tests can be run by calling

ctest

from the build directory where CMake was run.

Unit tests are built by default, but can be suppressed by setting the CMake option ENABLE_TESTS to false.

Output Visualisation

Caesar uses python scripts to visualise output data. These can be run using Caesar, or can be run directly. When Caesar is built, the python scripts will be written to the python directory within the build directory.

Performing Calculations

Caesar is a command line utility. The behaviour of Caesar can be controlled using command line options, a configuration file, interactive input, or a combination of these. Detailed usage information can be obtained by calling

caesar --help

Source Code

The source code for Caesar is available from the Caesar repository