From bd82e077a2da5654b2a011766059ab4b488ebfc0 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Mon, 16 Mar 2026 13:32:54 -0700 Subject: [PATCH 01/10] Revise README structure and content Updated README.md to improve clarity and organization of content. --- README.md | 39 +++++++-------------------------------- 1 file changed, 7 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index dcfaf070..54c1bbbf 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,11 @@ [![GitHub Actions](https://github.com/PhasesResearchLab/dfttk/actions/workflows/test.yaml/badge.svg)](https://github.com/PhasesResearchLab/dfttk/actions/workflows/test.yaml) [![Documentation Status](https://readthedocs.org/projects/dfttk/badge/?version=main)](https://www.dfttk.org/en/main/?badge=main) -## 📝 Overview +## Overview The **Density Functional Theory Toolkit (DFTTK)** is a Python package designed to automate VASP jobs and manage relevant results in MongoDB. VASP workflows leverage [Custodian](https://github.com/materialsproject/custodian), and data storage is handled via [PyMongo](https://github.com/mongodb/mongo-python-driver). -## 🔧 What does DFTTK do? +## Key Features ### Enumeration of Configurations - Enumerates **unique collinear magnetic configurations** for a given structure. @@ -24,7 +24,7 @@ The **Density Functional Theory Toolkit (DFTTK)** is a Python package designed t ### MongoDB Storage - Stores and retrieves VASP **input data** and **post-processed results** in MongoDB. -## ⚙️ Installation +## Installation It is recommended first to set up a virtual environment using Conda: conda create -n dfttk python=3.12 @@ -43,43 +43,18 @@ Or clone a specific branch: cd dfttk pip install -e . -> 🛠️ **Note:** A PyPI release is currently under development. +> **Note:** A PyPI release is currently under development. -## 📖 Documentation +## Documentation For a comprehensive description of **DFTTK** and its capabilities, please refer to the [Official Documentation](https://vasp-job-automation.readthedocs.io/en/latest/index.html). -> 🛠️ **Note:** The documentation is currently under construction. Some sections may be incomplete or subject to change. +> **Note:** The documentation is currently under construction. Some sections may be incomplete or subject to change. -## 📚 Citing DFTTK +## Citing DFTTK If you use **DFTTK** in your work, please cite the following publication: > **N. Hew et al.**, > *Density Functional Theory ToolKit (DFTTK) to automate first-principles thermodynamics via the quasiharmonic approximation*, **Computational Materials Science**, Volume 258, 2025, 114072, ISSN 0927-0256. > [https://doi.org/10.1016/j.commatsci.2025.114072](https://doi.org/10.1016/j.commatsci.2025.114072) ([View on ScienceDirect](https://www.sciencedirect.com/science/article/pii/S092702562500415X)) - -## 🤝 Contributing - -We welcome bug reports, feature suggestions, and pull requests! - -### Getting Started -1. Fork and clone the repo: - - git clone https://github.com//dfttk.git - -2. Create a new branch: - - git checkout -b my-feature - -3. Make changes, commit, push, and open a pull request to `main`. - -### 🐛 Reporting Issues -Found a bug or have a suggestion? -Please open an issue at [GitHub Issues](https://github.com/PhasesResearchLab/dfttk/issues) with: -- A clear description -- Steps to reproduce (if applicable) -- Logs or screenshots - -> Thanks for helping improve **DFTTK**! - From 89d358cd37fe8fabdba7689cca50afecadbcd00a Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Tue, 17 Mar 2026 11:49:52 -0700 Subject: [PATCH 02/10] Revise README with enhanced project overview Updated README to include additional context and features of DFTTK. --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 54c1bbbf..4e4d9276 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,9 @@ [![Documentation Status](https://readthedocs.org/projects/dfttk/badge/?version=main)](https://www.dfttk.org/en/main/?badge=main) ## Overview +Over the years, many tools have been developed to help set up and/or automate DFT calculations with VASP, as well as provide various post-processing features, such as [atomate2](https://github.com/materialsproject/atomate2), [quacc](https://github.com/Quantum-Accelerators/quacc), [AFLOW](https://www.aflowlib.org/), [AiiDA](https://www.aiida.net/), [pyiron](https://pyiron.org/), and [VASPkit](https://vaspkit.com/). The **Density Functional Theory ToolKit (DFTTK)** is another addition to this space, with a philosophy of keeping the interface between the user and VASP as minimal as possible and making the automation and post-processing steps easy to see and understand. -The **Density Functional Theory Toolkit (DFTTK)** is a Python package designed to automate VASP jobs and manage relevant results in MongoDB. VASP workflows leverage [Custodian](https://github.com/materialsproject/custodian), and data storage is handled via [PyMongo](https://github.com/mongodb/mongo-python-driver). +**DFTTK** workflows use [Custodian](https://github.com/materialsproject/custodian) for job management. The usefulness of Custodian is that it allows many VASP jobs to be chained together and includes various self-correction strategies for handling VASP errors. Key features are listed below. ## Key Features From 5e1454ae2a56e60ac6b9263fe19fa8ab88d380e5 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Tue, 17 Mar 2026 11:52:26 -0700 Subject: [PATCH 03/10] Restore and format README content Restored README content with proper formatting and additional details. --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4e4d9276..ada26a8e 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,9 @@ ## Overview Over the years, many tools have been developed to help set up and/or automate DFT calculations with VASP, as well as provide various post-processing features, such as [atomate2](https://github.com/materialsproject/atomate2), [quacc](https://github.com/Quantum-Accelerators/quacc), [AFLOW](https://www.aflowlib.org/), [AiiDA](https://www.aiida.net/), [pyiron](https://pyiron.org/), and [VASPkit](https://vaspkit.com/). The **Density Functional Theory ToolKit (DFTTK)** is another addition to this space, with a philosophy of keeping the interface between the user and VASP as minimal as possible and making the automation and post-processing steps easy to see and understand. -**DFTTK** workflows use [Custodian](https://github.com/materialsproject/custodian) for job management. The usefulness of Custodian is that it allows many VASP jobs to be chained together and includes various self-correction strategies for handling VASP errors. Key features are listed below. +DFTTK workflows use [Custodian](https://github.com/materialsproject/custodian) for job management. The usefulness of Custodian is that it allows many VASP jobs to be chained together and includes various self-correction strategies for handling VASP errors. + +Current key features are listed below. ## Key Features From 366b6a4a39836d8af9864a5543c5274b22593994 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Tue, 17 Mar 2026 11:58:53 -0700 Subject: [PATCH 04/10] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ada26a8e..a8e45fea 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ [![Documentation Status](https://readthedocs.org/projects/dfttk/badge/?version=main)](https://www.dfttk.org/en/main/?badge=main) ## Overview -Over the years, many tools have been developed to help set up and/or automate DFT calculations with VASP, as well as provide various post-processing features, such as [atomate2](https://github.com/materialsproject/atomate2), [quacc](https://github.com/Quantum-Accelerators/quacc), [AFLOW](https://www.aflowlib.org/), [AiiDA](https://www.aiida.net/), [pyiron](https://pyiron.org/), and [VASPkit](https://vaspkit.com/). The **Density Functional Theory ToolKit (DFTTK)** is another addition to this space, with a philosophy of keeping the interface between the user and VASP as minimal as possible and making the automation and post-processing steps easy to see and understand. +Over the years, many tools have been developed to help set up and/or automate DFT calculations with VASP, as well as provide various post-processing features, such as [atomate2](https://github.com/materialsproject/atomate2), [quacc](https://github.com/Quantum-Accelerators/quacc), [AFLOW](https://www.aflowlib.org/), [AiiDA](https://www.aiida.net/), [pyiron](https://pyiron.org/), and [VASPKIT](https://vaspkit.com/). The **Density Functional Theory ToolKit (DFTTK)** is another addition to this space, with a philosophy of keeping the interface between the user and VASP as minimal as possible and making the automation and post-processing steps easy to see and understand. DFTTK workflows use [Custodian](https://github.com/materialsproject/custodian) for job management. The usefulness of Custodian is that it allows many VASP jobs to be chained together and includes various self-correction strategies for handling VASP errors. From 3471b9facf7cbf7e4ca9f43e1f8ad9246ed49181 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Wed, 18 Mar 2026 14:15:23 -0700 Subject: [PATCH 05/10] Revise README with updated features --- README.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a8e45fea..70567c50 100644 --- a/README.md +++ b/README.md @@ -16,16 +16,19 @@ Current key features are listed below. ## Key Features ### Enumeration of Configurations -- Enumerates **unique collinear magnetic configurations** for a given structure. +- Enumerates unique collinear magnetic configurations for a given structure. ### VASP Workflows -- Performs **convergence tests** for: +- Performs convergence tests for: - Cutoff energy (`ENCUT`) - k-points grid density (`kppa`) -- Computes **free energy** using the **quasiharmonic approximation**. +- Computes contributions to the Helmholtz energy, $F_k = E_k + F_{k,\text{vib}} + F_{k,\text{el}}$: + - $E_k$ — Energy–volume curves + - $F_{k,\text{vib}}$ — Phonons (post-processed with YPHON) + - $F_{k,\text{el}}$ — From the electronic DOS ### MongoDB Storage -- Stores and retrieves VASP **input data** and **post-processed results** in MongoDB. +- Stores and retrieves VASP input data and post-processed results in MongoDB. ## Installation It is recommended first to set up a virtual environment using Conda: From 053cd2a189f892f1cd6051bd0656390e1ac323c8 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Wed, 18 Mar 2026 14:45:01 -0700 Subject: [PATCH 06/10] Enhance README with post-processing details and updates --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 70567c50..1f0dc1b9 100644 --- a/README.md +++ b/README.md @@ -27,8 +27,12 @@ Current key features are listed below. - $F_{k,\text{vib}}$ — Phonons (post-processed with YPHON) - $F_{k,\text{el}}$ — From the electronic DOS -### MongoDB Storage -- Stores and retrieves VASP input data and post-processed results in MongoDB. +### Post-processing +- $E_k$ — Fit energy–volume curves using an EOS +- $F_{k,\text{vib}}$: + - Debye–Grüneisen model + - Phonons (via YPHON) +- $F_{k,\text{el}}$ — From the electronic DOS ## Installation It is recommended first to set up a virtual environment using Conda: From dcba1c775d91d583a278901d1d7c0ac6adeac9d3 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Fri, 20 Mar 2026 17:59:09 -0400 Subject: [PATCH 07/10] Update README with Configuration class details Added Configuration class to orchestrate VASP workflows and manage results in MongoDB. --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 1f0dc1b9..bb665dbf 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,9 @@ Current key features are listed below. - Phonons (via YPHON) - $F_{k,\text{el}}$ — From the electronic DOS +### Configuration class +The Configuration class orchestrates VASP workflows to compute contributions to $F_k$, along with post-processing and storing results in MongoDB. + ## Installation It is recommended first to set up a virtual environment using Conda: From dd5c83c711ce81dadbbab7a6b298ee68af4640e8 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Fri, 20 Mar 2026 18:18:38 -0400 Subject: [PATCH 08/10] Update README with example notebooks and installation Added example notebooks section and installation instructions. --- README.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index bb665dbf..7921e0ef 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ Current key features are listed below. - Phonons (via YPHON) - $F_{k,\text{el}}$ — From the electronic DOS -### Configuration class +### Configuration Class The Configuration class orchestrates VASP workflows to compute contributions to $F_k$, along with post-processing and storing results in MongoDB. ## Installation @@ -58,14 +58,24 @@ Or clone a specific branch: > **Note:** A PyPI release is currently under development. -## Documentation +## Example Notebooks +Click the badge below to open the project in GitHub Codespaces. +Then, browse the `examples` folder to explore and run the example notebooks: + +[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/PhasesResearchLab/dfttk?quickstart=1) + +| Notebooks | Description | +|--------------|-------------| +| DebyeGruneisen | Compute and plot vibrational contributions to the Helmholtz energy using the Debye–Gruneisen model for Al | +| ThermalElectronic | Compute and plot thermal electronic contributions to the Helmholtz energy for Al using Fermi–Dirac statistics and the electronic DOS| +| Configuration | Orchestrate VASP workflows to compute all contributions to $F_k$, with post-processing, plotting, and MongoDB storage for Al and Fe3Pt| +## Documentation For a comprehensive description of **DFTTK** and its capabilities, please refer to the [Official Documentation](https://vasp-job-automation.readthedocs.io/en/latest/index.html). > **Note:** The documentation is currently under construction. Some sections may be incomplete or subject to change. ## Citing DFTTK - If you use **DFTTK** in your work, please cite the following publication: > **N. Hew et al.**, From 006dc0eedb33576d3f50d92f9539aceea9c419d0 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Fri, 20 Mar 2026 18:24:44 -0400 Subject: [PATCH 09/10] Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7921e0ef..8f0a46f2 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ Then, browse the `examples` folder to explore and run the example notebooks: | Configuration | Orchestrate VASP workflows to compute all contributions to $F_k$, with post-processing, plotting, and MongoDB storage for Al and Fe3Pt| ## Documentation -For a comprehensive description of **DFTTK** and its capabilities, please refer to the [Official Documentation](https://vasp-job-automation.readthedocs.io/en/latest/index.html). +For a comprehensive description of **DFTTK** and its capabilities, please refer to the [Official Documentation](https://www.dfttk.org/en/main/). > **Note:** The documentation is currently under construction. Some sections may be incomplete or subject to change. From 403fcfa07bbfa040e8a909cf269bc66b1782da50 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Fri, 20 Mar 2026 18:25:09 -0400 Subject: [PATCH 10/10] Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8f0a46f2..18d989e0 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ Then, browse the `examples` folder to explore and run the example notebooks: | Notebooks | Description | |--------------|-------------| -| DebyeGruneisen | Compute and plot vibrational contributions to the Helmholtz energy using the Debye–Gruneisen model for Al | +| DebyeGruneisen | Compute and plot vibrational contributions to the Helmholtz energy using the Debye–Grüneisen model for Al | | ThermalElectronic | Compute and plot thermal electronic contributions to the Helmholtz energy for Al using Fermi–Dirac statistics and the electronic DOS| | Configuration | Orchestrate VASP workflows to compute all contributions to $F_k$, with post-processing, plotting, and MongoDB storage for Al and Fe3Pt|