Welcome to QM-Thermodynamics’s documentation!

Ab initio calculation of an equation of state and thermodynamics of minerals

Thermodynamic properties, equation of state (3th or 4th-order Birch-Murnaghan EoS) and thermal expansion of crystal phases can be computed, along with their temperature and pressure dependence, by using the code here described, starting from data calculated at the ab initio quantum-mechanical (QM) level, which are essentially static energies (internal energies) and vibrational frequencies as functions of the unit cell volume.

Ab initio data are processed within the general framework of Statistical Thermodynamics, within the limit of the quasi-harmonic approximation (QHA).

Properties like:

  • bulk modulus, its pressure derivative and its thermal dependence;

  • thermal expansion and its temperature dependence;

  • specific heat (at constant pressure) and its temperature dependences;

  • entropy at the reference state (T=298.15K, P=1 bar)

can be computed from QM data, and can then be used to evaluate the Gibbs free energy at any temperature and pressure, by following algorithms equivalent to those implemented in the Perplex package .

Equilibria between mineral species (only end-members can be considered) can be evaluated starting from the thermodynamic data thus derived. Here is an example where the equilibrium between kyanite and andalusite has been determined in a P/T field: thermodynamics data for kyanite are computed at the QM level, whereas those for andalusite are from literature (Holland & Powell )

_images/react.png

All of the properties are computed by constructing the Helmholtz free energy [F(V,T)] as a function of volume (V) and temperature (T). At any given T, F is fitted in a V range by a 3^order volume-integrated Birch-Murnaghan EoS (V-BM3). Results of the fitting are then used to compute all the possibles properties derivable from F.

The program can be loaded and run in a normal Python console as well as in any other environment like Spyder

_images/spyderimage.svg

Jupyter Notebooks or Jupyter Labs are convenient environments, too.

Other than the local PC, Jupyter Notebooks can also be viewed by using the viewer by inserting the location of the book; see the example here .

Once the notebook has been loaded in nbviewer, by clicking on the Execute on Binder button an image is created on the Binder site and the notebook is executed (though it may require some minutes to build the image and run it on the server).

Information about the input required to run the program can be found in the EoS tutorial , as well as in the sections Input file and required files on this site.

The github repository of the package can be found here .

The input files used in the EoS tutorial refer to the example on pyrope and can be found on Github . The notebook of such tutorial can also be view here , on the nbviewer site and, from there, compiled and interactively used on Binder (click on the Execute on Binder icon).

Input file

Structure of the input file (input.txt)

The input file can contain blank lines or commented # characters that are ignored. Its structure is keyword oriented. Keywords can be inserted in any order and must be followed by the parameters they specify. The input is key sensitive.

List of keywords:

  • ALPHA (optional): powers of a polynomial for the fitting of thermal expansion as a function of T

  • ANH (optional): input for anharmonic calculation (see the tutorial)

  • CP (optional): powers of a polynomial for the fitting of specific heat (at P constant) as a function of T

  • DISP (optional): input for phonon dispersion correction (see the tutorial)

  • END (mandatory): end of keywords list

  • EXCLUDE (optional): specifies a list of modes to be excluded from the computation of the free energy

  • EXP (optional): file name of experimental Cp and S data from the literature, for comparison with computed results

  • FITVOL (optional): fitting of the frequencies in a given V range and use of the fitted values in the calculation of F free energy

  • FREQ (mandatory): file name of the frequencies data set

  • FU (mandatory): number of formula units in the primitive cell, and number of atoms in the formula unit

  • INI (optional): initial parameters for the fit of a volume integrated 3° order Birch-Murnaghan EoS to the F free energy(volume) data

  • KIEF (optional): input for the modified Kieffer model

  • LO (optional): file name of the LO-TO splitting data

  • NZP (optional): zero point energy is not explictly computed (because it is already added to the static contribution)

  • SET (mandatory): set of volumes/frequencies to be used in the calculation (a list of integers indexing the file specified by the VOLUME keyword)

  • STATIC (mandatory): file name of static energy curve (volumes and static internal energy of the crystal)

  • PSTATIC (optional): file name of the static pressures (volumes and static pressures) followed by the value of the static energy at the equilibrium static volume

  • TEMP (optional): set of temperature for the output of a PVT file to be used with the EoSFit program

  • VOLUME (mandatory): file name of the volumes corresponding to the frequencies in the FREQ file

Below, an example of input file is shown

—————– input.txt file ———————

# STATIC: file of the E(V) static energy curve
# VOLUME: file with the set of volumes for which the frequencies were calculated
# END: closes the input list
# EXP: file with experimental data
# FITVOL: type of fit (SPLINE POLY), range of volume, number of V points and degree of the
#                 spline or polynomial fit of the frequencies, and smoothness* parameter for the spline
# FREQ: file with the sets of frequencies (one set for each volume)
# LO: file with the modes affected by LO-TO splitting
# FU: number of formula units in the (primitive) cell
# SET: set of volumes to be used in the calculation (list of integers)
# TEMP: temperature list (for EoSFit)
# INI: initial parameters for the EoS
# CP powers for the polynomial fit of Cp(T)
# ALPHA: Powers for the polynomial fit of alpha(T) (fixed pressure)
# DISP: Phonon dispersion correction from a supercell calculation
# ANH: Anharmonic correction
# DISP Dispersion correction

STATIC
pyrope_static.dat
VOLUME
volume.dat
FREQ
pyrope_freq.dat
LO
LO.txt
EXP
experimental.txt
FITVOL
SPLINE
725. 768. 16 3 10
EXCLUDE
88 36
FU
4 20
SET
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
# TEMP
# 40 50 60 70 80 90 100 120 150 170 180 200 230 260 300 350 400 500
INI
755 170. 5 -1.1418e+04
CP
0. 1. -2. 2. -0.5 -1. -3. 3.
ALPHA
0. 1. -1. -2. -0.5
END

———————— End of file ——————-

Files Required

Several files must be provided to the program. They must all be contained in a data subfolder whose name should be specified as an input datum when the program is started (see the read_file function).

Mandatory files:

  1. A volume* v.s. *static energy file: this file contains only two columns; the first one lists unit cell volumes (in A^3); the second one lists static energies (in a.u.). The name of this file must be written in the Input file under the STATIC keyword

  2. A volume file listing the unit cell volumes (in A^3) at which vibrational frequencies of the normal modes were computed. The name of this file must be written in the Input file, under the VOLUME keyword

  3. A frequencies file: it consists of several columns and, precisely, one for each volume listed in the volume file; each column lists the set of frequencies computed at each volume. Frequencies must be given in cm^-1. The name of this file must be written in the Input file, under the FREQ keyword. Note that the first column of the frequencies file must contains the degeneracy of each vibrational mode (an integer number in the interval 1-3)

  4. An input.txt file containing instructions and parameters for the execution of the program.

Optional files:

  1. A file containing data for the LO-TO splitting: it is required to activate a correction for the LO-TO splitting. The name of the such file must be provided under the keyword LO in the Input file. Such LO file must contains two columns: the first one contains the progressive number of the modes affected by LO-TO splitting (the numbering follows the same order of the modes found in the frequencies file); the second column contains the corresponding split values (in cm^-1)

  2. A file containing experimental data of specific heat and entropy, to be used for comparisons with computed results (by the function compare_exp). The name of this file must be written in the Input file, under the EXP keyword

  3. Files for the phonon dispersion correction (see the tutorial)

  4. Files for the anharmonic correction (see the tutorial)

  5. A quick_start.txt file in the master folder. This file contains the name of the folder of the data to be processed. If this file exists, the program immediately proceeds to read the relevant data files, without having to issue the read_file and the static commands

  6. A static pressures file. The file must contain a list of unit cell volumes (in A^3) and the corrisponding static pressures (in GPa). The name of this file must be written in the Input file under the PSTATIC keyword. Note that, with this keyword, the name of the file must be followed by the static energy value at the equilibrium unit cell volume.

Note:

A special parame.py mandatory file must be always present in the master folder. It contains several parameters for the execution of some functions of the program, which could possibly be modified by expert users and developers only.

Main Features and more advanced calculations

Main Features

Anharmonic correction

Phonon dispersion

Tutorials

This section is based on the use of jupyter notebooks; notebooks offers a particularly convenient environment to run the code in interactive sessions that can be saved as html or pdf files

Basic EoS

Thermodynamics

Dealing with the frequencies

Determining temperatures from frequencies

LO-TO splitting correction

Anharmonic correction

Phonon dispersion

Updates

03/03/2021 (Extrapolation of Cv at the Debye limit)

02/07/2021 (Static EoS)

03/09/2021 (Thermal expansion I)

27/10/2021 (Thermal expansion II)

Version

The current version of the program is the v2.8.0 (2022, October 12)

Citation

The program can be cited as

Mauro-Prencipe. (2022, October 12). Mauro-Prencipe/QM-thermodynamics: QmTh-v2.8.0-alpha (Version 2.8.0). Zenodo. https://doi.org/10.5281/zenodo.6821531

Contacts

Author:

Mauro Prencipe

Contact:

mauro.prencipe@unito.it

Address:

Depth. of Earth’s Science, University of Torino

Via Valperga Caluso 35, 10125 Torino - Italy

Download

The current version of the software can be downloaded from the Github repository

https://zenodo.org/badge/DOI/10.5281/zenodo.6821531.svg