add badelf and warren_lab apps 🎅 (#547)

Co-authored-by: Jack Sundberg <[email protected]>

docs/apps/badelf.md

@@ -0,0 +1,57 @@
+
+# The BadELF App
+
+!!! note
+    This app is currently maintained by [Sam Weaver](https://github.com/SWeav02)
+
+    Further, this app and its BadELF algorithm is based on the following study:
+
+    - ["Counting Electrons in Electrides"](https://pubs.acs.org/doi/abs/10.1021/jacs.3c10876) (JACS 2023)
+
+--------------------------------------------------------------------------------
+
+## About BadELF
+
+Bader Charge Analysis (or "Bader" for short) is a process of partitioning charge density in order to predict oxidation states. Then the Electron Localization Function (ELF) is a popular scheme for visualizing chemically important features in molecules and solids.
+
+BadELF builds on top of these two ideas. The algorithm uses Bader segmentation of the ELF to find the electride electrons (if any) and Voronoi segmentation of the ELF to identify atoms. Thus BadELF is intended as an alternative method to run population analysis / predict oxidation states of electrides.
+
+--------------------------------------------------------------------------------
+
+## About this app
+
+This app provides workflows and utilities to help with BadELF analysis.
+
+--------------------------------------------------------------------------------
+
+## Installation
+
+1. Make sure you have Simmate installed and have reset your database.
+
+2. Register the warrenapp with simmate by adding `- warrenapp.apps.WarrenConfig` to `~/simmate/my_env-apps.yaml`
+
+3. Update your database to include custom tables from the warrenapp
+``` shell
+simmate database update
+```
+
+--------------------------------------------------------------------------------
+
+## Basic Use
+
+BadELF requires the outputs from VASP calculations (e.g. the CHGCAR, ELFCAR, etc.). You can either (a) generate these on your own or (b) run a simmate workflow that does it for you. 
+
+### (a) from VASP outputs
+
+The BadELF algorithm can be run in a folder with VASP results. Please note that your VASP settings must produce a CHGCAR and ELFCAR with the same grid size.
+``` bash
+simmate-badelf run
+```
+
+### (b) from structure
+
+If you would prefer to have Simmate handle the VASP calculation, there are workflows that will first run the required DFT and then BadELF. 
+
+These workflows are stored in the `Warren Lab` app because we are our lab's preferred VASP settings there. View the `Warren Lab` app for more information and to see the workflows available.
+
+--------------------------------------------------------------------------------

docs/apps/bader_henkelman.md

@@ -0,0 +1,51 @@
+
+# The Bader App
+
+--------------------------------------------------------------------------------
+
+## About Bader
+
+Bader Charge Analysis (or "Bader" for short) is a process of  partitioning charge density in order to predict oxidation states. This module is specifically for the [Henkelman Group](http://theory.cm.utexas.edu/henkelman/)'s code that implements this analysis.
+
+The code is free to everyone and can be downloaded [here](http://theory.cm.utexas.edu/henkelman/code/bader/).
+
+--------------------------------------------------------------------------------
+
+## About this app
+
+This app uses Simmate tools to build workflows and utilities on top of the Henkelman Lab's Bader code. 
+
+Typically, other workflows handle calling the workflows registered here. For example, you can find workflows in the `Warren Lab` app that combine Bader, VASP, and rational settings together for you. Beginners should therefore start elsewhere.
+
+--------------------------------------------------------------------------------
+
+## Installation (Ubuntu 22.04)
+
+### `bader` command
+
+1. Download `Linux x86-64` from the Henkelman website [here](http://theory.cm.utexas.edu/henkelman/code/bader/)
+2. Unpack the compressed file. There should only be one "file" in it named bader. This is the executable.
+3. Move the `bader` executable to a folder of your choosing. For example, `~/jacksund/bader/bader` (within a folder named bader in my home directory)
+4. run `nano ~/.bashrc` to edit your bash and add this line to the bottom:
+``` bash
+export PATH=/home/jacksund/bader/:$PATH
+```
+5. restart your terminal and try the command `bader --help`
+
+### `chgsum.pl` and extra scripts
+
+1. Download the scripts from [VTST-tools](http://theory.cm.utexas.edu/vtsttools/scripts.html)
+2. Unpack the folder (`vtstscripts-1033`) and move it into the folder with your bader executable
+3. run `nano ~/.bashrc` to edit your bash and add this line to the bottom:
+``` bash
+export PATH=/home/jacksund/bader/vtstscripts-1033:$PATH
+```
+4. restart your terminal and you're ready to try Bader analyses with Simmate!
+
+--------------------------------------------------------------------------------
+
+## Helpful links
+
+ - [website](http://theory.cm.utexas.edu/henkelman/code/bader/) (includes docs + guide)
+
+--------------------------------------------------------------------------------

docs/apps/clease.md

@@ -1,16 +1,24 @@
+
+# The CLEASE App
+
 !!! danger
     This app is still under early testing and not really for use outside of the Warren Lab
 
-The CLEASE App
---------------------
+--------------------------------------------------------------------------------
+
+## About
 
 *From their webpage:*
 CLuster Expansion in Atomic Simulation Environment (CLEASE) is a package that automates the cumbersome setup and construction procedure of cluster expansion (CE). It provides a comprehensive list of tools for specifying parameters for CE, generating training structures, fitting effective cluster interaction (ECI) values and running Monte Carlo simulations.
 
 The code is free and open-source.
 
+--------------------------------------------------------------------------------
+
 ## Helpful links
 
  - [gitlab](https://gitlab.com/computationalmaterials/clease/)
  - [documentation](https://clease.readthedocs.io/en/stable/)
- - [paper](https://doi.org/10.1088/1361-648X/ab1bbc)
+ - [paper](https://doi.org/10.1088/1361-648X/ab1bbc)
+
+--------------------------------------------------------------------------------

docs/apps/deepmd.md

@@ -1,16 +1,23 @@
 
+# The DeePMD App
+
 !!! danger
     This app is still under early testing and not really for use outside of the Warren Lab
 
-The DeePMD App
---------------------
+--------------------------------------------------------------------------------
+
+## About
 
 The Deep Potential for Molecular Dynamics (DeePMD) is a package that builds machine-learned interatomic potentials from energy and force-field data. These machine-learned potentials are particularlly powerful when trained on DFT data and then subsequently used to run molecular dynamics simulations.
 
 The code is free and open-source.
 
+--------------------------------------------------------------------------------
+
 ## Helpful links
 
  - [github](https://github.com/deepmodeling/deepmd-kit)
  - [documentation](https://docs.deepmodeling.org/projects/deepmd/en/master/)
  - [paper](https://www.sciencedirect.com/science/article/pii/S0010465518300882)
+
+--------------------------------------------------------------------------------

docs/apps/warren_lab.md

@@ -0,0 +1,80 @@
+
+# The Warren Lab App
+
+!!! note
+    This app is currently maintained by [Sam Weaver](https://github.com/SWeav02)
+
+--------------------------------------------------------------------------------
+
+## About
+
+Scott Warren's Materials Discovery Lab at the University of North Carolina (Chapel Hill) lab specicializes in electrides, fluoride-ion batteries, and 2D materials. 
+
+This `Warren Lab` app contains workflows for our lab's preferred DFT settings and common analyses. By registering this app, you will add many new workflow presets that build on top of several other apps (VASP, Bader, BadELF, etc.).
+
+--------------------------------------------------------------------------------
+
+## Helpful links
+
+ - [Scott Warren](https://chem.unc.edu/faculty/warren-scott/) (UNC contact page)
+ - [lab website](https://materials-lab.io/)
+
+--------------------------------------------------------------------------------
+
+## Installation
+
+1. Make sure you have Simmate installed and a working database.
+
+2. Add the following apps to `~/simmate/my_env-apps.yaml`:
+``` yaml
+# Add app dependencies.
+# NOTE!!! some of these are already present by default. Do not add duplicates
+- simmate.apps.configs.VaspConfig
+- simmate.apps.configs.BaderConfig
+- simmate.apps.configs.BadelfConfig
+# Add warren lab app.
+- simmate.workflows.configs.WarrenLabConfig
+```
+
+3. Update your database to include custom tables:
+``` bash
+simmate database update
+```
+
+--------------------------------------------------------------------------------
+
+## Workflows provided
+
+### VASP (relaxation)
+
+```
+relaxation.vasp.warren-lab-hse
+relaxation.vasp.warren-lab-hse-with-wavecar
+relaxation.vasp.warren-lab-hsesol
+relaxation.vasp.warren-lab-pbe
+relaxation.vasp.warren-lab-pbe-metal
+relaxation.vasp.warren-lab-pbe-with-wavecar
+relaxation.vasp.warren-lab-pbesol
+relaxation.vasp.warren-lab-scan
+```
+
+### VASP (static energy)
+
+```
+static-energy.vasp.warren-lab-hse
+static-energy.vasp.warren-lab-hsesol
+static-energy.vasp.warren-lab-pbe
+static-energy.vasp.warren-lab-pbe-metal
+static-energy.vasp.warren-lab-pbesol
+static-energy.vasp.warren-lab-prebadelf-hse
+static-energy.vasp.warren-lab-prebadelf-pbesol
+static-energy.vasp.warren-lab-scan
+```
+
+### BadELF
+
+```
+bad-elf-analysis.badelf.badelf-pbesol
+```
+
+--------------------------------------------------------------------------------

docs/change_log.md

@@ -82,6 +82,9 @@ There is one key exception to the rules above -- and that is with `MAJOR`=0 rele
 - add `django-simple-history` support to track user changes on specific models
 - add `@check_db_conn` decorator to help with database connection closures/timeouts
 - add `simmate engine start-schedules` which let's you configure periodic tasks for individual apps (e.g. check a table for updates every 5 minutes). Includes error handling and email alerts. (Note: this a quick alternative to full Prefect system)
+- add warren_lab app with Warren Lab preferred VASP settings
+- add badelf app with class oriented tools for performing BadELF analyses
+- add `simmate-badelf` command for running badelf analysis
 
 **Fixes**