Merge pull request #83 from SMTG-Bham/develop

Update `Dimer` functionality

CHANGELOG.rst

@@ -1,6 +1,18 @@
 Change Log
 ==========
 
+v3.4.1
+----------
+- Updated handling of Dimer distortions:
+    - The default dimer bond lengths are now set to match known covalent bond lengths (e.g. for O-O, S-S,
+      O-N etc), or failing that, the sum of their covalent radii (rather than prev hard default of 2 Å).
+    - Alternatively, dimer bond lengths can be specified by the user, both in the ``distortions`` functions
+      and in the higher level ``shakenbreak.input`` functions/classes (i.e. in ``Distortions``).
+- Added ``distort_and_rattle`` convenience function to ``distortions``, to easily apply the SnB distortions
+  and rattling (where rattling is not applied to the bond-distorted atoms) to a given structure. Useful for
+  power users.
+- Minor code streamlining and simplification in ``inputs``/``distortions``.
+
 v3.4.0
 ----------
 - Major efficiency updates:

README.md

@@ -25,10 +25,12 @@ The code currently supports `VASP`, `CP2K`, `Quantum-Espresso`, `CASTEP` & `FHI-
 ![ShakeNBreak Summary](https://raw.githubusercontent.com/SMTG-Bham/ShakeNBreak/main/docs/SnB_Supercell_Schematic_PES_2sec_Compressed.gif)
 
 ### Literature
-- Preview: Mosquera-Lois, I.; Kavanagh, S. R. [In Search of Hidden Defects](https://doi.org/10.1016/j.matt.2021.06.003), _Matter_ 4 (8), 2602-2605, **2021**
-- Code: Mosquera-Lois, I. & Kavanagh, S. R.; Walsh, A.; Scanlon, D. O. [ShakeNBreak: Navigating the defect configurational landscape](https://doi.org/10.21105/joss.04817), _Journal of Open Source Software_ 7 (80), 4817, **2022**
-- Theory/Method: Mosquera-Lois, I. & Kavanagh, S. R.; Walsh, A.; Scanlon, D. O. [Identifying the Ground State Structures of Defects in Solids](https://doi.org/10.1038/s41524-023-00973-1), _npj Comput Mater_ 9, 25 **2023**
-- News & Views: Mannodi-Kanakkithodi, A. [The Devil is in the Defects](https://doi.org/10.1038/s41567-023-02049-9), _Nature Physics_ **2023** ([Free-to-read link](https://t.co/EetpnRgjzh))
+- **Preview**: Mosquera-Lois, I.; Kavanagh, S. R. [In Search of Hidden Defects](https://doi.org/10.1016/j.matt.2021.06.003), _Matter_ 4 (8), 2602-2605, **2021**
+- **Code**: Mosquera-Lois, I. & Kavanagh, S. R.; Walsh, A.; Scanlon, D. O. [ShakeNBreak: Navigating the defect configurational landscape](https://doi.org/10.21105/joss.04817), _Journal of Open Source Software_ 7 (80), 4817, **2022**
+- **Theory/Method**: Mosquera-Lois, I. & Kavanagh, S. R.; Walsh, A.; Scanlon, D. O. [Identifying the Ground State Structures of Defects in Solids](https://doi.org/10.1038/s41524-023-00973-1), _npj Comput Mater_ 9, 25 **2023**
+- **News & Views**: Mannodi-Kanakkithodi, A. [The Devil is in the Defects](https://doi.org/10.1038/s41567-023-02049-9), _Nature Physics_ **2023** ([Free-to-read link](https://t.co/EetpnRgjzh))
+- **YouTube Overview (10 mins)**: [ShakeNBreak: Symmetry-Breaking and Reconstruction at Defects in Solids](https://www.youtube.com/watch?v=aqXlyLofLSU&ab_channel=Se%C3%A1nR.Kavanagh)
+- **YouTube Seminar (35 mins)**: [Seminar: Predicting the Atomic Structures of Defects](https://www.youtube.com/watch?v=u7CdhI_1S18&ab_channel=Se%C3%A1nR.Kavanagh)
 
 ## Installation
 `ShakeNBreak` can be installed using `conda`:
@@ -52,23 +54,6 @@ PMG_VASP_PSP_DIR: <Path to VASP pseudopotential top directory>
 
 The font Montserrat ([Open Font License](https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL)) will be installed with the package, and will be used by default for plotting.
 
-### Developer installation
-For development work, ShakeNBreak can also be installed from a copy of the source directory:
-
-1. Download `ShakeNBreak` source code using the command:
-```bash
-git clone https://github.com/SMTG-Bham/ShakeNBreak
-```
-2. Navigate to root directory:
-```bash
-cd ShakeNBreak
-```
-3. Install the code, using the command:
-```bash
-pip install -e .
-```
-   This command tries to obtain the required packages and their dependencies and install them automatically.
-
 
 ## Usage
 
@@ -92,45 +77,16 @@ The functions provided include:
 More information about each function and its inputs/outputs are available from the [CLI section of the docs](https://shakenbreak.readthedocs.io/en/latest/shakenbreak.cli.html#commands) or using `-h` help option (e.g. `snb -h`).
 
 We recommend at least looking through the [tutorials](https://shakenbreak.readthedocs.io/en/latest/Tutorials.html) when first starting to use `ShakeNBreak`, to familiarise yourself with the full functionality and workflow.
-
-## Code Compatibility
-`ShakeNBreak` is built to natively function using `pymatgen` `Defect` objects ([docs available here](https://materialsproject.github.io/pymatgen-analysis-defects/)) and be compatible with the most recent version of `pymatgen`.
-If you are receiving `pymatgen`-related errors when using `ShakeNBreak`, you may need to update `pymatgen` and/or `ShakeNBreak`, which can be done with:
-```bash
-pip install --upgrade pymatgen shakenbreak
-```
-
-`ShakeNBreak` can take `pymatgen` `Defect` objects as input (to then generate the trial distorted structures),
-**_but also_** can take in `pymatgen` `Structure` objects, `doped` defects or structure files
-(e.g. `POSCAR`s for `VASP`) as inputs. As such, it should be compatible with any defect code
-(such as [`doped`](https://doped.readthedocs.io), [`pydefect`](https://github.com/kumagai-group/pydefect),
-[`PyCDT`](https://github.com/mbkumar/pycdt), [`PyLada`](https://github.com/pylada/pylada-defects),
-[`DASP`](http://hzwtech.com/files/software/DASP/htmlEnglish/index.html), [`Spinney`](https://gitlab.com/Marrigoni/spinney/-/tree/master),
-[`DefAP`](https://github.com/DefAP/defap), [`PyDEF`](https://github.com/PyDEF2/PyDEF-2.0)...) that generates these files.
-Please let us know if you have any issues with compatibility, or if you would like to see any additional features added to `ShakeNBreak` to make it more compatible with your code.
-
-## Contributing
-
-### Bugs reports, feature requests and questions
-Please use the [Issue Tracker](https://github.com/SMTG-Bham/ShakeNBreak/issues) to report bugs or request new features.
-
-Contributions to extend this package are very welcome! Please use the
-["Fork and Pull"](https://docs.github.com/en/get-started/quickstart/contributing-to-projects)
-workflow to do so and follow the [PEP8](https://peps.python.org/pep-0008/) style guidelines.
-
-See the [Contributing Documentation](https://shakenbreak.readthedocs.io/en/latest/Contributing.html) for detailed instructions.
-
-### Tests
-Unit tests are in the `tests` directory and can be run from the top directory using [unittest](https://docs.python.org/3/library/unittest.html).
-Automatic testing is run on the master and develop branches using Github Actions. Please run tests and add new tests for any new features whenever submitting pull requests.
-
-## Acknowledgements
-`ShakeNBreak` has benefitted from feedback from many members of the Walsh and Scanlon research groups who have used / are using it in their work, including Adair Nicolson, Xinwei Wang, Katarina Brlec, Joe Willis, Zhenzhu Li, Jiayi Cen, Lavan Ganeshkumar, Daniel Sykes, Luisa Herring-Rodriguez, Alex Squires, Sabrine Hachmioune and Chris Savory.
+You may also find the
+[YouTube Overview (10 mins)](https://www.youtube.com/watch?v=aqXlyLofLSU&ab_channel=Se%C3%A1nR.Kavanagh),
+[YouTube Seminar (35 mins)](https://www.youtube.com/watch?v=u7CdhI_1S18&ab_channel=Se%C3%A1nR.Kavanagh)
+and/or papers listed in the [Literature](#literature) section above useful.
 
 ## Studies using `ShakeNBreak`
 
 - Y. Fu & H. Lohan et al. **_Factors Enabling Delocalized Charge-Carriers in Pnictogen-Based
 Solar Absorbers: In-depth Investigation into CuSbSe<sub>2</sub>_** [_Nature Communications_](https://doi.org/10.1038/s41467-024-55254-2) 2025
+- Y\. Liu **_Small hole polarons in yellow phase δ-CsPbI<sub>3</sub>_** [_arXiv_](https://doi.org/10.48550/arXiv.2501.16695) 2025
 - S. R. Kavanagh **_Identifying Split Vacancies with Foundation Models and Electrostatics_** [_arXiv_](https://doi.org/10.48550/arXiv.2412.19330) 2025
 - S. R. Kavanagh et al. **_Intrinsic point defect tolerance in selenium for indoor and tandem photovoltaics_** [_ChemRxiv_](https://doi.org/10.26434/chemrxiv-2024-91h02) 2025
 - J. Hu et al. **_Enabling ionic transport in Li<sub>3</sub>AlP<sub>2</sub> the roles of defects and disorder_** [_Journal of Materials Chemistry A_](https://doi.org/10.1039/D4TA04347B) 2025
@@ -162,14 +118,11 @@ Solar Absorbers: In-depth Investigation into CuSbSe<sub>2</sub>_** [_Nature Comm
 - (News & Views): A. Mannodi-Kanakkithodi **_The devil is in the defects_** [_Nature Physics_](https://doi.org/10.1038/s41567-023-02049-9) 2023 ([Free-to-read link](https://t.co/EetpnRgjzh))
 
 <!-- Wenzhen paper -->
-<!-- Se -->
 <!-- Oba book -->
 <!-- BiOI -->
 <!-- Kumagai collab paper -->
-<!-- Lavan LiNiO2 -->
 <!-- Sykes Magnetic oxide polarons -->
 <!-- Kat YTOS -->
-<!-- Squires (and mention benchmark test against AIRSS? See Slack message) -->
 
 ## License and Citation
 ShakeNBreak is made available under the MIT License.
@@ -183,14 +136,31 @@ You may also find this Preview paper useful, which discusses the general problem
 
 `BibTeX` entries for these papers are provided in the [`CITATIONS.md`](CITATIONS.md) file.
 
-## Requirements
-`ShakeNBreak` is compatible with Python 3.9 - 3.12 and requires the following open-source python packages:
-* [Pymatgen](https://pymatgen.org/)
-* [Ase](https://wiki.fysik.dtu.dk/ase/)
-* [Hiphive](https://hiphive.materialsmodeling.org/)
-* [Numpy](https://numpy.org/)
-* [Matplotlib](https://matplotlib.org/)
-* [Pandas](https://pandas.pydata.org/)
-* [Seaborn](https://seaborn.pydata.org/)
-* [Monty](https://pythonhosted.org/monty/index.html)
-* [Click](https://click.palletsprojects.com/en/8.1.x/)
+## Code Compatibility
+`ShakeNBreak` is built to natively function using [`doped`](https://doped.readthedocs.io) / [`pymatgen`](https://materialsproject.github.io/pymatgen-analysis-defects/) `Defect` objects and be compatible with the most recent version of `pymatgen`.
+If you are receiving `pymatgen`-related errors when using `ShakeNBreak`, you may need to update `pymatgen` and/or `ShakeNBreak`, which can be done with:
+```bash
+pip install -U pymatgen shakenbreak
+```
+
+`ShakeNBreak` is compatible with a variety of inputs (to then generate the trial distorted structures), including  [`doped`](https://doped.readthedocs.io) / [`pymatgen`](https://materialsproject.github.io/pymatgen-analysis-defects/) `Defect` objects, `pymatgen` `Structure` objects or structure files
+(e.g. `POSCAR`s for `VASP`). As such, it should be compatible with any defect code
+(such as [`doped`](https://doped.readthedocs.io), [`pydefect`](https://github.com/kumagai-group/pydefect),
+[`PyCDT`](https://github.com/mbkumar/pycdt), [`PyLada`](https://github.com/pylada/pylada-defects),
+[`DASP`](http://hzwtech.com/files/software/DASP/htmlEnglish/index.html), [`Spinney`](https://gitlab.com/Marrigoni/spinney/-/tree/master),
+[`DefAP`](https://github.com/DefAP/defap), [`PyDEF`](https://github.com/PyDEF2/PyDEF-2.0)...) or manual defect supercell generation.
+Please let us know if you have any issues with compatibility, or if you would like to see any additional features added to `ShakeNBreak` to make it more compatible with your code.
+
+## Acknowledgements
+`ShakeNBreak` has benefitted from feedback from many members of the Walsh and Scanlon research groups who have used / are using it in their work, including Adair Nicolson, Xinwei Wang, Katarina Brlec, Joe Willis, Zhenzhu Li, Jiayi Cen, Lavan Ganeshkumar, Daniel Sykes, Luisa Herring-Rodriguez, Alex Squires, Sabrine Hachmioune and Chris Savory.
+
+## Contributing
+
+### Bugs reports, feature requests and questions
+Please use the [Issue Tracker](https://github.com/SMTG-Bham/ShakeNBreak/issues) to report bugs or request new features.
+
+Contributions to extend this package are very welcome! Please use the
+["Fork and Pull"](https://docs.github.com/en/get-started/quickstart/contributing-to-projects)
+workflow to do so and follow the [PEP8](https://peps.python.org/pep-0008/) style guidelines.
+
+See the [Contributing Documentation](https://shakenbreak.readthedocs.io/en/latest/Contributing.html) for detailed instructions.

docs/Contributing.rst

@@ -50,6 +50,6 @@ Tests
 -------
 
 Unit tests are in the `tests <https://github.com/SMTG-Bham/ShakeNBreak/tree/main/tests>`_ directory
-and can be run from the top directory using ``unittest``. Automatic testing is run on the master and
-develop branches using `Github Actions <https://docs.github.com/en/actions>`_. Please
-run tests and add new tests for any new features whenever submitting pull requests.
+and can be run from the top directory using ``pytest`` or ``unittest``. Automatic testing is run upon
+pushes to all branches using `Github Actions <https://docs.github.com/en/actions>`_. Please run tests and
+add new tests for any new features whenever submitting pull requests.