# DFT Dataset: Mg Intercalation into (OH,F)-Substituted Anatase TiO<sub>2</sub> 

<i>Benjamin J. Morgan</i>  
ORCID: [0000-0002-3056-8233](https://orcid.org/0000-0002-3056-8233)

This dataset contains DFT calculation data and analysis codes for calculation of Mg intercalation energies into anion-substituted anatase TiO<sub>2</sub>. More details on these calculations and analysis are given in Ma <i>et al.</i>, <i>Chem. Comm.</i> 2018 (Ref.&nbsp;1). 

## Contents

The top level directories are:
```
|-- stoichiometric
|-- vacancy_intercalation
|-- data
|-- analysis
|-- figures
```

* [`stoichiometric`](./stoichiometric) VASP input and output files for calculations of Mg intercalation into stoichiometric anatase TiO<sub>2</sub>.
* [`vacancy_intercalation`](./vacancy_intercalation) VASP input and output files for calculations of Mg intercalation into anion-substituted anatase TiO<sub>2</sub>.
* [`data`](./data) YAML files containing summaries of the VASP calculation data.
* [`analysis`](./analysis) Jupyter notebook containing calculations of Mg-intercalation energies, with these results plotted as an outputted figure.
* [`figures`](./figures) Figure showing calculated Mg intercalation energies in stoichiometric and anion-substituted anatase TiO<sub>2</sub>.

Each VASP calculation directory contains the following files:
- `INCAR`: VASP master input file.
- `KPOINTS`: VASP k-point input file.
- `POSCAR`: VASP structure input file.
- `POTCAR.spec`: Specification of the pseudopotentials used.
- `OUTCAR`: VASP master output file.
- `vasprun.xml.gz`: Gzipped XML VASP output summary.
- `vasprun.yaml`: Additional metadata describing the calculation.

### `INCAR`, `KPOINTS`, `POSCAR`, `OUTCAR`, `vasprun.xml`
Standard VASP input and output files. Please see the [VASP manual](http://cms.mpi.univie.ac.at/vasp/vasp/vasp.html) for more details.

### `POTCAR.spec`

Each calculation directory contains a `POTCAR.spec` file that specifies the pseudopotentials used
for that calculation.

e.g.
```
Ti_pv PBE_54
```
indicates the `Ti_pv` pseudopotential, from the PBE v.54 has been used.
The `POTCAR.spec` data have been automatically generated using the `potcar_spec` tool in [`vasppy`](https://github.com/bjmorgan/vasppy), which matches the pseudopotentials from a `POTCAR` file via their md5 hash values.

### `vaspmeta.yaml`

Each calculation directory contains a `vaspmeta.yaml` file, that describes additional metadata for that calculation.

e.g.

```
title: stoichiometric anatase
description: >
    stoichiometric anatase TiO2 3x3x1 supercell.
notes: The lattice parameters were generated by fitting volume-constrained geometry optimised structures for a single unit cell, then imposing the correct spacegroup symmetry of the minimum energy-volume structure.
status: finished
```

The `title` entry is used in subsequent processing as a unique identifier for each calculation.

## Data Processing

The data processing and analysis is handled with a [snakemake](https://snakemake.readthedocs.io/en/stable/index.html) workflow. If the necessary Python dependencies have been installed (see below), this can be run with the command
```
snakemake
```
The workflow consists of:
1. The output of the VASP calculations is parsed and collated using the `vasppy` `vasp_summary` script. This produces a YAML file summarising the DFT data: `data/4x4x2_vasp_summary.yaml`.
2. A Jupyter notebook `analysis/intercalation_energies.ipynb` is run. This calculates the Mg intercalation energies, and generates the figure `figures/Mg_intercalation_energies.pdf` (Fig. 2b in Ref.&nbsp;1)
This data analysis uses the elemental reference Mg energy from `data/elemental_reference.yaml`, which is taken from Ref.&nbsp;2.

## Requirements

Python dependencies for the data processing workflow are listed in `requirements.txt`. These can be installed using `pip` with
```
pip install -r requirements.txt
```

The required dependencies are:
```
numpy
pandas
vasppy >= 0.4.0.4
jupyter
version-information
matplotlib
snakemake
pyyaml
nbconvert >= 4.2.0
```

## References

\[1\] J.&nbsp;Ma <i>et al.</i> &ldquo;Controlled Hydroxy-Fluorination Reaction of Anatase to Promote Mg<sup>2+</sup> Mobility in Rechargeable Magnesium Batteries&rdquo; <i>Chem. Comm.</i> 2018.

\[2\] B.&nbsp;J.&nbsp;Morgan &ldquo;DFT dataset: <i>X</i>=(Li,Na,Ca,Mg,Al) Intercalation into (F/OH)-Substituted Anatase TiO<sub>2</sub>&rdquo; [doi:10.15125/BATH-00473](https://dx.doi.org/10.15125/BATH-00473).