From 12d7a2e4ccda09e6c440621e3ae6ee7cf00b82b5 Mon Sep 17 00:00:00 2001 From: Paul Kent Date: Thu, 8 Apr 2021 13:44:39 -0400 Subject: [PATCH] QE and TeX updates --- README.md | 55 ++++++++++++++++----------------------- docs/additional_tools.rst | 12 ++++----- docs/contributing.rst | 39 +++------------------------ docs/features.rst | 2 +- docs/installation.rst | 12 ++++----- 5 files changed, 38 insertions(+), 82 deletions(-) diff --git a/README.md b/README.md index 0b834cd2e..2e3308dc5 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,8 @@ particular emphasis is placed on code quality and reproducibility. # Obtaining and installing QMCPACK Obtain the latest release from https://github.com/QMCPACK/qmcpack/releases or clone the development source from - https://github.com/QMCPACK/qmcpack. A full installation guide and steps to perform an initial QMC calculation are given in the [extensive online documentation for QMCPACK](https://qmcpack.readthedocs.io/en/develop/index.html) + https://github.com/QMCPACK/qmcpack. A full installation guide and steps to perform an initial QMC calculation are given in the + [extensive online documentation for QMCPACK](https://qmcpack.readthedocs.io/en/develop/index.html). # Prerequisites @@ -31,11 +32,11 @@ particular emphasis is placed on code quality and reproducibility. * MPI, parallel library. Optional, but a near requirement for production calculations. * Python3. Older versions are not supported as of January 2020. -We aim to support open source compilers and libraries released within two years of each QMCPACK release. Use of software versions over -two years old may work but is discouraged and untested. Proprietary compilers (Intel, PGI) are generally supported over the same -period but may require use of an exact version. We also aim to support the standard software environments on Summit at OLCF, Theta -at ALCF, and Cori at NERSC. Use of the most recently released compilers and library versions is particularly encouraged for highest -performance and easiest configuration. +We aim to support open source compilers and libraries released within two years of each QMCPACK release. Use of software versions +over two years old may work but is discouraged and untested. Proprietary compilers (Intel, PGI) are generally supported over the +same period but may require use of an exact version. We also aim to support the standard software environments on machines such as +Summit at OLCF, Theta at ALCF, and Cori at NERSC. Use of the most recently released compilers and library versions is particularly +encouraged for highest performance and easiest configuration. Nightly testing currently includes the following software versions on x86: @@ -60,18 +61,13 @@ On a developmental basis we also check the latest Clang and GCC development vers # Building with CMake - The build system for QMCPACK is based on CMake. It will auto-configure - based on the detected compilers and libraries. Previously QMCPACK made - extensive use of toolchains, but the system has since been updated to - eliminate the use of toolchain files for most cases. The build - system works with GNU, Intel, and IBM XLC compilers. Specific compile options - can be specified either through specific environment or CMake - variables. When the libraries are installed in standard locations, - e.g., /usr, /usr/local, there is no need to set environment or CMake - variables for the packages. + The build system for QMCPACK is based on CMake. It will auto-configure based on the detected compilers and libraries. Previously + QMCPACK made extensive use of toolchains, but the system has since been updated to eliminate the use of toolchain files for most + cases. Specific compile options can be specified either through specific environment or CMake variables. When the libraries are + installed in standard locations, e.g., /usr, /usr/local, there is no need to set environment or CMake variables for the packages. See the manual linked at https://qmcpack.readthedocs.io/en/develop/ and https://www.qmcpack.org/documentation or buildable using - sphinx from the sources in docs/. + sphinx from the sources in docs/. A PDF version is still available at https://qmcpack.readthedocs.io/_/downloads/en/develop/pdf/ ## Quick build @@ -287,22 +283,17 @@ manual](https://qmcpack.readthedocs.io/en/develop/index.html). QMCPACK includes correctness of the code, compilers, tools, and runtime. The tests should ideally be run each compilation, and certainly before any research use. The tests include checks of the output against known mean-field, quantum chemistry, and other QMC results. -While some tests are fully deterministic, due to QMCPACK's stochastic -nature some tests are statistical and can occasionally fail. We employ -a range of test names and labeling to differentiate between these, as -well as developmental tests that are known to fail. In particular, -"deterministic" tests include this in their ctest test name, while -tests known to be unstable (stochastically or otherwise) are labeled -unstable using ctest labels. +While some tests are fully deterministic, due to QMCPACK's stochastic nature some tests are statistical and can occasionally fail. +We employ a range of test names and labeling to differentiate between these, as well as developmental tests that are known to +fail. In particular, "deterministic" tests include this in their ctest test name, while tests known to be unstable (stochastically +or otherwise) are labeled unstable using ctest labels. The tests currently use up to 16 cores in various combinations of MPI tasks and OpenMP threads. Current status for many combinations of systems, compilers, and libraries can be checked at https://cdash.qmcpack.org -Note that due to the small electron and walker counts used in the -tests, they should not be used for any performance measurements. These -should be made on problem sizes that are representative of actual -research calculations. As described in the manual, performance tests -are provided to aid in monitoring performance. +Note that due to the small electron and walker counts used in the tests, they should not be used for any performance measurements. +These should be made on problem sizes that are representative of actual research calculations. As described in the manual, +performance tests are provided to aid in monitoring performance. ## Run the unit tests @@ -345,9 +336,8 @@ ctest -R name-of-test-to-run # Documentation and support -For more information, consult QMCPACK pages at http://www.qmcpack.org, -the manual at https://qmcpack.readthedocs.io/en/develop/index.html, -or its sources in the docs directory. +For more information, consult QMCPACK pages at http://www.qmcpack.org, the manual at +https://qmcpack.readthedocs.io/en/develop/index.html, or its sources in the docs directory. If you have trouble using or building QMCPACK, or have questions about its use, please post to the [Google QMCPACK group](https://groups.google.com/forum/#!forum/qmcpack), create a GitHub issue at https://github.com/QMCPACK/qmcpack/issues or @@ -362,5 +352,4 @@ For an extensive contribution, it can be helpful to discuss on the [Google QMCPA group](https://groups.google.com/forum/#!forum/qmcpack), to create a GitHub issue, or to talk directly with a developer in advance. -Contributions are made under the same UIUC/NCSA open source license -that covers QMCPACK. Please contact us if this is problematic. +Contributions are made under the same UIUC/NCSA open source license that covers QMCPACK. Please contact us if this is problematic. diff --git a/docs/additional_tools.rst b/docs/additional_tools.rst index 840e38c14..8b0aa7fdf 100644 --- a/docs/additional_tools.rst +++ b/docs/additional_tools.rst @@ -694,11 +694,11 @@ Periodic boundary conditions with Gaussian orbitals from PySCF is fully supporte pw2qmcpack.x ~~~~~~~~~~~~ -``pw2qmcpack.x`` is an executable that converts PWSCF wavefunctions to QMCPACK readable -HDF5 format. This utility is built alongside the QE postprocessing utilities. -This utility is written in Fortran90 and is distributed as a patch of the QE -source code. The patch, as well as automated QE download and patch scripts, can be found in -``qmcpack/external_codes/quantum_espresso``. +``pw2qmcpack.x`` is an executable that converts PWSCF wavefunctions from the Quantum ESPRESSO (QE) package to QMCPACK readable +HDF5 format. This utility is built alongside the QE postprocessing utilities. This utility is written in Fortran90 and is +distributed as a patch of the QE source code. The patch, as well as automated QE download and patch scripts, can be found in +``qmcpack/external_codes/quantum_espresso``. Once built, we recommend also build QMCPACK with the QE_BIN option pointing to the +build pw.x and pw2qmcpack.x directory. This will enable workflow tests to be run. pw2qmcpack can be used in serial in small systems and should be used in parallel with large systems for best performance. The K_POINT gamma optimization is not supported. @@ -757,7 +757,7 @@ After the wavefunction file is written (basename.sample in this case) one can us This reads the Qbox wavefunction and performs the Fourier transform before saving to a QMCPACK eshdf format wavefunction. Currently multiple k-points are supported, but due to difficulties with the qbox wavefunction file format, the single particle orbitals do not have their proper energies associated with them. This means that when tiling from a primitive cell to a supercell, the lowest n single particle orbitals from all necessary k-points will be used. This can be problematic in the case of a metal and this feature should be used with EXTREME caution. -In the case of quantum espresso, QE must be compiled with HDF support. If this is the case, then an eshdf file can be generated by targeting the data-file-schema.xml file +In the case of Quantum espresso, QE must be compiled with HDF support. If this is the case, then an eshdf file can be generated by targeting the data-file-schema.xml file generated in the output of quantum espresso. For example, if one is running a calculation with outdir = 'out' and prefix='Pt' then the converter can be invoked as: :: diff --git a/docs/contributing.rst b/docs/contributing.rst index 4877eb215..1c7f5fb1f 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -9,23 +9,9 @@ This section briefly describes how to contribute to the manual and is primarily - Use the following table templates when describing XML input. -- Instead of ``\texttt`` or ``\verb`` use - - - ``\ishell`` for shell text - - - ``\ixml`` for xml text - - - ``\icode`` for C++ text - - **Except within tabularx or math environments** - -- Instead of ``\begin{verbatim}`` environments, use the appropriate ``\begin{lstlisting}[style=]``. - -- ``\begin{shade}`` can be used in place of ``\begin{lstlisting}[style=SHELL]``. - - Unicode rules - - Do not use characters for which well-established latex idiom + - Do not use characters for which well-established idioms exists, especially dashes, quotes, and apostrophes. - Use math mode markup instead of unicode characters for equations. @@ -37,36 +23,17 @@ This section briefly describes how to contribute to the manual and is primarily (emacs and ‘esc-x toggle-enable-multibyte-characters’)—see any unicode you did not intend? -- Place unformatted text targeted at developers working on the LaTeX in - comments. Include generously. - -- Encapsulate formatted text aimed at developers (like this entire - chapter), in ``\dev{}``. Text encapsulated in this way will be removed from the - user version of the manual by editing the definition of ``\dev{}`` in ``qmcpack_manual.tex``. Existing - but deprecated or partially functioning features fall in this - category. - - Newly added entries to a Bib file should be as complete as possible. Use a tool such as JabRef or Zotero that can automate creation of these entries from just a DOI. **Forbidden:** -- Including images instead of using lstlisting sections for text. +- Including images instead of text tables. -- Using packages the LaTeX community considers `deprecated`_. - -- Using packages, features, or fonts not included in texlive 2017 - unless you ensure they degrade reasonably for 2017. - -- Adding packages unless they bring great value and are supported by - tex4ht (unless you are willing to add the support). - -- Saving Tex files and Bib files in encodings other than UTF8. Some may +- Saving files in encodings other than UTF8. Some may report being ASCII encoded since they contain no unicode characters. -.. _deprecated: https://latex.org/forum/viewtopic.php?f=37&t=6637 - **Missing sections (these are opinions, not decided priorities):** - Description of XML input in general. Discuss XML format, use of diff --git a/docs/features.rst b/docs/features.rst index b9c9283a1..c8a84980d 100644 --- a/docs/features.rst +++ b/docs/features.rst @@ -51,7 +51,7 @@ feature that you are interested in, check the remainder of this manual or ask if orbitals. - Interface and conversion utilities for plane-wave wavefunctions from - Quantum Espresso (Plane-Wave Self-Consistent Field package [PWSCF]). + Quantum ESPRESSO (Plane-Wave Self-Consistent Field package [PWSCF]). - Interface and conversion utilities for Gaussian-basis wavefunctions from GAMESS, PySCF, and QP2. Many more are supported via the molden format and molden2qmc. diff --git a/docs/installation.rst b/docs/installation.rst index dc61de0f5..a8ba0c064 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -28,9 +28,9 @@ are given in the referenced sections. (:ref:`buildqe`). #. Run the cmake configure step and build with make - (:ref:`cmake` and :ref:`cmakequick`). Examples for - common systems are given in - :ref:`installexamples`. + (:ref:`cmake` and :ref:`cmakequick`). Examples for common systems are given in :ref:`installexamples`. To activate workflow + tests for Quantum ESPRESSO or PYSCF, be sure to specify QE_BIN or ensure that the python modules are available when cmake is + run. #. Run the tests to verify QMCPACK (:ref:`testing`). @@ -1634,9 +1634,9 @@ workflows of trial wavefunction generation, conversion, and eventual QMC calculation. A patched QE must be installed so that the pw2qmcpack converter is available. -By adding ``-D QE_BIN=your_QE_binary_path`` in the CMake command line when building your QMCPACK, -tests named with the "qe-" prefix will be included in the test set of your build. -You can test the whole ``pw > pw2qmcpack > qmcpack`` workflow by +By adding ``-D QE_BIN=your_QE_binary_path`` in the CMake command line when building your QMCPACK, tests named with the "qe-" +prefix will be included in the test set of your build. If CMake finds pw2qmcpack.x and pw.x in the same location on the PATH, +these tests will also be activated. You can test the whole ``pw > pw2qmcpack > qmcpack`` workflow by ::