diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 7c99f17..3c96edb 100644
--- a/.github/workflows/doc.yml
+++ b/.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
diff --git a/_static/favicon.ico b/_static/favicon.ico
new file mode 100644
index 0000000..1053f25
Binary files /dev/null and b/_static/favicon.ico differ
diff --git a/_static/onetep_logo.png b/_static/onetep_logo.png
new file mode 100644
index 0000000..c2c9674
Binary files /dev/null and b/_static/onetep_logo.png differ
diff --git a/_static/onetep_logo.svg b/_static/onetep_logo.svg
new file mode 100644
index 0000000..9a4d5a2
--- /dev/null
+++ b/_static/onetep_logo.svg
@@ -0,0 +1,101 @@
+
+
diff --git a/conf.py b/conf.py
index c76d348..1f3338f 100644
--- a/conf.py
+++ b/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'),
]
diff --git a/dipole_correction.rst b/dipole_correction.rst
new file mode 100644
index 0000000..8424210
--- /dev/null
+++ b/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 `__.
+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.
+
diff --git a/index_ground_state.rst b/index_ground_state.rst
index 4ca03b5..58bf426 100644
--- a/index_ground_state.rst
+++ b/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
diff --git a/kpoints_and_spin.rst b/kpoints_and_spin.rst
index 037c991..70e0a79 100644
--- a/kpoints_and_spin.rst
+++ b/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,10 +457,10 @@ 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
@@ -453,11 +468,17 @@ Keywords
- ``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.
diff --git a/symmetry.rst b/symmetry.rst
index bf63ba2..355bd94 100644
--- a/symmetry.rst
+++ b/symmetry.rst
@@ -11,7 +11,7 @@ Symmetry operations in ONETEP
Crystal symmetry operations can be defined using rotation and translation pairs.
In ONETEP, symmetry operations (in fractional coordinates) are obtained by
passing the crystal information (lattice, ionic positions, and types) to
-`spglib `.
+`spglib `__.
These operations can then be used to find symmetry-related k-points:
@@ -68,31 +68,32 @@ commensurate with the total number of non-primitive translations, it will have
zero amplitude so we can **avoid** applying symmetry operations to these
G-vectors altogether.
-Magnetic symmetry operations
-============================
+Symmetry operations reductions
+==============================
-Magnetic moments can affect the symmetry operations in a crystal. Specifically,
-the presence of certain magnetic moments can lead to the existence of additional
-symmetry operations - Time-reversal operations that swap the spin components of
-the wavefunctions.
+In ONETEP, the default crystal symmetry is detected by pseudopotential types
+instead of species labels. This ensures that if the symmetry is not broken even
+if user has specified different species labels for atoms with the same
+pseudopotential and initial configurations.
-In ONETEP, instead of using full time-reversal operations to symmetrise the spin
-polarised charge density, the entire crystal symmetry is lowered by treating the
-atoms that belong to the same species but have different **initial** magnetic
-moments as if they belong to different species.
+It is important to know that initial atomic configurations can affect the
+symmetry operations in a crystal. For example, the presence of certain magnetic
+moments can lead to the existence of additional symmetry operations -
+Time-reversal operations that swap the spin components of the wavefunctions.
-Doing this allows the possibility for the lower symmetry magnetic structure
-(such as antiferromagnetic) to relax into a higher symmetry structure (such as
+In ONETEP, the entire crystal symmetry is lowered by treating the atoms that
+belong to the same species but have different **initial** configurations (e.g.,
+magnetic moments) as if they belong to different species. Doing this allows the
+possibility for the lower symmetry magnetic structure (such as
+antiferromagnetic) to relax into a higher symmetry structure (such as
ferrimagnetic).
-
This is done automatically by ONETEP when the ``use_symmetry`` keyword is set to
-``True`` and the ``use_time_reversal`` keyword is set to ``True`` and ``LOCK
-SPECIES_ATOMIC_SET`` is used to specify different initial magnetic moments for
-different atoms of the same species (for more, see
-:ref:`initial-guess-density-setting-initial-charges-and-spins`). If the initial
-magnetic moments do change the symmetry, ONETEP will report the symmetry
-operations written:
+``True`` and ``SPECIES_ATOMIC_SET`` is used to specify different initial
+configurations for different atoms of the same species (how this is done is
+documented in :ref:`initial-guess-density-setting-initial-charges-and-spins`).
+If the initial configurations such as magnetic moments do change the symmetry,
+ONETEP will report the symmetry operations written:
.. code::
@@ -109,6 +110,9 @@ ONETEP now ships with spglib and can be enabled by ``BUILD_SPGLIB=yes``, i.e.,
make onetep ARCH=YOUR_ARCH BUILD_SPGLIB=yes
+This is by default turned on, and you can turn it off by setting
+``BUILD_SPGLIB=no``.
+
You can also change the C-compiler by setting the ``CC`` environment variable in
your ARCH file, e.g.,
@@ -124,22 +128,22 @@ keyword to ``True``. To leverage the time-reversal symmetry to reduce the number
of k-points, the ``use_time_reversal`` keyword can also be set to `True`.
One thing to note is that only MP grids set up by ``kpoint_grid_size`` will get
-symmetrised. User-supplied k-point list (via ``block kpoints_list``) will not be
-modified.
+symmetrised (i.e., reduced by applying symmetry). User-supplied k-point list
+(via ``block kpoints_list``) will not be modified.
-Once these tags are set, ONETEP will report the symmetry operations and the
-reduced k-points in the output file (if ``output_detail`` is set to
-``verbose``), and the symmetry-related k-points will be used in the calculation.
+Once these tags are set (along with ``output_detail`` set to ``verbose``),
+ONETEP will report the symmetry operations and the reduced k-points in the
+output file, and the symmetry-related k-points will be used in the calculation.
Keywords
========
-- ``use_symmetry``: [bool] turn symmetry on or off (only works if compiled with
- spglib) | default: off
+- ``use_symmetry``: [Basic, bool, default ``F``\ ] Whether to use symmetry or
+ not (only works if compiled with spglib)
-- ``use_time_reversal`` : [bool] use TRS to reduce the number of k-points or not |
- default: on
+- ``use_time_reversal``: [Basic, bool, define ``T``\ ] use TRS to reduce the
+ number of k-points or not.
-- ``symmetry_tol``: [float] Precision in determining the symmetry. | default:
- 0.001889726 Bohr (0.001 Å)
+- ``symmetry_tol``: [Basic, float, default 0.001889726 Bohr (0.001 Å)] Precision
+ in determining the symmetry.