OrderN · davidbowler · Feb 27, 2026 · May 18, 2022 · May 19, 2022 · May 19, 2022
diff --git a/.github/workflows/makefile.yml b/.github/workflows/makefile.yml
@@ -142,6 +142,12 @@ jobs:
         mpirun -np ${{matrix.np}} ../../bin/Conquest
         cat Conquest_out
 
+    - name: Run test 008
+      working-directory: ${{github.workspace}}/testsuite/test_008_surface_dipole
+      run: |
+        mpirun -np ${{matrix.np}} ../../bin/Conquest
+        cat Conquest_out
+
     - name: Check test results
       working-directory: ${{github.workspace}}/testsuite
       run: pytest test_check_output.py
diff --git a/README.md b/README.md
@@ -50,4 +50,4 @@ DOI for the specific version you have used in any given study.
 
 ## Version number
 
-CONQUEST is now at version 1.4 (tag:v1.4)
+CONQUEST is now at version 1.5 (tag:v1.5)
diff --git a/docs/conf.py b/docs/conf.py
@@ -55,17 +55,17 @@
 
 # General information about the project.
 project = u'CONQUEST'
-copyright = u'2018-2024, CONQUEST Developers'
+copyright = u'2018-2026, CONQUEST Developers'
 author = u'CONQUEST Developers'
 
 # 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 = u'1.4'
+version = u'1.5'
 # The full version, including alpha/beta/rc tags.
-release = u'1.4'
+release = u'1.5'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/docs/groundstate.rst b/docs/groundstate.rst
@@ -185,7 +185,7 @@ for the block size of the matrix, specify the following two variables.
   Diag.BlockSizeC       20
 
 Note that these two numbers should be the same when padding 
-(and when using ELPA which will be introduced to CONQUEST soon).
+(and when using ELPA as described below).
 We suggest that an appropriate value is between 20 and 200, but 
 this should be tested. 
 
@@ -197,6 +197,26 @@ like to remove it, set the following variable.
   Diag.PaddingHmatrix              F 
 
 
+Go to :ref:`top <groundstate>`
+
+.. _gs_diag_elpa:
+
+Using ELPA
+~~~~~~~~~~
+
+`ELPA <https://elpa.mpcdf.mpg.de/>`_ is an alternative to ScaLAPACK for
+diagonalisation which can show better parallelisation, and allows use of
+GPU cards for acceleration (though the GPU implementation in CONQUEST is
+at a very early stage).  To enable ELPA and GPUs, set the following tags:
+
+ ::
+
+  Diag.UseELPA T
+  Diag.ELPA_GPU T
+
+Some care is needed in the balance between MPI processes and number of GPUs
+on the compute nodes: careful testing is important.
+
 Go to :ref:`top <groundstate>`.
 
 .. _gs_on:
@@ -410,6 +430,34 @@ beyond the valence electrons.
 
 Go to :ref:`top <groundstate>`.
 
+.. _gs_surf_dip:
+
+Surface dipole correction
+-------------------------
+
+If your simulation involves a slab calculation, then unless the slab is
+perfectly symmetrical there can be a dipole moment which gives an unphysical
+field across the periodic cell even for a neutral system.  A correction can be applied, following the
+method outlined in :cite:`g-Neugebauer1992,g-Bengtsson1999` (where we use the energy from the
+Bengtsson paper, which is correct).  This method *only* works for slab
+calculations, and calculates a dipole correction potential, placing the
+necessary discontinuity in the vacuum.  The user can specify the location
+of the discontinuity (in *fractional* coordinates), or the code will place it at the point where the
+planar averaged density is a minimum (which is a good way to find the
+centre of the vacuum).
+
+::
+
+   SC.SurfaceDipoleCorrection T/F
+   SC.SurfaceNormal x, y, or z
+   SC.DiscontinuityLocation (*real*)
+
+It is also possible to write out the planar-averaged potential and charge density
+(averaged in the plane perpendicular to the surface normal) using the parameter
+``SC.OutputAveragePotential T/F``.  This generates the file ``AveragedPotential.dat``.
+
+Go to :ref:`top <groundstate>`.
+
 .. _gs_spin:
 
 Spin polarisation

diff --git a/docs/input_tags.rst b/docs/input_tags.rst
@@ -951,25 +951,26 @@ AtomMove.OptCell.Constraint (*string*)
 
     *Fixing a single cell dimension:*
 
-    a: Fix the x-dimension of the simulation box
+    ``a``: Fix the x-dimension of the simulation cell
 
-    b: Fix the y-dimension of the simulation box
+    ``b``: Fix the y-dimension of the simulation cell
 
-    c: Fix the z-dimension of the simulation box
+    ``c``: Fix the z-dimension of the simulation cell
 
     *Fixing multiple cell dimensions:*
 
-    any combination of the above separated by a space character. e.g: "a b" fixes
-    both the x and y dimensions of the simulation box
+
+    Any combination of the above separated by a space character. e.g: ``a b`` fixes
+    both the x- and y-dimensions of the simulation cell.
 
     *Fixing Ratios:*
 
-    Any combination of a, b or c separated by a "/" character. e.g "c/a" fixes
-    the initial ratio of the z-dimension to the x-direction.
+    Any combination of a, b or c separated by a "/" character, e.g ``c/a`` fixes
+    the initial ratio of the z-dimension to the x-dimension.
 
     *Global scaling factor:*
 
-    volume: minimize the total energy by scaling each simulation box dimension by
+    ``volume``: minimize the total energy by scaling each simulation cell dimension by
     the same global scaling factor. Search directions are set by the mean stress.
 
 AtomMove.TestSpecificForce (*integer*)

diff --git a/docs/installing.rst b/docs/installing.rst
@@ -43,8 +43,10 @@ a working MPI installation including a Fortran90 compiler (often
   can be obtained from `the netlib repository <http://www.netlib.org/scalapack/>`_ if
   you need to compile it)
 
-Additionally, Conquest can use LibXC if it is available (v4.x or
-later).
+Additionally, Conquest can use `ELPA <https://elpa.mpcdf.mpg.de/index.html>`_ as an
+alternative to ScaLAPACK (with GPU implementations also available).
+It will also use `LibXC <https://libxc.gitlab.io/>`_ if it is
+available (v4.x or later) :cite:`i-Lehtola:2018le`.
 
 The library locations are set in the ``system.make`` file in the ``src/system``
 directory, along with other parameters needed for compilation.  The default file
@@ -112,7 +114,7 @@ and load the ``Conquest`` executable to ``PATH`` with
 
 The build can be customized by adding options to the
 `Spack spec <https://spack.readthedocs.io/en/latest/basic_usage.html#specs-dependencies>`_ ``conquest``.
-The CONQUEST package includes variants for OpenMP support and different matrix multiplication kernels; more details can be found in the `Spack CONQUEST package <https://spack.readthedocs.io/en/latest/package_list.html#conquest>`_.
+The CONQUEST package includes variants for OpenMP support and different matrix multiplication kernels; more details can be found in the `Spack CONQUEST package <https://packages.spack.io/package.html?name=conquest>`_.
 
 Installing on Ubuntu
 -----------
@@ -192,7 +194,7 @@ Prepare makefile
     # Choose LibXC version: v4 (deprecated) or v5/6 (v5 and v6 have the same interface)
     # XC_LIBRARY = LibXC_v4
     XC_LIBRARY = LibXC_v5
-    XC_LIB = -lxcf90 -lxc
+    XC_LIB = -lxcf03 -lxc
     XC_COMPFLAGS = -I\${HOME}/local/include -I/usr/local/include
 
     # Set FFT library
@@ -223,5 +225,13 @@ Compile CONQUEST
 
     dos2unix ./makedeps       # For Windows Subsystem for Linux (WSL), there may be some incompatibilities thus file conversion is recommended.
     make                      # Or make -j`nproc` for parallel compilation using all available cores
+
 Go to :ref:`top <install>`
 
+.. bibliography:: references.bib
+    :cited:
+    :labelprefix: I
+    :keyprefix: i-
+    :style: unsrt
+
+Go to :ref:`top <install>`
diff --git a/docs/references.bib b/docs/references.bib
@@ -1,12 +1,22 @@
 %% This BibTeX bibliography file was created using BibDesk.
-%% http://bibdesk.sourceforge.net/
+%% https://bibdesk.sourceforge.io/
 
-
-%% Created for David Bowler at 2019-12-20 09:46:12 +0000 
+%% Created for David Bowler at 2026-02-11 11:22:57 +0000 
 
 
 %% Saved with string encoding Unicode (UTF-8) 
 
+
+
+@article{Lehtola:2018le,
+	author = {Lehtola, Susi and Steigemann, Conrad and Oliveira, Micael J. T. and Marques, Miguel A. L.},
+	doi = {10.1016/j.softx.2017.11.002},
+	journal = {SoftwareX},
+	pages = {1--5},
+	title = {Recent developments in libxc —A comprehensive library of functionals for density functional theory},
+	volume = {7},
+	year = {2018}}
+
 @article{Torralba:2009nr,
 	author = {Torralba, Antonio S and Bowler, David R and Miyazaki, Tsuyoshi and Gillan, Michael J},
 	doi = {10.1021/ct8005425},
@@ -679,3 +689,23 @@ @article{Boys:1970aa
   year = {1970},
   doi = {10.1080/00268977000101561},
   pages = {553}}
+@article{Bengtsson1999,
+  title = {Dipole correction for surface supercell calculations},
+  author = {Bengtsson, Lennart},
+  journal = {Phys. Rev. B},
+  volume = {59},
+  issue = {19},
+  pages = {12301--12304},
+  year = {1999},
+  doi = {10.1103/PhysRevB.59.12301}
+}
+@article{Neugebauer1992,
+  title = {Adsorbate-substrate and adsorbate-adsorbate interactions of Na and K adlayers on Al(111)},
+  author = {Neugebauer, J\"org and Scheffler, Matthias},
+  journal = {Phys. Rev. B},
+  volume = {46},
+  issue = {24},
+  pages = {16067--16080},
+  year = {1992},
+  doi = {10.1103/PhysRevB.46.16067}
+}
diff --git a/docs/strucrelax.rst b/docs/strucrelax.rst
@@ -123,6 +123,15 @@ coordinates* (``AtomMove.OptCellMethod 1``) using the following input:
 
 Note that stress is in GPa and enthalpy is in Ha by default.
 
+It is possible to apply constraints to the cell when optimising it, using the
+flag ``AtomMove.OptCell.Constraint``.  The constraint takes three different possible
+forms: fixing one or two of the cell lengths (e.g. ``AtomMove.OptCell.Constraint a`` or
+``AtomMove.OptCell.Constraint a b``); fixing the ratio between two cell lengths
+(e.g. ``AtomMove.OptCell.Constraint c/a``); and varying only the volume but not the
+cell shape (``AtomMove.OptCell.Constraint volume``).  Fixing the ratio between two
+cell lengths does not determine the minimisation fully: we choose to maintain the
+*average* stress in the two directions as well as the ratio.
+
 Go to :ref:`top <strucrelax>`.
 
 .. _sr_both:
@@ -147,7 +156,10 @@ allows *orthorhombic* unit cells). This can be done by setting
    AtomMove.EnthalpyTolerance 1E-5
    AtomMove.StressTolerance 0.1
 
-Note that stress is in GPa and enthalpy is in Ha by default.
+Note that stress is in GPa and enthalpy is in Ha by default.  It is possible
+to apply constraints to the simulation cell as described above, but this will
+require extra care from the user to ensure that the simulation proceeds as
+desired.
 
 The enthalpy will generally converge much more rapidly than the force
 and stress, and that it may be necessary to tighten ``minE.SCTolerance``

diff --git a/src/DMMinModule.f90 b/src/DMMinModule.f90
@@ -827,7 +827,7 @@ subroutine lateDM(ndone, n_L_iterations, done, deltaE, vary_mu, &
                                  flag_mix_L_SC_min,                    &
                                  flag_fix_spin_population, nspin,      &
                                  spin_factor, flag_dump_L,             &
-                                 flag_SpinDependentSF, min_layer
+                                 flag_SpinDependentSF, min_layer, mu_DMM
     use timer_module,      only: cq_timer,start_timer,                 &
                                  stop_print_timer, WITH_LEVEL
     use io_module,         only: dump_matrix, return_prefix
@@ -877,6 +877,7 @@ subroutine lateDM(ndone, n_L_iterations, done, deltaE, vary_mu, &
     if (ndone > n_L_iterations) &
          call cq_abort('lateDM: too many L iterations', ndone, n_L_iterations)
 
+    mu_DMM = zero
     do spin = 1, nspin
        do i = 1, maxpulayDMM
           mat_Lstore(i,spin) = allocate_temp_matrix(Lrange,0)
@@ -888,7 +889,6 @@ subroutine lateDM(ndone, n_L_iterations, done, deltaE, vary_mu, &
        matSphi(spin) = allocate_temp_matrix(Lrange,0)
        mat_temp(spin) = allocate_temp_matrix(TLrange,0)
     end do
-
     ! Update the charge density if flag is set
     min_layer = min_layer - 1
     if (flag_mix_L_SC_min) then
@@ -931,6 +931,7 @@ subroutine lateDM(ndone, n_L_iterations, done, deltaE, vary_mu, &
           call matrix_product(mat_temp(spin), matT(spin_SF), matSphi(spin), mult(TL_T_L))
           e_dot_n(spin) = matrix_product_trace(matSM3(spin), matphi(spin))
           n_dot_n(spin) = matrix_product_trace(matSphi(spin), matphi(spin))
+          mu_DMM(spin) = e_dot_n(spin) / n_dot_n(spin)
           if (inode == ionode .and. iprint_DM + min_layer >= 3) then
              write(io_lun, '(4x,a,i1,") ",f16.6)') &
                   trim(prefix)//" e.n (spin=", spin, e_dot_n(spin)
@@ -1057,6 +1058,7 @@ subroutine lateDM(ndone, n_L_iterations, done, deltaE, vary_mu, &
                                  mult(TL_T_L))
              e_dot_n(spin) = matrix_product_trace(matSM3(spin), matphi(spin))
              n_dot_n(spin) = matrix_product_trace(matSphi(spin), matphi(spin))
+             mu_DMM(spin) = e_dot_n(spin) / n_dot_n(spin)
           end do
           if (flag_fix_spin_population) then
              do spin = 1, nspin
@@ -1185,6 +1187,7 @@ subroutine lateDM(ndone, n_L_iterations, done, deltaE, vary_mu, &
                                  matSphi(spin), mult(TL_T_L))
              e_dot_n(spin) = matrix_product_trace(matSM3(spin), matphi(spin))
              n_dot_n(spin) = matrix_product_trace(matSphi(spin), matphi(spin))
+             mu_DMM(spin) = e_dot_n(spin) / n_dot_n(spin)
           end do
           if (flag_fix_spin_population) then
              do spin = 1, nspin
Original file line number	Diff line number	Diff line change
Expand Up		@@ -50,4 +50,4 @@ DOI for the specific version you have used in any given study.

		## Version number

		CONQUEST is now at version 1.4 (tag:v1.4)
		CONQUEST is now at version 1.5 (tag:v1.5)