Soc PROCAR handling and more (#28)

* Update docs main page * Update `README.md` * Add `-h` CLI help options * `yapf` formatting * Update `Guide` docs * Update NaBiS2 figure to have title centred * Update atom-projected NaBiS2 figures to have titles centred * Refactor `Guide` to `Tutorial` as this is more recognisable to people in the field (otherwise most will skip to the examples) * Update `publications.md` * Update `theory.md` * Add links to Theory page * Update `Installation` docs page * Recentre Si222 images * Fix typos and make output more informative * Add symlinked `README.md`s for the other examples as well as Si222 * Update `Si222` docs example * Update `Si` CASTEP docs example * Update `MgO` docs example * Fix `colors`/`cmap` handling and docstrings * Update `NaBiS2` example * Add .DS_Store to gitignore * Refactor `vscale` to `colour-norm` and update help message/docstrings as discussed in #10. Tested and works as expected * Parse `PROCAR` in current directory by default, and update help message accordingly. Tested and works as expected * Add `--atoms` option (and corresponding functions) to just specify which atoms to project (rather than `atoms_idx`), by reading from POSCAR/CONTCAR. Tested and works as expected. Avoids using `pymatgen` as a dependency also. Will update examples to show this functionality * Remove completed TODO * Consolidate `colour_norm` (formerly `vscale`) and `intensity` as they do the same thing just in different plotting functions (which depends on whether `--combined` is used). Tested and all works as expected * Make `ylim` consistent between CLI and plotting module * Add DOS plotting functionality * Refactor `mpl-style-file` to plot command options, as it's the only place where it affects behaviour (and to avoid user confusion about having to place it after `unfold` but before `plot`) * Update CLI * Clean up the time-reversal symmetry handling Simplify the handling of the time-reversal symmetry * Add docstrings * Ignore unnecessary `POTCAR` warnings * Update help messages to be more informative * Consolidate DOS plot and projected plot colours * Colour different orbitals for the same atom as different shades of the specified colour * Update `PROCAR` handling to deal with setting just `p` or just `d` for orbital projections (all directions) * Update CLI help messages * Match DOS elements and orbitals with `atoms` / `orbitals` options * Match DOS elements/orbitals with `atoms`/`orbitals` for non-projected plot * Allow non-projected plot to still specify `atoms`/`atoms_idx` and/or `orbitals` in groups, rather than all as one (e.g. if we want to use weighting with s orbitals from one and p orbitals from a different group of atoms), and sum for the final spectral function plot * Update `unfold` docstrings to be more informative * Add multi-group orbital handling to `parse_atoms()` * Formatting * Handle colours/line-styles for _lm_-decomposed orbital contributions, to match the colour projections on the bandstructure * Linting * Ignore other `POTCAR` warnings * Update `pre-commit` requirements * Update `sumo` function calling for `pylint` * Add NaBiS2 directory test setup * Add help message option tests * Add NaBiS2 plotting tests, with all options * Formatting * Update tests * Fix `sumo` version * Handle older `sumo` version requirement * Formatting * Add link to NaBiS2 customisation in Si example * Fix missing file link in tutorial * Update `Si222` plots (first plots potential users will see, want them looking decent) * Update MgO example figures, commands, docs (show recommended `--atoms` rather than `--atoms-idx`) * Refactor `colors` to `colours` and formatting * Update `NaBiS2` example with new `--atoms` option, and specific application of `--atoms-idx` * Update `sumo` requirement * Add DOS plot example * Relax `sumo` requirements * Formatting * Add atom-projected w/DOS example * Add notes/warnings about `sumo` requirement for DOS plots and not to use the `vasprun.xml` from GGA band structure calcs * Handle case where user sets the same atom in different projection groupings, but with different orbitals * Add orbital projected band structure with DOS example * Add lm-decomposed orbital projected band structure with DOS example * Adjust figure sizing * Update handling of multiple atom-orbital combos with the same atomic element for `unfold plot` (not projected) * Removed unused image * Refactor usages of `Easyunfold` to `easyunfold` (this is the canonical package name I believe?) * Fix `symprec` help message * Hide `--yes` help option * Update tutorial to show the `scf-kpoints` option for hybrid DFT calculations * Update tutorial to mention `--gamma` and `--ncl` options * Move `add_plot_options` to just before `plot` commands (rather than before `effective_mass` where it isn't used) * Refactor `mpl_style_option` to a decorator to avoid code duplication and allow it to be added as an option to `effective_mass`, `plot` and `plot-projections` * Revert `colour_norm` to `vscale` * Fix `intensity` handling from #26 * Replace all instances of `colour-norm`/`vscale` in docs with recommended `intensity` option * Add `poscar` option to specify `POSCAR` file as requested, and add test for this * Make shell files executable * Add help messages and docstrings for `--time-reversal`, and remove `TODO` * Update `PROCAR` handling to work for all `LORBIT >= 11` and add test for this * Move `if dos:` block to separate function to avoid code duplication * Refactor DOS plotter handling in `plotting` to separate function to avoid code duplication * Bump version number before next major release with backwards-compatible DOS plotting and other additions * `pre-commit` formatting * Remove unused `ncl` and `gamma` CLI options from plot options (CLI plot commands require WAVECARs to already have been parsed with `unfold calculate`, so these are just fluff options that do nothing) * Overhaul `PROCAR` handling to handle and amalgamate multiple `PROCAR`s in one `Procar` object. Means that previously-parsed kpoints are skipped (and not double counted), as well as some efficiency boosts and aided handling * Refactor other modules to updated `PROCAR` handling * Dynamically determine whether `PROCAR`s are SOC or not * Make `Procar` object JSON serializable * Add deprecation notice for `vscale` * Add notes about passing multiple `--procar` options for split `PROCAR`s in docs * Update `test_procar()` (Gamma point duplicated in k-point path so updated parsing reduces nkpts from 48 to 47) * Bump version number * No ticks on DOS plots * Use sumo orbital colours in DOS plots (if not atom-projected plot) * Pre-commit formatting * Pre-commit formatting * Code cleanup and efficiency * Fix weight normalisation * Add `colourspace` CLI option for `plot-projected` * Code cleanup * Code cleanup * Change default colour handling ("g" in matplotlib goes to (0,0.5,0) in RGB space which can give odd interpolation behaviour, so use RGB coordinates as defaults instead) * Renormalise final interpolated colours appropriately * Change default `colorspace` to `xyz` * Normalise PROCAR projections so the total orbital projection sums to 1 (this avoids cases where bands with delocalised contributions become very very faint just because there is less complete orbital basis set assignment to them in VASP, rather than actually having low spectral function intensity (still weighted by the actual spectral function intensity in the plot)) * pre-commit formatting * Darken colour slightly if too white * Set default colours and colorspace to `lablch` (to be discussed) * Add and update tests * Update test * Default colourspace is `LAB` everywhere * Pre commit formatting * Update MgO projection plots * Update NaBiS2 projection plots * Add example outputs mini section * Pre-commit formatting * Bump version number before next release * GitHub readme doesn't seem to work with symlinks? * Resize images * Update README.md * Subscript formatting * Subscript formatting * Remove `with` from `_read` method --------- Co-authored-by: Bonan Zhu <[email protected]>
SMTG-Bham · Aug 10, 2023 · 8397a72 · 8397a72
1 parent 0bf8180
commit 8397a72
Show file tree

Hide file tree

Showing 26 changed files with 522 additions and 316 deletions.
diff --git a/.gitignore b/.gitignore
@@ -47,3 +47,5 @@ KPOINTS
 PROCAR
 *.json
 *.DS_Store
+
+local_tests/
diff --git a/README.md b/README.md
@@ -21,6 +21,11 @@ package.
 For the methodology of supercell band unfolding, see
 [here](https://link.aps.org/doi/10.1103/PhysRevB.85.085201).
 
+### Example Outputs
+Cs₂(Sn/Ti)Br₆ Vacancy-Ordered Perovskite Alloys |     Symmetry-broken Si Supercell
+:-------------------------:|:------------------------------------:
+<img src="docs/img/CSTB_easyunfold.gif" height="400"/> | <img src="examples/Si222/unfold_tall.png" height="400"/>
+
 ## Usage
 
 To generate an unfolded band structure, one typically needs to perform the following steps:

diff --git a/docs/examples/example_mgo.md b/docs/examples/example_mgo.md
@@ -38,9 +38,15 @@ easyunfold unfold plot-projections --procar MgO_super/PROCAR --atoms="Mg,O" --co
 
 Note that the path of the `PROCAR` is passed along with the desired atom projections (`Mg` and `O` here). 
 
+:::{tip}
+If the _k_-points have been split into multiple calculations (e.g. hybrid DFT band structures), the `--procar` option 
+should be passed multiple times to specify the path to each split `PROCAR` file (i.e. 
+`--procar calc1/PROCAR --procar cal2/PROCAR ...`).
+:::
+
 :::{note}
-The atomic projections are not stored in the `easyunfold.json` data file, so the `PROCAR` file should be 
-kept for replotting in the future.
+The atomic projections are not stored in the `easyunfold.json` data file, so the `PROCAR` file(s) should be kept for 
+replotting in the future.
 :::
 
 The `--combined` option creates a combined plot with different colour maps for each atomic grouping.
@@ -97,3 +103,8 @@ easyunfold unfold plot-projections --procar MgO_super/PROCAR --atoms="Mg,O" --em
 
 Unfolded MgO band structure with atomic projections plotted separately.
 ```
+
+:::{tip}
+There are _many_ customisation options available for the plotting functions in `easyunfold`. See `easyunfold plot -h` or 
+`easyunfold unfold plot-projections -h` for more details!
+:::
diff --git a/docs/examples/example_nabis2.md b/docs/examples/example_nabis2.md
@@ -88,7 +88,7 @@ When plotting the unfolded band, the `plot-projections` subcommand is used with
 `--atoms` options:
 
 ```bash
-easyunfold unfold plot-projections --atoms="Na,Bi,S" --intensity 2 --combined
+easyunfold unfold plot-projections --atoms="Na,Bi,S" --intensity 3 --combined
 ```
 
 ```{figure} ../../examples/NaBiS2/NaBiS2_unfold-plot_proj.png
@@ -98,6 +98,12 @@ easyunfold unfold plot-projections --atoms="Na,Bi,S" --intensity 2 --combined
 Unfolded band structure of NaBiS<sub>2</sub> with atomic contributions.
 ```
 
+:::{tip}
+If the _k_-points have been split into multiple calculations (e.g. hybrid DFT band structures), the `--procar` option 
+should be passed multiple times to specify the path to each split `PROCAR` file (i.e. 
+`--procar calc1/PROCAR --procar cal2/PROCAR ...`).
+:::
+
 From this plot, we can see that sulfur anions dominate the valence band, while bismuth cations dominate the conduction 
 band, with minimal contributions from the sodium cations as expected.
 
@@ -126,7 +132,7 @@ Unfolded band structure of NaBiS<sub>2</sub> with atomic contributions plotted s
 
 An alternative option here is also to just plot only the contributions of `Na` and `Bi` cations, with no S projections:
 ```bash
-easyunfold unfold plot-projections --atoms="Na,Bi" --intensity 2 --combined
+easyunfold unfold plot-projections --atoms="Na,Bi" --intensity 3 --combined
 ```
 
 ```{figure} ../../examples/NaBiS2/NaBiS2_unfold-plot_proj_noS.png
@@ -143,7 +149,7 @@ While this plot isn't the most aesthetic, it clearly shows that Bi (green) contr
 ### Atom-projected Unfolded Band Structure with DOS
 We can also combine the atom projections with the DOS plotting, using the `--dos` option as before:
 ```bash
-easyunfold unfold plot-projections --atoms "Na,Bi,S" --intensity 2 --combined --dos vasprun.xml.gz --zero-line \
+easyunfold unfold plot-projections --atoms "Na,Bi,S" --intensity 3 --combined --dos vasprun.xml.gz --zero-line \
   --dos-label "DOS" --gaussian 0.1 --no-total --scale 2
 ```
 
@@ -193,7 +199,7 @@ For example, if we want to see the contributions of the Bi $s$, $p$ and S $s$ or
 we can use the following command:
 
 ```bash
-easyunfold unfold plot-projections --atoms "Bi,Bi,S" --orbitals="s|p|s"  --intensity 2  --combined \
+easyunfold unfold plot-projections --atoms "Bi,Bi,S" --orbitals="s|p|s"  --intensity 3  --combined \
   --dos vasprun.xml.gz --zero-line --dos-label "DOS" --gaussian 0.1 --no-total --scale 5
 ```
 
@@ -216,7 +222,7 @@ see the contributions of the Bi and S $p_x$, $p_y$ and $p_z$ orbitals to the unf
 following command:
 
 ```bash
-easyunfold unfold plot-projections --atoms "Na,Bi,S" --orbitals="all|px,py,pz|px,py,pz" --intensity 2 --combined \
+easyunfold unfold plot-projections --atoms "Na,Bi,S" --orbitals="all|px,py,pz|px,py,pz" --intensity 3 --combined \
   --dos vasprun.xml.gz --zero-line --dos-label "DOS" --gaussian 0.1 --no-total --scale 6
 ```
 
@@ -232,6 +238,10 @@ structure, due to the cubic symmetry of the NaBiS<sub>2</sub> crystal structure.
 for the $d$ orbitals of transition metals in octahedral/tetrahedral environments, we would expect to see significant 
 differences in the contributions of different $lm$-decomposed orbitals to the electronic structure.
 
+:::{tip}
+There are _many_ customisation options available for the plotting functions in `easyunfold`. See `easyunfold plot -h` or 
+`easyunfold unfold plot-projections -h` for more details!
+:::
 
 [^1]: [Huang, YT., Kavanagh, S.R., Righetto, M. et al. Strong absorption and ultrafast localisation in NaBiS2 nanocrystals with slow charge-carrier recombination. Nat Commun 13, 4960 (2022)](https://www.nature.com/articles/s41467-022-32669-3) 
 [^2]: [Wang, Y., Kavanagh, S.R., Burgués-Ceballos, I. et al. Cation disorder engineering yields AgBiS2 nanocrystals with enhanced optical absorption for efficient ultrathin solar cells. Nat. Photon. 16, 235–241 (2022).](https://www.nature.com/articles/s41566-021-00950-4)
diff --git a/docs/examples/example_si211_castep.md b/docs/examples/example_si211_castep.md
@@ -143,4 +143,9 @@ Supercell band structure of Si in a 2x1x1 supercell
 
 which, as expected, is the same as the primitive cell if it is folded back along the midpoint between 
 $\Gamma$ and $X$, corresponding to the 2x expansion of the primitive cell along the $x$ direction in 
-generating the 2x1x1 supercell. 
+generating the 2x1x1 supercell. 
+
+:::{tip}
+There are _many_ customisation options available for the plotting functions in `easyunfold`. See `easyunfold plot -h` or 
+`easyunfold unfold plot-projections -h` for more details!
+:::
diff --git a/docs/examples/example_si222.md b/docs/examples/example_si222.md
@@ -131,7 +131,6 @@ customising and prettifying the unfolded band structure plot. Here we have also
 option to increase the spectral function intensity.
 :::
 
-
 Note the appearance of extra branches compared to the band structure of the primitive cell (below), due 
 to symmetry breaking from the displaced atom.
 

diff --git a/docs/img/CSTB_easyunfold.gif b/docs/img/CSTB_easyunfold.gif
diff --git a/docs/img/Si_222_unfold_tall.png b/docs/img/Si_222_unfold_tall.png
@@ -0,0 +1 @@
+../../examples/Si222/unfold_tall.png
diff --git a/docs/index.md b/docs/index.md
@@ -20,6 +20,11 @@ package.
 For the methodology of supercell band unfolding, see 
 [here](https://link.aps.org/doi/10.1103/PhysRevB.85.085201).
 
+### Example Outputs
+Cs₂(Sn/Ti)Br₆ Vacancy-Ordered Perovskite Alloys |     Symmetry-broken Si Supercell     
+:-------------------------:|:------------------------------------:
+<img src="../img/CSTB_easyunfold.gif" height="400"/> | <img src="../img/Si_222_unfold_tall.png" height="400"/>
+
 ## Usage
 
 To generate an unfolded band structure, one typically needs to perform the following steps:

diff --git a/easyunfold/__init__.py b/easyunfold/__init__.py
@@ -2,4 +2,4 @@
 Collection of code for band unfolding
 """
 
-__version__ = '0.2.0'
+__version__ = '0.3.0'