Add troubleshooting note about mis-matching bulk/defect supercells

docs/Dev_ToDo.md

@@ -13,7 +13,6 @@
   - 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!  
   - Separate `dist_tol` for interstitials vs (inequivalent) vacancies/substitutions? (See Xinwei chat) Any other options on this front?
   - Also see Fig. 6a of the `AiiDA-defects` preprint, want plotting tools like this
-- Could add support for bulk supercells which mis-match the defect supercells, using the `orient_s2_like_s1` functions in `configurations` (to get the transformed bulk), and then atom mapping to account for eFNV corrections (site potentials), and can transform `LOCPOT` data for FNV correction with e.g. https://github.com/materialsproject/pyrho/blob/2c35912d667e65d7f9d54d63a3693ad6e014a401/src/pyrho/charge_density.py#L365 – but, a lot of work for (hopefully) a rare use case (sometimes caused by mismatching versions) and minimal extra work to fix (user just needs to recalculate bulk single-shot). Maybe just add a note to troubleshooting page about this warning and how it can be fixed using `orient_s2_like_s1` to get the corresponding bulk supercell? (TODO!)
 - Kumagai GKFO and CC diagram corrections. Implemented in `pydefect` and relatively easy to port?
 - 2D corrections; like `pydefect_2d`, or recommended to use SCPC in VASP?
 - 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

docs/Troubleshooting.rst

@@ -5,7 +5,6 @@ Troubleshooting & Support
 
 ``doped``/``pymatgen`` Errors
 -----------------------------
-
 For most error cases, ``doped`` has been designed to try and give informative error messages about why
 the functions are failing.
 In the majority of cases, if you encounter an error using ``doped`` which does not have a clear error
@@ -26,7 +25,6 @@ please contact the developers through the
 
 Parsing Errors
 --------------
-
 If errors occur during parsing of defect calculations, ``doped`` will try to informatively warn you about
 the origin of the parsing failure (e.g. ``Parsing failed for [...] with the same error: ...``).
 Depending on what the error is, this error message on its own may not be very helpful. In these cases, it's
@@ -41,6 +39,67 @@ error traceback.
     corrupted/incomplete ``vasprun.xml(.gz)`` file, for which the solution is to re-run the VASP
     calculation to obtain the appropriate output.
 
+Mis-matching Bulk and Defect Supercells
+----------------------------------------
+When parsing defect calculations with ``doped``, if you provide bulk and defect supercells which do not
+match, you will see the following warning:
+
+.. code::
+
+    Detected atoms far from the defect site (>X Å) with major displacements (>0.5 Å) in the defect
+    supercell. This likely indicates a mismatch between the bulk and defect supercell definitions or an
+    unconverged supercell size, both of which could cause errors in parsing. The mean displacement of the
+    following species, at sites far from the determined defect position, is >0.5 Å: ...
+
+This can sometimes happen due to the use of a bulk supercell which does not match the atomic positions of
+the defect supercell, but is symmetry-equivalent by a translation and/or rotation. This causes issues for
+determining the defect position in the supercell, and for calculating charge corrections which rely on
+differences in electrostatic potential between the bulk and defect supercells. ``doped`` will never output
+mis-matching bulk and defect supercells, but this can occur from accidental combination of outputs from
+old and newer versions, or separate manual calculations of bulk supercells etc.
+
+The easiest solution is to generate the bulk supercell which corresponds to the defect supercell
+definitions:
+
+.. code:: python
+
+    from pymatgen.core.structure import Structure
+    from doped.utils.configurations import orient_s2_like_s1
+
+    # Load the bulk and defect supercells
+    defect_supercell = Structure.from_file("...")
+    bulk_supercell = Structure.from_file("...")  # which mis-matches the defect supercell
+
+    # orient the bulk supercell to match the defect supercell:
+    # for this, we need to 'reverse' the defect formation in the defect supercell, to get
+    # a supercell with the bulk composition that can then be used as a rough template.
+    # in this example case we add a site because the defect supercell is an oxygen vacancy,
+    # but for interstitials you would remove a site (with Structure.remove(...)) and for
+    # substitutions you would replace a site (with Structure.replace(...)).
+    defect_supercell_w_bulk_comp = defect_supercell.copy()
+    defect_supercell_w_bulk_comp.append("O", [0.5, 0.5, 0.5])  # add element to remove vacancy
+    # defect frac coords are given in the POSCAR comment
+
+    oriented_bulk_supercell = orient_s2_like_s1(defect_supercell_w_bulk_comp, bulk_supercell)
+    oriented_bulk_supercell.to(fmt="POSCAR", filename="oriented_bulk_POSCAR")
+
+With this re-generated matching bulk supercell, we just need to run the single-point bulk calculation, and
+use this matching-supercell calculation for defect parsing.
+
+If for some reason you have different supercell definitions for different sets of defect calculations, you
+can use different bulk supercells (which match the corresponding set of defect supercells) and combine them
+using something like:
+
+.. code:: python
+
+    from doped.analysis import DefectsParser
+    from doped.thermodynamics import DefectThermodynamics
+
+    dp_1 = DefectsParser("Defects_Calcs_Supercell_1", bulk_path="Bulk_Supercell_1", dielectric=dielectric)
+    dp_2 = DefectsParser("Defects_Calcs_Supercell_2", bulk_path="Bulk_Supercell_2", dielectric=dielectric)
+
+    thermo = DefectThermodynamics([*dp_1.defect_entries.values(), *dp_2.defect_entries.values()], chempots...)
+
 
 ``numpy`` Errors
 -------------------