Merge develop, and update tests

.github/workflows/pip_install_test.yml

@@ -19,11 +19,11 @@ jobs:
 
       matrix:
         os: [ ubuntu-latest, macos-14 ]
-        python-version: [ '3.9', '3.10', '3.11' ]
+        python-version: [ '3.9', '3.10', '3.11', '3.12' ]
         exclude:
           - os: macos-14
             python-version: '3.9'  # Exclude Python 3.9 on macOS, not supported for macOS-14 tests
-        # macos-latest should be 14 according to link below, but currently doesn't?
+        # macos-latest should be 14 according to link below, but currently doesn't? Possibly because 3.9 included here? Update when 3.9 cut
         # https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories
 
     runs-on: ${{ matrix.os }}

.github/workflows/test.yml

@@ -14,11 +14,11 @@ jobs:
 
       matrix:
         os: [ ubuntu-latest, macos-14 ]
-        python-version: [ '3.9', '3.10', '3.11' ]
+        python-version: [ '3.9', '3.10', '3.11', '3.12' ]
         exclude:
           - os: macos-14
             python-version: '3.9'  # Exclude Python 3.9 on macOS, not supported for macOS-14 tests
-        # macos-latest should be 14 according to link below, but currently doesn't?
+        # macos-latest should be 14 according to link below, but currently doesn't? Possibly because 3.9 included here? Update when 3.9 cut
         # https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories
 
     runs-on: ${{ matrix.os }}

docs/Code_Compatibility.rst

@@ -1,6 +1,8 @@
 Code Compatibility
 ========================
 
+Python Package Compatibility
+----------------------------
 :code:`doped` is built to natively function using (and being compatible with) the most recent version of
 :code:`pymatgen`. If you are receiving :code:`pymatgen`-related errors when using
 :code:`doped`, you may need to update :code:`pymatgen` and/or :code:`doped`, which can be done with:
@@ -15,11 +17,24 @@ July 2022, such that major refactoring was undertaken to make the code compatibl
 < ``2022.7.25``).
 
 .. note::
-  If you run into this ``numpy``-related error, please see the :ref:`Troubleshooting <troubleshooting>`
-  section on the docs tips page:
-
-  .. code:: python
-
-      ValueError: numpy.ndarray size changed, may indicate binary incompatibility. Expected 88 from C header, got 80 from PyObject
+  If you run into any errors when using ``doped``, please check the
+  :ref:`Troubleshooting <troubleshooting>` docs page, where any known issues with codes (such as ``numpy``,
+  ``scipy`` or ``spglib``) are detailed.
+
+Energy Calculator (DFT/ML) Compatibility
+----------------------------------------
+The vast majority of the code in :code:`doped` is agnostic to the underlying energy calculator / electronic
+structure (i.e. DFT/ML) code used to calculate the raw energies of defect supercells. However, as
+demonstrated in the tutorials, direct I/O support is currently provided for the ``VASP`` DFT code, while
+structure files for essentially all DFT/ML codes can be easily generated using the
+`pymatgen <https://pymatgen.org/pymatgen.core.html#pymatgen.core.structure.IStructure.to>`__ or
+`ase <https://wiki.fysik.dtu.dk/ase/ase/io/io.html#ase.io.write>`__ I/O methods, with the ``pymatgen``
+``Structure`` objects used for crystal structures in ``doped``.
+
+Direct I/O capabilities for other codes is a goal (such as ``Quantum Espresso``, ``CP2K`` and/or
+``FHI-aims``), accompanied by an update publication, so please get in touch with the developers if you
+would be interested in contributing to this effort! Input file generation and structure/energy parsing
+should be straightforward with the ``doped``/``pymatgen``/``ase`` APIs, while finite-size charge
+corrections would be the main challenge for parsing & computing.
 
 Please let us know if you have any issues with compatibility!

docs/Dev_ToDo.md

@@ -2,8 +2,6 @@
 ## Chemical potential
 - 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.
-- 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.
 
 ## Post-processing / analysis / plotting
 - Better automatic defect formation energy plot colour handling (auto-change colormap based on number of defects, set similar colours for similar defects (types and inequivalent sites)) – and more customisable?
@@ -21,7 +19,7 @@
 
 ## Housekeeping
 - Tutorials general structure clean-up
-- Clean up repo, removing old unnecessary git blobs
+- Remnant TODOs in code
 
 - Docs:
   - Update note at end of thermo tutorial to link to py-sc-fermi/doped interface.
@@ -89,9 +87,10 @@
 
 ## SK To-Do for next update:
 - `doped` repo/docs cleanup `TODO`s above
+- Clean up repo, removing old unnecessary git blobs
 - Note in chempots tutorial that LaTeX table generator website can also be used with the `to_csv()` function to generate LaTeX tables for the competing phases.
 - Quick-start tutorial suggested by Alex G
-- Add chempot grid plotting tool, shown in `JOSS_plots` using Alex's chemical potential grid, and test (and remove TODO from JOSS plots notebook).
+- Test chempot grid plotting tool.
 - `dist_tol` should also group defects for the concentration etc functions, currently doesn't (e.g. `CdTe_thermo.get_equilibrium_concentrations(limit="Te-rich", per_charge=False, fermi_level=0.5)` and `CdTe_thermo.dist_tol=10; CdTe_thermo.get_equilibrium_concentrations(limit="Te-rich", per_charge=False, fermi_level=0.5)`, same output)
 - Plotting lines colour updates.
 - Add example to chemical potentials / thermodynamics analysis tutorials of varying chemical potentials as a function of temperature/pressure (i.e. gas phases), using the `Spinney` functions detailed here (https://spinney.readthedocs.io/en/latest/tutorial/chemipots.html#including-temperature-and-pressure-effects-through-the-gas-phase-chemical-potentials) or possibly `DefAP` functions otherwise.

docs/JOSS/data/Cs2SnBr6_competing_phase_energies.csv

@@ -0,0 +1,62 @@
+Formula,Formation Energy (eV/fu),Formation Energy (eV/atom),DFT Energy (eV/atom),DFT Energy (eV/fu),DFT Energy (eV),k-points,Cs,Sn,Br,H,O,Cl,Ti,I
+Cs2SnBr6,-12.784507527586204,-1.420500836398467,-3.8668539155555552,-34.80168524,-34.80168524,3x3x3,2.0,1.0,6.0,0.0,0.0,0.0,0.0,0.0
+Br,0.0,0.0,-2.505645065,-2.505645065,-10.02258026,6x6x3,0.0,0.0,1.0,0.0,0.0,0.0,0.0,0.0
+Cl2,0.0,0.0,-2.655503765,-5.31100753,-5.31100753,1x1x1,0.0,0.0,0.0,0.0,0.0,2.0,0.0,0.0
+Cs,0.0,0.0,-1.0485996862068965,-1.0485996862068965,-30.4093909,4x4x4,1.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0
+H2,0.0,0.0,-3.905740315,-7.81148063,-7.81148063,1x1x1,0.0,0.0,0.0,2.0,0.0,0.0,0.0,0.0
+I,0.0,0.0,-2.37863731,-2.37863731,-9.51454924,5x5x2,0.0,0.0,0.0,0.0,0.0,0.0,0.0,1.0
+O2,0.0,0.0,-7.02013651,-14.04027302,-14.04027302,1x1x1,0.0,0.0,0.0,0.0,2.0,0.0,0.0,0.0
+Sn,0.0,0.0,-4.88610795,-4.88610795,-9.7722159,10x10x10,0.0,1.0,0.0,0.0,0.0,0.0,0.0,0.0
+Ti,0.0,0.0,-10.151714933333333,-10.151714933333333,-30.4551448,6x6x9,0.0,0.0,0.0,0.0,0.0,0.0,1.0,0.0
+ClO2,0.7096600150000003,0.23655333833333345,-5.32870559,-15.98611677,-127.88893416,3x2x2,0.0,0.0,0.0,0.0,2.0,1.0,0.0,0.0
+Cs2O,-3.15938636091954,-1.05312878697318,-4.092240747777778,-12.276722243333333,-36.83016673,6x6x1,2.0,0.0,0.0,0.0,1.0,0.0,0.0,0.0
+CsBr,-3.9859229587931044,-1.9929614793965522,-3.770083855,-7.54016771,-7.54016771,4x4x4,1.0,0.0,1.0,0.0,0.0,0.0,0.0,0.0
+CsBr3,-4.273783741293103,-1.0684459353232758,-3.209829655625,-12.8393186225,-51.35727449,3x3x3,1.0,0.0,3.0,0.0,0.0,0.0,0.0,0.0
+CsCl,-4.432881008793103,-2.2164405043965516,-4.06849223,-8.13698446,-8.13698446,4x4x4,1.0,0.0,0.0,0.0,0.0,1.0,0.0,0.0
+CsI,-3.4757193637931043,-1.7378596818965522,-3.45147818,-6.90295636,-6.90295636,5x5x5,1.0,0.0,0.0,0.0,0.0,0.0,0.0,1.0
+CsI3,-3.680982218793105,-0.9202455546982763,-2.96637345875,-11.865493835,-47.46197534,2x2x2,1.0,0.0,0.0,0.0,0.0,0.0,0.0,3.0
+CsI4,-3.7229461212931043,-0.7445892242586208,-2.8572190095,-14.2860950475,-57.14438019,2x2x1,1.0,0.0,0.0,0.0,0.0,0.0,0.0,4.0
+H2O,-2.6916064299999984,-0.8972021433333328,-5.841074523333333,-17.52322357,-17.52322357,1x1x1,0.0,0.0,0.0,2.0,1.0,0.0,0.0,0.0
+HBr,-0.27320103999999956,-0.13660051999999978,-3.34229321,-6.68458642,-6.68458642,1x1x1,0.0,0.0,1.0,1.0,0.0,0.0,0.0,0.0
+HCl,-0.9734486099999997,-0.48672430499999986,-3.767346345,-7.53469269,-7.53469269,1x1x1,0.0,0.0,0.0,1.0,0.0,1.0,0.0,0.0
+HI,0.3515555049999999,0.17577775249999994,-2.96641106,-5.93282212,-5.93282212,1x1x1,0.0,0.0,0.0,1.0,0.0,0.0,0.0,1.0
+I2O5,-1.0436959499999974,-0.14909942142857105,-5.843093302857143,-40.90165312,-163.60661248,3x5x3,0.0,0.0,0.0,0.0,5.0,0.0,0.0,2.0
+I2O5,-1.0436959499999974,-0.14909942142857105,-5.843093302857143,-40.90165312,-163.60661248,3x5x3,0.0,0.0,0.0,0.0,5.0,0.0,0.0,2.0
+SnBr2,-2.329004039999999,-0.7763346799999997,-4.075467373333333,-12.22640212,-12.22640212,3x3x2,0.0,1.0,2.0,0.0,0.0,0.0,0.0,0.0
+SnBr4,-3.7090816324999993,-0.7418163264999998,-3.7235539685,-18.6177698425,-74.47107937,2x2x1,0.0,1.0,4.0,0.0,0.0,0.0,0.0,0.0
+SnCl2,-3.3810519875000002,-1.1270173291666667,-4.5260558225,-13.5781674675,-54.31266987,3x2x2,0.0,1.0,0.0,0.0,0.0,2.0,0.0,0.0
+SnCl4,-5.501950434999999,-1.1003900869999996,-4.202014689,-21.010073445,-84.04029378,2x2x1,0.0,1.0,0.0,0.0,0.0,4.0,0.0,0.0
+SnI4,-2.011203487500003,-0.40224069750000063,-3.2823721355,-16.4118606775,-131.29488542,3x3x3,0.0,1.0,0.0,0.0,0.0,0.0,0.0,4.0
+SnO2,-5.562294744999998,-1.8540982483333328,-8.162891905,-24.488675715,-48.97735143,4x4x6,0.0,1.0,0.0,0.0,2.0,0.0,0.0,0.0
+Ti2O3,-15.433091303333331,-3.086618260666666,-11.35938614,-56.7969307,-113.5938614,5x5x5,0.0,0.0,0.0,0.0,3.0,0.0,2.0,0.0
+Ti3O5,-25.014935754999996,-3.1268669693749995,-11.321345388125,-90.570763105,-181.14152621,6x6x3,0.0,0.0,0.0,0.0,5.0,0.0,3.0,0.0
+TiBr3,-5.346215021666666,-1.3365537554166664,-5.7537162875,-23.01486515,-46.0297303,2x2x2,0.0,0.0,3.0,0.0,0.0,0.0,1.0,0.0
+TiBr4,-6.275900536666667,-1.2551801073333333,-5.290039146,-26.45019573,-105.80078292,2x1x1,0.0,0.0,4.0,0.0,0.0,0.0,1.0,0.0
+TiCl3,-7.285464656666667,-1.8213661641666667,-6.35092272125,-25.403690885,-50.80738177,4x4x5,0.0,0.0,0.0,0.0,0.0,3.0,1.0,0.0
+TiCl4,-8.627428276666668,-1.7254856553333338,-5.880231654,-29.40115827,-117.60463308,2x1x1,0.0,0.0,0.0,0.0,0.0,4.0,1.0,0.0
+TiH2,-1.818687406666669,-0.6062291355555564,-6.59396099,-19.78188297,-19.78188297,5x5x5,0.0,0.0,0.0,2.0,0.0,0.0,1.0,0.0
+TiI3,-3.655616079166668,-0.913904019791667,-5.235810735625,-20.9432429425,-83.77297177,3x3x2,0.0,0.0,0.0,0.0,0.0,0.0,1.0,3.0
+TiI4,-3.93920481166667,-0.787840962333334,-4.721093797,-23.605468985,-47.21093797,3x3x4,0.0,0.0,0.0,0.0,0.0,0.0,1.0,4.0
+TiO2,-9.65153525916667,-3.2171784197222233,-11.281174404166668,-33.8435232125,-135.37409285,6x6x2,0.0,0.0,0.0,0.0,2.0,0.0,1.0,0.0
+Cs2SnCl6,-15.91741889758621,-1.768602099731801,-4.314860978888889,-38.83374881,-38.83374881,3x3x3,2.0,1.0,0.0,0.0,0.0,6.0,0.0,0.0
+Cs2SnI6,-9.435166387586207,-1.048351820842912,-3.410033063333333,-30.69029757,-30.69029757,3x3x3,2.0,1.0,0.0,0.0,0.0,0.0,0.0,6.0
+Cs2TiBr6,-15.275320464252871,-1.6972578293614302,-4.72867835111111,-42.55810516,-340.46484128,3x2x1,2.0,0.0,6.0,0.0,0.0,0.0,1.0,0.0
+Cs2TiBr6,-15.267895254252878,-1.6964328060280975,-4.727853327777778,-42.55067995,-42.55067995,3x3x3,2.0,0.0,6.0,0.0,0.0,0.0,1.0,0.0
+Cs2TiCl6,-18.804819815502878,-2.0894244239447644,-5.220750745694445,-46.98675671125,-375.89405369,3x2x1,2.0,0.0,0.0,0.0,0.0,6.0,1.0,0.0
+Cs2TiCl6,-18.804058564252873,-2.0893398404725416,-5.220666162222222,-46.98599546,-46.98599546,3x3x3,2.0,0.0,0.0,0.0,0.0,6.0,1.0,0.0
+Cs2TiI6,-11.468192714252876,-1.2742436349169861,-4.22099232,-37.98893088,-303.91144704,3x2x1,2.0,0.0,0.0,0.0,0.0,0.0,1.0,6.0
+Cs2TiI6,-11.459377794252877,-1.2732641993614306,-4.2200128844444444,-37.98011596,-37.98011596,3x3x3,2.0,0.0,0.0,0.0,0.0,0.0,1.0,6.0
+Cs3Ti2Cl9,-29.323364459712657,-2.0945260328366184,-5.476580519285714,-76.67212727,-153.34425454,2x2x1,3.0,0.0,0.0,0.0,0.0,9.0,2.0,0.0
+CsClO4,-4.119544711293102,-0.686590785215517,-5.9840323670833335,-35.9041942025,-143.61677681,2x2x1,1.0,0.0,0.0,0.0,4.0,1.0,0.0,0.0
+CsSn2Br5,-9.292833043793102,-1.1616041304741378,-4.080234244375,-32.641873955,-65.28374791,2x2x3,1.0,2.0,5.0,0.0,0.0,0.0,0.0,0.0
+CsSn2Cl5,-11.613319053793099,-1.4516648817241373,-4.463956683125,-35.711653465,-71.42330693,2x2x2,1.0,2.0,0.0,0.0,0.0,5.0,0.0,0.0
+CsSnBr3,-6.638688098793104,-1.3277376197586208,-4.018066186,-20.09033093,-20.09033093,8x8x8,1.0,1.0,3.0,0.0,0.0,0.0,0.0,0.0
+CsSnI3,-5.249774406293104,-1.0499548812586208,-3.6640787945,-18.3203939725,-73.28157589,3x2x1,1.0,1.0,0.0,0.0,0.0,0.0,0.0,3.0
+CsSnI3,-5.161183903793104,-1.0322367807586208,-3.6463606939999997,-18.23180347,-36.46360694,3x3x5,1.0,1.0,0.0,0.0,0.0,0.0,0.0,3.0
+CsSnI3,-5.151594576293105,-1.030318915258621,-3.6444428285,-18.2222141425,-72.88885657,3x2x2,1.0,1.0,0.0,0.0,0.0,0.0,0.0,3.0
+CsSnI3,-5.109926653793105,-1.0219853307586209,-3.636109244,-18.18054622,-18.18054622,8x8x8,1.0,1.0,0.0,0.0,0.0,0.0,0.0,3.0
+H3BrO,-4.0523989,-0.81047978,-5.059080284,-25.29540142,-25.29540142,4x4x4,0.0,0.0,1.0,3.0,1.0,0.0,0.0,0.0
+H3ClO,-4.6326153199999975,-0.9265230639999995,-5.205095308,-26.02547654,-26.02547654,4x4x4,0.0,0.0,0.0,3.0,1.0,1.0,0.0,0.0
+H7ClO3,-10.936220049999994,-0.9942018227272722,-5.63566505,-61.99231555,-123.9846311,2x2x2,0.0,0.0,0.0,7.0,3.0,1.0,0.0,0.0
+H7ClO7,-10.304044812499987,-0.6869363208333324,-5.962712423499999,-89.4406863525,-715.52549082,1x1x1,0.0,0.0,0.0,7.0,7.0,1.0,0.0,0.0
+H9BrO4,-13.502685612499992,-0.9644775437499994,-5.660038539464286,-79.2405395525,-316.96215821,2x2x1,0.0,0.0,1.0,9.0,4.0,0.0,0.0,0.0

docs/Tips.rst

@@ -337,6 +337,15 @@ PHS on the transition level diagram with a clear circle is shown on the right.
     It is recommended to additionally manually check the real-space charge density (i.e. ``PARCHG``) of
     the defect state to confirm the identification of a PHS.
 
+.. note::
+
+   As mentioned above, the eigenvalue analysis functions use code from ``pydefect``, so please cite the
+   ``pydefect`` paper if using these analyses in your work:
+
+   "Insights into oxygen vacancies from high-throughput first-principles calculations"
+   Yu Kumagai, Naoki Tsunoda, Akira Takahashi, and Fumiyasu Oba
+   Phys. Rev. Materials 5, 123803 (2021) -- 10.1103/PhysRevMaterials.5.123803
+
 Spin Polarisation
 -----------------
 Proper accounting of spin polarisation and multiplicity is crucial for accurate defect calculations and
@@ -426,9 +435,10 @@ for multiple defects.
 .. note::
 
     For magnetic competing phases, the spin configuration should also be appropriately set. ``doped`` will
-    automatically set ``NUPDOWN`` according to the magnetisation output from the ``Materials Project``
-    calculation of the competing phase, but ``MAGMOM`` may also need to be set to induce a specific spin
-    configuration.
+    automatically set ``ISPIN=2`` (allowing spin polarisation) and ``NUPDOWN`` according to the
+    magnetisation output from the ``Materials Project`` calculation of the competing phase, but ``MAGMOM``
+    (and possibly ``ISPIN``/``NUPDOWN``) may also need to be set to induce a specific spin configuration in
+    certain cases.
 
 Symmetry Precision (``symprec``)
 --------------------------------

doped/VASP_sets/RelaxSet.yaml

@@ -13,7 +13,7 @@ INCAR:
   LORBIT: 11  # lm-decomposed orbital projections; useful for DOS analysis (e.g. sumo-dosplot)
   LREAL: AUTO
   NCORE: 16
-  NEDOS: 2000  # dense energy mesh output in OUTCAR; useful for DOS analysis (e.g. sumo-dosplot)
+  NEDOS: 3000  # dense energy mesh output in OUTCAR; useful for DOS analysis (e.g. sumo-dosplot)
   NSW: 100
   PREC: Accurate
   SIGMA: 0.05