kpt/symmetry/dipole documentation update

.github/workflows/doc.yml

@@ -26,6 +26,7 @@ jobs:
     - name: sphinx
       run: |
         pip install sphinx-rtd-dark-mode
+        pip install sphinx_favicon
         make latexpdf
         cp _build/latex/ONETEP_Documentation.pdf  _static/
         make html

conf.py

@@ -33,6 +33,7 @@
 # ones.
 extensions = ['sphinx.ext.mathjax']
 extensions += ["sphinx_rtd_dark_mode"]
+extensions += ["sphinx_favicon"]
 default_dark_mode = False
 
 # Add any paths that contain templates here, relative to this directory.
@@ -49,15 +50,15 @@
 
 # General information about the project.
 project = 'ONETEP Documentation'
-copyright = '2022-2023, Joseph Prentice'
-author = 'ONETEP Developers\' Group: Jacek Dziedzic, Peter Haynes, Nicholas Hine, Arash Mostofi, Mike Payne, and Chris-Kriton Skylaris. Documentation by Joseph Prentice'
+copyright = '2022-2025, ONETEP Developers\' Group'
+author = 'ONETEP Developers\' Group: Jacek Dziedzic, Peter Haynes, Nicholas Hine, Arash Mostofi, Mike Payne, and Chris-Kriton Skylaris.'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '7.1'
+version = '7.3'
 # The full version, including alpha/beta/rc tags.
 release = '7.1.8'
 
@@ -88,6 +89,16 @@
 # a list of builtin themes.
 #
 html_theme = 'alabaster'
+html_logo = '_static/onetep_logo.png'
+html_theme_options = {
+    'logo_only': True,
+    'display_version': True,
+}
+
+# --- Favicon ---
+favicons = [
+    "favicon.ico",
+]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -147,7 +158,7 @@
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
     (master_doc, 'ONETEP_Documentation.tex', 'ONETEP Documentation',
-     'Joseph Prentice', 'manual'),
+     'ONETEP Developers\'s Group', 'manual'),
 ]
 
 

dipole_correction.rst

@@ -0,0 +1,105 @@
+=================
+Dipole correction
+=================
+
+:Author: Chengcheng Xiao
+:Date:   November 2025
+
+Dipole correction
+=================
+
+When the system has a net dipole, the electric field generated by it will incur
+spurious interaction across periodic images, especially when there's not enough
+vacuum space. The goal of applying dipole correction to ONETEP is to eliminate
+this effect. An alternative way is to employ coulomb cut-off.
+
+The net dipole moment :math:`\mu` can be easily calculated as,
+
+.. math::
+
+   \boldsymbol{\mu} = \int_\mathrm{cell} \rho(\mathbf{r}) \mathbf{r} d\mathbf{r}
+
+where the total charge density $\rho(\mathbf{r})$ can be decomposed as the
+contribution from the electrons and ions (in units of e*Bohr):
+
+.. math::
+
+   \rho(\mathbf{r}) = -\rho_\mathrm{el}(\mathbf{r}) + \rho_\mathrm{ion}(\mathbf{r})
+
+Correspondingly, the electric field created by this dipole moment can be
+expressed as (in units of Hartree/Bohr)
+
+.. math::
+
+   \mathbf{E} = 4\pi(\boldsymbol{\mu}/\Omega)
+
+To eliminate this effect, we can insert a dipole layer (by directly manipulating
+the external potential) along certain direction. This is done in the spirit of
+`Jörg Neugebauer and Matthias Scheffler <https://doi.org/10.1103/PhysRevB.46.16067>`__. 
+For now, the dipole
+correction only supports slab calculation (or equivlant) and can only be applied
+to the vacuum direction prependicular to the other two directions. Note that you
+cell can be tilted but as long as the Cartesian direction specified for the
+dipole correction is prependicular to the periodic cell direction, the result is
+correct. The added electric field generates a potential that takes the following
+form (assuming z direction):
+
+.. math::
+
+   V_\mathrm{dipole}(z) = -4\pi(\boldsymbol{\mu}/\Omega)_z \cdot z
+
+Following the same logic, one can add an external electric field by:
+
+.. math::
+
+   \mathbf{E} = 4\pi(\boldsymbol{\mu}/\Omega) + \mathbf{E}_\mathrm{ext}
+
+and in this case, dipole correction could and should be added to make sure the
+results are correct.
+
+Finally, after running ground state calculation with dipole correction, the
+total energy reported in the output file will contain the contribution from the
+dipole layer. Furthermore, the output potential will also include the dipole
+layer contribution.
+
+In ONETEP, dipole correction can be added by 
+
+.. code::
+
+   dipole_correction : T
+
+and the correction direction is set by 
+
+.. code::
+
+   dipole_correction_dir : 3
+
+The location of the dipole layer is set by 
+
+.. code::
+
+   efield_origin : 0.0 0.0 0.0
+
+And a constant external electric field can be added as
+
+.. code::
+
+   constant_efield : 0.0 0.0 1.0
+
+
+Keywords
+========
+
+- ``dipole_correction``: [Basic, bool, default ``F``\ ] Whether to use dipole
+  correction or not.
+
+- ``dipole_correction_dir``: [Basic, integer, define ``3``\ ] Direction along
+  which the dipole correction is applied. ``1``\ , ``2``\ , ``3``\  correspond
+  to x, y, z directions respectively.
+
+- ``efield_origin``: [Basic, float float float, default 0.0 0.0 0.0] Location of
+  the dipole layer.
+
+- ``constant_efield``: [Basic, float float float, default 0.0 0.0 0.0] Constant
+  external electric field to be added.
+

index_ground_state.rst

@@ -23,6 +23,7 @@ Ground State Calculation Setup
    implicit_solvation_v3.rst
    hfx.rst
    cutoff_coulomb.rst
+   dipole_correction.rst
    scissor_operator.rst
    EMFT_in_ONETEP.rst
 

kpoints_and_spin.rst

@@ -308,9 +308,9 @@ where :math:`q` is the number of k-points in each direction and :math:`r` is the
 k-point index. An optional shift of half a grid cell can be added so
 that :math:`\Gamma` point is included in the sampling.
 
-There are two ways to define the k-point sampling in ONETEP:
+There are two ways to define the k-point grid in ONETEP:
 
-1. Automatic generation using the Monkhorst-Pack scheme.:
+1. Automatic generation using the Monkhorst-Pack scheme:
 
    ::
 
@@ -321,6 +321,21 @@ There are two ways to define the k-point sampling in ONETEP:
    along b direction (shifted by half a grid distance) and 6 along c direction
    (also shifted by half a grid distance).
 
+   Alternatively, one can set the grid spacing in units of 1/Bohr and a grid
+   that fits within the specified spacing will be generated: 
+
+   ::
+
+      kpoint_grid_spacing : 0.1 1/Bohr
+
+   Optionally, one can force the generated grid to include the Gamma point by:
+
+   ::
+
+      kpoint_gamma_centred : T
+
+   which will override any shifts specified in `kpoint_grid_shift`.
+
 
 2. Manual generation using the k-point coordinates:
 
@@ -442,22 +457,28 @@ pseudopotentials. Here's a brief list of supported functionalities:
 Keywords
 ========
 
--  ``extended_ngwf`` [Basic, bool bool bool, default ``F F F``\ ]. Turn on 
+-  ``extended_ngwf`` [Basic, bool bool bool, default ``F F F``\ ] Turn on 
    extended NGWFs along the three directions.
 
--  ``kpoint_method`` [Basic, default ``None``\ ]. The method used to generate 
+-  ``kpoint_method`` [Basic, string, default ``None``\ ] The method used to generate 
    the k-point grid. The options are:
 
    -  ``PW``: Plane-wave mode. Requires NGWFs to be extended along the periodic
       directions where k-point sampling is applied.
    -  ``TB``: Tight-Binding mode. Requires NGWFs to be fully localised.
    -  ``None``: No k-point sampling.
 
-- ``kpoint_grid_shift`` [Basic int int int, default ``0 0 0``\ ]. The shift of 
+- ``kpoint_grid_shift`` [Basic int int int, default ``0 0 0``\ ] The shift of 
   the k-point grid.
 
-- ``kpoint_grid_size`` [Basic int int int, default ``1 1 1``\ ]. The size of 
+- ``kpoint_grid_size`` [Basic int int int, default ``1 1 1``\ ] The size of 
   the k-point grid.
 
-- ``num_kpars`` [Basic int, default ``1``\ ]. The number of k-parallelisation
+- ``kpoint_grid_spacing`` [Basic float 1/Bohr, default ``0.0 1/Bohr``\ ] The
+  spacing of the k-point grid in units of 1/Bohr.
+
+- ``kpoint_gamma_centred`` [Basic, bool, default ``F``\ ] Whether to force the
+  generated k-point grid to be Gamma-centred.
+
+- ``num_kpars`` [Basic int, default ``1``\ ] The number of k-parallelisation
   groups.