Merge pull request #154 from OrderN/release-1.1

Release v1.1 of Conquest

.readthedocs.yml

@@ -6,8 +6,8 @@
 version: 2
 
 # Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: docs/CONQUEST-manual/conf.py
+#sphinx:
+#  configuration: docs/CONQUEST-manual/conf.py
 
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: all

README.md

@@ -45,3 +45,7 @@ under this umbrella DOI (which will resolve to the latest version).  Please use
 DOI for the specific version you have used in any given study.
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3943720.svg)](https://doi.org/10.5281/zenodo.3943720)
+
+## Version number
+
+CONQUEST is now at version 1.1 (tag:v1.1)

docs/README.md

@@ -1 +1,8 @@
 The documentation for CONQUEST and associated utilities is stored here.
+
+You can build the documentation simply:
+
+* make html will make HTML documentation (found in _build/html)
+* make PDF will make one PDF file using LaTeX (if installed)
+
+The documentation is also available on [ReadTheDocs](https://conquest.readthedocs.io/en/latest/).

docs/CONQUEST-manual/basissets.rst → docs/basissets.rst

@@ -57,11 +57,11 @@ The accuracy of a calculation can be improved by adding polarisation
 functions and multiple radial functions for different angular momentum
 values, though systematic improvement is rather difficult to achieve
 (this is straightforward with a :ref:`blip function basis<basis_blips>`).
-The PAO utility included with CONQUEST generates basis sets with
+The :ref:`PAO utility<generating_paos>` included with CONQUEST generates basis sets with
 differing sizes and accuracies; full details of the performance of
 these basis sets can be found elsewhere :cite:`b-Bowler:2019fv`.
 
-* minimal (single zeta)
+* minimal (single zeta, SZ)
 * small   (single zeta and polarisation, SZP)
 * medium  (double zeta, single polarisation, DZP)
 * large   (triple zeta, double polarisation, TZDP)

docs/CONQUEST-manual/conf.py → docs/conf.py

@@ -19,6 +19,8 @@
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('extensions'))
+import sphinx_rtd_theme
+
 
 
 # -- General configuration ------------------------------------------------
@@ -34,8 +36,11 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.githubpages',
     'sphinx.ext.autosectionlabel',
+    'sphinx_rtd_theme',
     'sphinxcontrib.bibtex']
 
+bibtex_bibfiles = ['references.bib']
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -50,24 +55,24 @@
 
 # General information about the project.
 project = u'CONQUEST'
-copyright = u'2018-2020, CONQUEST Developers'
+copyright = u'2018-2022, 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.0.2-pre'
+version = u'1.0.7-pre'
 # The full version, including alpha/beta/rc tags.
-release = u'1.0.2-pre'
+release = u'1.0.7-pre'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -167,7 +172,8 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
     (master_doc, 'CONQUEST', u'CONQUEST Documentation',
-     author, 'CONQUEST', 'One line description of project.',
+     'CONQUEST Developers', 'CONQUEST',
+     'CONQUEST: Large scale and linear scaling DFT.',
      'Miscellaneous'),
 ]
 

docs/CONQUEST-manual/ext-tools.rst → docs/ext-tools.rst

@@ -4,6 +4,200 @@
 External tools
 ==============
 
+.. _et_post_process:
+
+Post-processing for charge density, band density, DOS, STM
+----------------------------------------------------------
+
+The utility ``PostProcessCQ`` allows users to post-process the output
+of a CONQUEST calculation, to produce the charge density, band
+densities, DOS and STM images in useful forms (at present, as a CUBE
+file which can be read by the `VESTA
+<https://jp-minerals.org/vesta/en/>`_ code, which is freely available).
+
+There are a number of different analyses which can be performed:
+coordinate conversion (to formats which can be plotted); conversion of
+total charge density to CUBE file format; production of band-resolved
+(optionally k-point resolved) densities in CUBE file format; simple
+Tersoff-Hamann STM simulation; and calculation of densities of states
+(projected DOS is under development).  You should ensure that all the
+files produced during the CONQUEST run are available for the
+post-processing (including ``eigenvalues.dat``, ``chden.nnn``,
+``make_blk.dat`` or ``hilbert_make_blk.dat``) as well as the input
+files.
+
+**Note** that the utility reads the ``Conquest_input`` file, taking some
+flags from the CONQUEST run that generated the output, and some
+utility-specific flags that are detailed below.
+
+**Note also** that band density and STM simulation are not at present
+compatible with multi-site support functions (MSSF), though we hope
+to implement this soon.
+
+Go to :ref:`top <ext-tools>`.
+
+Coordinate conversion
++++++++++++++++++++++
+
+Set ``Process.Job coo`` to output a coordinate file for further
+processing or plotting.  The utility will read the file specified by
+``Process.Coordinates`` (which defaults to the file specified by
+``IO.Coordinates``).  The output format is selected by specifying the
+``Process.CoordFormat`` tag.  The default output format is XYZ (which
+adds a ``.xyz`` suffix to the file name) using ``xyz``.  The CASTEP
+.cell output format can also be selected using ``cell``.  We plan to
+expand this conversion to other formats in the future.
+
+**Note** that for a structural relaxation or molecular dynamics
+calculation, if you do not specify ``Process.Coordinates`` then the
+``IO.Coordinates`` file, which will be converted, will be the *input*
+structure, not the output structure.  Parameters that can be set are:
+
+::
+
+   Process.Coordinates string (default: IO.Coordinates value)
+   Process.CoordFormat string (default: xyz)
+
+Go to :ref:`top <ext-tools>`.
+
+Charge density
+++++++++++++++
+
+Setting ``Process.Job`` to ``cha``, ``chg`` or ``den`` will convert
+the files ``chden.nnn`` which are written by CONQUEST to a cube file.
+The processing will use the files ``chden.nnn``, ``Conquest_input``
+and ``hilbert_make_blk.dat`` or ``raster_make_blk.dat``.  Parameters
+that can be set include:
+
+::
+   
+   Process.ChargeStub string (default: chden)
+
+The ChargeStub simply defines the filename which will be read, and
+used for output.
+
+**Note** that to output the ``chden.nnn`` files from CONQUEST, you must
+set the flag ``IO.DumpChargeDensity`` to true in the CONQUEST run.
+
+Go to :ref:`top <ext-tools>`.
+
+Band density
+++++++++++++
+
+Setting ``Process.Job`` to ``ban`` produces band densities from wave
+function coefficients output by CONQUEST.  The CONQUEST run must have
+the following tags set:
+
+::
+
+   IO.outputWF T
+
+A set of bands whose coefficients are output are specified either with
+an energy range (the default is to produce *all* bands):
+
+::
+
+   IO.WFRangeRelative T/F
+   IO.min_wf_E real (Ha)
+   IO.max_wf_E real (Ha)
+
+or with a list of bands:
+
+::
+
+   IO.maxnoWF n
+
+   %block WaveFunctionsOut
+   n entries, each a band number
+   %endblock
+
+The wavefunction range can be relative to the Fermi level
+(``IO.WFRangeRelative T``) otherwise it is absolute.  Either of these
+will produce a file containing all eigenvalues at all k-points
+(``eigenvalues.dat``) and a series of files containing the
+wavefunction expansion coefficients for the selected bands
+(``ProcessnnnnnnnWF.dat``).  From these, band densities can be
+produced in post-processing, using similar tags; either a range:
+
+::
+
+   Process.min_wf_E real (Ha)
+   Process.max_wf_E real (Ha)
+   Process.WFRangeRelative T/F
+
+or an explicit list of bands:
+
+::
+
+   Process.noWF n
+
+   %block WaveFunctionsProcess
+   n entries, each a band number
+   %endblock
+
+Note that the bands to be processed must be a subset of the bands
+output by CONQUEST.  The bands can be output summed over k-points, or
+at individual k-points, by setting ``Process.outputWF_by_kpoint`` to
+``F`` or ``T`` respectively.
+
+Go to :ref:`top <ext-tools>`.
+
+Tersoff-Hamann STM simulation
++++++++++++++++++++++++++++++
+
+Setting ``Process.Job ter`` will use a very simple Tersoff-Hamann
+approach to STM simulation, summing over band densities between the
+Fermi level and the bias voltage (this is often surprisingly
+accurate).  The following parameters can be set:
+
+::
+
+   STM.BiasVoltage    real (eV)
+   STM.FermiOffset    real (eV)
+   Process.MinZ       real (Bohr)
+   Process.MaxZ       real (Bohr)
+   Process.RootFile   string (default: STM)
+
+The ``FermiOffset`` tag allows the user to shift the Fermi level (to simulate
+charging or an external field).  The height of the simulation cell
+in which the STM image is calculated is set by the ``MinZ`` and
+``MaxZ`` tags, and the filename by the ``RootFile`` tag.
+
+Go to :ref:`top <ext-tools>`.
+
+Density of states
++++++++++++++++++
+
+Setting ``Process.Job dos`` will produce a total density of states
+(DOS) for the system, using the eigenvalues output by CONQUEST.  The
+following parameters can be set:
+
+::
+
+   Process.min_DOS_E real    (Ha, default lowest eigenvalue)
+   Process.max_DOS_E real    (Ha, default highest eigenvalue)
+   Process.sigma_DOS real    (Ha, default 0.001)
+   Process.n_DOS     integer (default 201)
+
+The limits for the DOS are set by the first two parameters (note that
+CONQUEST will output all eigenvalues, so the limits on these are set
+by the eigenspectrum).  The broadening applied to each state is set by
+``sigma_DOS``, while the number of bins is set by ``n_DOS``.  The
+integrated DOS are also calculated; the user can choose whether this
+is the total integrated DOS (i.e. from the lowest eigenvalue,
+regardless of the lower limit for DOS) or just the local integrated
+DOS (i.e. over the interval specified for the DOS) by setting
+``Process.TotalIntegratedDOS`` to ``T`` or ``F``, respectively.
+
+We recommend that, for accurate DOS, CONQUEST should be
+run non-self-consistently with a very high k-point density, using a
+well-converged input charge density: set ``minE.SelfConsistent F`` and
+``General.LoadRho T``.
+
+Atom-projected DOS will be available soon.
+
+Go to :ref:`top <ext-tools>`.
+
 .. _et_md_scripts:
 
 Molecular dynamics analysis