Merge pull request #35 from OrderN/release-1.0.2

Release 1.0.2-pre

.readthedocs.yml

@@ -0,0 +1,19 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/CONQUEST-manual/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: all
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.7
+  install:
+    - requirements: docs/requirements.txt

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+## Contributing to CONQUEST
+
+Thank you for your interest in contributing to the development of
+CONQUEST.  The [current
+roadmap](https://github.com/OrderN/CONQUEST-release/issues) can be
+seen on the [Conquest GitHub issues
+page](https://github.com/OrderN/CONQUEST-release/issues).  The
+features and developments planned are organised through 
+[milestones](https://github.com/OrderN/CONQUEST-release/milestones).
+If you want to submit a [new
+issue](https://github.com/OrderN/CONQUEST-release/issues/new) please
+use one of the templates, and provide as much information as possible,
+including input files needed to reproduce any unusual or incorrect
+behaviour.  We would also be happy for you to
+[fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo)
+the repository to fix a bug, and then submit a pull request.
+
+Please note that, while we will endeavour to fix any bugs, and are
+happy to receive suggestions of new features, we are not able to
+guarantee any level of support.
+
+### Joining the development team
+
+We welcome new developers.  If you are interested in contributing a
+new feature, please suggest it via the [issues
+page](https://github.com/OrderN/CONQUEST-release/issues).  If you are
+interested in contributing to an existing feature, please contact the
+development team.
+
+We follow a
+[git branching workflow](https://nvie.com/posts/a-successful-git-branching-model/)
+(also described
+[here](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow),
+though we do *not* use the ``gitflow`` tool).  You may find the
+figures in these references very helpful in understanding the overall
+workflow. The key idea is that all developments should be made on a branch
+created from the ``develop`` branch.  The overall approach is this:
+
+* We consider the [GitHub
+  repository](https://github.com/OrderN/CONQUEST-release) to be the
+  central repository (though as Git is distributed, there is no such
+  thing as an actual central repository).  We designate this
+  repository as ``origin``.
+* The ``origin/master`` branch is the main branch which always represents a
+  production-ready state.
+* The ``origin/develop`` branch is where developments which have been
+  delivered for the next release reside.
+* Feature branches (named ``f-FeatureName``) branch off ``develop``
+  and are used to develop new features or functionality for a future
+  release (possibly unspecified).  They may reside on a
+  developer's local repository only in the early stages, but will need
+  to be pushed for collaboration and discussion.  They will merge into
+  ``develop``.
+* Release branches (named ``release-Release``) branch from ``develop``
+  and merge into both ``master`` and ``develop``.
+  Release branches allow new developments to proceed on ``develop``
+  while final changes and bug fixes are made to the release.
+* Hotfix branches (named ``hotfix-Version``) branch off ``master`` and
+  merge into both ``master`` and ``develop``.  They are only used for
+  urgent fixes to an existing release.

README.md

@@ -12,15 +12,28 @@ brings the possibility of linear scaling calculations on over
 CONQUEST can perform static electronic structure calculations
 (including DOS and band structure calculations), structural
 relaxation, molecular dynamics (with NVE, NVT and NPT ensembles all
-implemented).  It can output energies, forces and stresses as well as
+implemented) and simulation cell optimisation.  It can output energies, forces and stresses as well as
 density of states, charge density, orbital density and Tersoff-Hamann
 STM images.  The facility to perform delta-SCF and cDFT calculations
 is available.  The code can use LibXC for access to a wide variety of
 exchange-correlation functionals.
 
+The basis sets used are primarily pseudo-atomic orbitals (PAOs), generated by
+a utility provided in the package.  The PAOs can be used as primitive
+basis sets, and as basis functions for multi-site support functions (MSSF)
+to allow large-scale diagonalisation calculations (up to several
+thousand atoms).  Linear scaling calculations with on-site support
+functions or small PAO basis sets are also possible.
+
 CONQUEST reads pseudopotentials produced by Don Hamann's
 [ONCVPSP](http://www.mat-simresearch.com) code, and is fully
-compatible with the PseudoDojo database.  It can also read the .ion
+compatible with the the [PseudoDojo](http://www.pseudo-dojo.org) 
+and [SG15](http://www.quantum-simulation.org/potentials/sg15_oncv/)
+databases. It can also read the .ion
 files produced by Siesta, using both the pseudopotentials and
-pseudo-atomic orbitals (PAOs) in those files.  A CONQUEST code to
-generate PAO basis sets is included in the distribution.
+pseudo-atomic orbitals (PAOs) in those files.  CONQUEST integrates with
+[ASE](https://wiki.fysik.dtu.dk/ase/index.html), the atomic simulation environment.
+
+The manual is provided with the release (see the ``docs`` directory)
+but is also available on
+[ReadTheDocs](https://conquest.readthedocs.io/en/latest/). 

docs/CONQUEST-manual/conf.py

@@ -50,17 +50,17 @@
 
 # General information about the project.
 project = u'CONQUEST'
-copyright = u'2018-2019, CONQUEST Developers'
+copyright = u'2018-2020, 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'0.1.0'
+version = u'1.0.2-pre'
 # The full version, including alpha/beta/rc tags.
-release = u'0.1.0'
+release = u'1.0.2-pre'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/CONQUEST-manual/index.rst

@@ -85,19 +85,32 @@ Get in touch
 - If you have suggestions for developing the code, please
   use `GitHub issues`_.  The developers cannot guarantee to offer
   support, though we will try to help. 
-- Report bugs, suggest features or view the source code on `GitHub
-  issues`_.
+- Report bugs, or suggest features on `GitHub
+  issues`_.  View the source code on the main `GitHub page`_.
 - You can ask for help and discuss any problems that you may have on
-  the Conquest mailing list (**to be completed**)
+  the Conquest mailing list (to register for this list, please send an
+  email to mlsystem@ml.nims.go.jp with the subject "sub
+  conquest-user", though please note that, for a little while, some of the
+  system emails may be in Japanese; you will receive a confirmation
+  email to which you should simply reply without adding any text).
 
-.. _GitHub issues: http://github.com/OrderN/CONQUEST-release/issues
+.. _GitHub issues: https://github.com/OrderN/CONQUEST-release/issues
+.. _GitHub page: https://github.com/OrderN/CONQUEST-release
 
 Licence
 -------
 
 CONQUEST is available freely under the open source `MIT Licence`__.
 We ask that you acknowledge use of the code by citing appropriate
 papers, which will be given in the output file (a BiBTeX file
-containing these references is also output).
+containing these references is also output).  The key CONQUEST
+references are:
+
+* D. R. Bowler, T. Miyazaki and M. J. Gillan, J. Phys. Condens. Matter
+  **14**, 2781--2798 (2002)
+* T. Miyazaki, D. R. Bowler, R. Choudhury
+  and M. J. Gillan, J. Chem. Phys. **121**, 6186--6194 (2004)
+* D. R. Bowler, R. Choudhury, M. J. Gillan and T. Miyazaki,
+  phys. stat. sol. b **243**, 989--1000 (2006)
 
 __ https://choosealicense.com/licenses/mit/

docs/requirements.txt

@@ -0,0 +1 @@
+sphinxcontrib.bibtex