Merge pull request #61 from SMTG-Bham/develop

Develop

CHANGELOG.rst

@@ -1,6 +1,13 @@
 Change Log
 ==========
 
+v.2.4.1
+----------
+- Speed up eigenvalue parsing by using the faster ``doped`` site-matching functions rather than ``MakeDefectStructureInfo`` from ``pydefect``
+- Minor efficiency & robustness updates.
+- Minor docs & tutorials updates
+- Minor tests updates
+
 v.2.4.0
 ----------
 - Electronic structure analysis by @adair-nicolson & @kavanase:

README.md

@@ -25,7 +25,8 @@ All features and functionality are fully-customisable:
 
 ### Performance and Example Outputs
 ![https://github.com/openjournals/joss-reviews/issues/6433](docs/JOSS/doped_JOSS_figure.png)
-**a.** Optimal supercell generation comparison. **b.** Charge state estimation comparison. Example **(c)** Kumagai-Oba (eFNV) finite-size correction plot, **(d)** defect formation energy diagram, **(e)** chemical potential / stability region, **(f)** Fermi level vs. annealing temperature, **(g)** defect/carrier concentrations vs. annealing temperature and **(h)** Fermi level / carrier concentration heatmap plots from `doped`. See the [JOSS paper](https://github.com/openjournals/joss-reviews/issues/6433) for more details.
+**(a)** Optimal supercell generation comparison. **(b)** Charge state estimation comparison. Example **(c)** Kumagai-Oba (eFNV) finite-size correction plot, **(d)** defect formation energy diagram, **(e)** chemical potential / stability region, **(f)** Fermi level vs. annealing temperature, **(g)** defect/carrier concentrations vs. annealing temperature and **(h)** Fermi level / carrier concentration heatmap plots from `doped`. Automated plots of **(i,j)** single-particle eigenvalues and **(k)** site
+displacements from DFT supercell calculations. See the [JOSS paper](https://github.com/openjournals/joss-reviews/issues/6433) for more details.
 <!-- Update this link!! -->
 
 ## Installation

docs/Contributing.rst

@@ -23,6 +23,6 @@ run tests and add new tests for any new features whenever submitting pull reques
 
 .. NOTE::
     If you run into any issues using ``doped`` that aren't addressed on the
-    [Troubleshooting](https://doped.readthedocs.io/en/latest/Troubleshooting.html) page, please contact
+    `Troubleshooting <https://doped.readthedocs.io/en/latest/Troubleshooting.html>`_ page, please contact
     the developers through the ``GitHub`` `Issues <https://github.com/SMTG-Bham/doped/issues>`_ page, or
     by email.

docs/Dev_ToDo.md

@@ -1,9 +1,9 @@
 # `doped` Development To-Do List
 ## Chemical potential
-- Check through chemical potential TO-DOs. Need to recheck validity of approximations used for extrinsic competing phases (and code for this).
+- Check through chemical potential TO-DOs. Need to recheck validity of approximations used for extrinsic competing phases (and code for this). Proper `vasp_std` setup (with `NKRED` folders like for defect calcs) and `vasp_ncl` generation.
 - Efficient generation of competing phases for which there are many polymorphs? See SK notes from CdTe competing phases.
 - Update chemical potential tools to work with new Materials Project API. Currently, supplying an API key for the new Materials Project API returns entries which do not have `e_above_hull` as a property, and so crashes. Ideally would be good to be compatible with both the legacy and new API, which should be fairly straightforward (try importing MPRester from mp_api client except ImportError import from pmg then will need to make a whole separate query/search because `band_gap` and `total_magnetisation` no longer accessible from `get_entries`). See https://docs.materialsproject.org/downloading-data/using-the-api
-- Publication ready chemical potential diagram plotting tool as in Adam Jackson's `plot-cplap-ternary` (3D) and Sungyhun's `cplapy` (4D) (see `doped_chempot_plotting_example.ipynb`; code there, just needs to be implemented in module functions). `ChemicalPotentialGrid` in `py-sc-fermi` interface could be quite useful for this? (Worth moving that part of code out of `interface` subpackage?)
+- Publication ready chemical potential diagram plotting tool as in Adam Jackson's `plot-cplap-ternary` (3D) and Sungyhun's `cplapy` (4D) (see `doped_chempot_plotting_example.ipynb`; code there, just needs to be implemented in module functions). `ChemicalPotentialGrid` in `py-sc-fermi` interface could be quite useful for this? (Worth moving that part of code out of `interface` subpackage?) Also can see https://github.com/materialsproject/pymatgen-analysis-defects/blob/main/pymatgen/analysis/defects/plotting/phases.py for 2D chempot plotting.
   - Also see `Cs2SnTiI6` notebooks for template code for this.
 - Note in tutorial that LaTeX table generator website can also be used with the `to_csv()` function to generate LaTeX tables for the competing phases.
 
@@ -14,8 +14,7 @@
   - Should have `ncols` as an optional parameter for the function, and auto-set this to 2 if the legend height exceeds that of the plot
   - Don't show transition levels outside of the bandgap (or within a certain range of the band edge, possibly using `pydefect` delocalisation analysis?), as these are shallow and not calculable with the standard supercell approach.
   - Option for degeneracy-weighted ('reduced') formation energy diagrams, similar to reduced energies in SOD. See Slack discussion and CdTe pyscfermi notebooks. Would be easy to implement if auto degeneracy handling implemented.
-  - Could also add an optional right-hand-side y-axis for defect concentration (for a chosen anneal temp) to our TLD plotting (e.g. `concentration_T = None`) as done for thesis, noting in docstring that this obvs doesn't account for degeneracy! 
-  - Also carrier concentration vs Fermi level plots as done in the Kumagai PRX paper? With this, should also mention that DOS calcs should be well converged wrt kpoints for accurate Fermi level prediction. 
+  - Could also add an optional right-hand-side y-axis for defect concentration (for a chosen anneal temp) to our TLD plotting (e.g. `concentration_T = None`) as done for thesis, noting in docstring that this obvs doesn't account for degeneracy!  
   - Also see Fig. 6a of the `AiiDA-defects` preprint, want plotting tools like this
 - Can we add an option to give the `pydefect` defect-structure-info output (shown here https://kumagai-group.github.io/pydefect/tutorial.html#check-defect-structures) – seems quite useful tbf
 
@@ -38,9 +37,8 @@
     and/or if it's known from other work for your chosen functional etc.)
   - Show our workflow for calculating interstitials (see docs Tips page, i.e. `vasp_gam` relaxations first (can point to defects tutorial for this)) -> Need to mention this in the defects tutorial, and point to discussion in Tips docs page.
   - Add mini-example of calculating the dielectric constant (plus convergence testing with `vaspup2.0`) to docs/examples, and link this when `dielectric` used in parsing examples. Should also note that the dielectric should be in the same xyz Cartesian basis as the supercell calculations (likely but not necessarily the same as the raw output of a VASP dielectric calculation if an oddly-defined primitive cell is used)
-  - Note about cost of `vasp_ncl` chemical potential calculations for metals, use `ISMEAR = -5`,
-    possibly `NKRED` etc. (make a function to generate `vasp_ncl` calculation files with `ISMEAR = -5`, with option to set different kpoints) - if `ISMEAR = 0` - converged kpoints still prohibitively large, use vasp_converge_files again to check for quicker convergence with ISMEAR = -5.
-  - Use `NKRED = 2` for `vasp_ncl` chempot calcs, if even kpoints and over 4. Often can't use `NKRED` with `vasp_std`, because we don't know beforehand the kpts in the IBZ (because symmetry on for `vasp_std` chempot calcs)(same goes for `EVENONLY = True`).
+  - `vasp_ncl` chemical potential calculations for metals, use `ISMEAR = -5`, possibly `NKRED` etc. (make a function to generate `vasp_ncl` calculation files with `ISMEAR = -5`, with option to set different kpoints) - if `ISMEAR = 0` - converged kpoints still prohibitively large, use vasp_converge_files again to check for quicker convergence with ISMEAR = -5.
+  - Often can't use `NKRED` with `vasp_std`, because we don't know beforehand the kpts in the IBZ (because symmetry on for `vasp_std` chempot calcs)(same goes for `EVENONLY = True`).
   - Readily-usable in conjunction with `atomate`, `AiiDA`(-defects), `vise`, `CarrierCapture`, and give some
     quick examples? Add as optional dependencies.
   - Workflow diagram with: https://twitter.com/Andrew_S_Rosen/status/1678115044348039168?s=20
@@ -57,6 +55,8 @@
     85.115104) suggests that the SOC effects on total energy cancel out for chemical potential
     calculations, but only the case when the occupation of the SOC-affected orbitals is constant
     (typically not the case)) Better to do consistently (link Emily SOC work and/or thesis).
+    - But, can generally use non-SOC energies to reliably determine relative energies of polymorphs of the same composition (oxidation states), to good accuracy.
+    - Also, can use symmetry with SOC total energy calculations, have tested this.
   - Link to Irea review, saying that while spin and configurational degeneracies are accounted for
     automatically in `doped`, excited-state degeneracy (e.g. with bipolarons/dimers with single and triplet
     states) are not, so the user should manually account for this if present. Also note that

docs/Future_ToDo.md

@@ -31,6 +31,7 @@
   workflow which ppl often mess up. Can use modified code from `config-coord-plots` (but actually to
   scale and automatically/sensibly parsed etc.)(also see `CarrierCapture` functionalities)
 - Dielectric/kpoint-sampling weighted supercell generation? (essentially just a vectorised cost function implemented in the generation loop). Would natively optimise e.g. layered materials quite well.
+- `doped`/`SnB`/`easyunfold` (virtual) workshop? Just noting as a possibility, could be MCC-supported.
 
 ## Chemical Potentials
 - Overhaul chemical potentials code, dealing with all `TODO`s in that module. 

docs/Installation.rst

@@ -108,4 +108,5 @@ the ``doped`` GitHub repository:
 Requirements
 -------------
 
-``doped`` requires ``pymatgen>=2022.10.22`` and its dependencies.
+The ``doped`` dependencies are listed in the ``pyproject.toml`` file on
+`the GitHub repository <https://github.com/SMTG-Bham/doped/blob/main/pyproject.toml>`__.