update docs, add script to convert nwchem input file to exachem input…

… file

README.md

@@ -14,7 +14,7 @@
 
 ## Overview
 
-**ExaChem** is a suite of scalable electronic structure methods to perform ground and excited-state calculations on molecular systems. These methodologies are implemented using the **T**ensor **A**lgebra for **M**any-body **M**ethods ([TAMM](https://github.com/NWChemEx-Project/TAMM)) library. TAMM is a parallel tensor algebra library for performance-portable development of scalable electronic structure methods that can be run on modern exascale computing platforms. ExaChem  currently includes implementations of: Hartree-Fock (HF), MP2, CC2, CCSD, CCSD(T), CCSD-Lambda, EOM-CCSD, RT-EOM-CCSD, GFCCSD and double unitary coupled-cluster (DUCC). ExaChem and TAMM are actively being developed and maintained at the Pacific Northwest National Laboratory ([PNNL](https://pnnl.gov)) and distributed as open-source under the terms of the Apache License version 2.0.
+**ExaChem** is a suite of scalable electronic structure methods to perform ground and excited-state calculations on molecular systems. It is currently being developed synergistically with the [NWChemEx](https://nwchemex-project.github.io/NWChemEx), [SPEC](https://spec.labworks.org/home), QIS and MAPOL projects (please see acknowledgements). The methodologies in ExaChem are implemented using the **T**ensor **A**lgebra for **M**any-body **M**ethods ([TAMM](https://github.com/NWChemEx-Project/TAMM)) library. TAMM is a parallel tensor algebra library for performance-portable development of scalable electronic structure methods that can be run on modern exascale computing platforms. ExaChem  currently includes implementations of: Hartree-Fock (HF), MP2, CC2, CCSD, CCSD(T), CCSD-Lambda, EOM-CCSD, RT-EOM-CCSD, GFCCSD and double unitary coupled-cluster (DUCC). ExaChem and TAMM are actively being developed and maintained at the Pacific Northwest National Laboratory ([PNNL](https://pnnl.gov)) and distributed as open-source under the terms of the Apache License version 2.0.
 
 
 ## Build 
@@ -24,14 +24,35 @@ Build instructions are available [here](docs/install.md)
 ## ExaChem Citation
 #### Please cite the following reference when publishing results obtained with ExaChem. 
 
-Panyala, Ajay; Govind, Niranjan; Kowalski, Karol; Bauman, Nicholas; Peng, Bo; Pathak, Himadri; Mutlu, Erda; Mejia Rodriguez, Daniel; Xantheas, Sotiris. **ExaChem: Open Source Exascale Computational Chemistry Software.** https://github.com/ExaChem/exachem  (June 2023) [DOI:10.11578/dc.20230628.1](https://doi.org/10.11578/dc.20230628.1)
+Panyala, Ajay; Bauman, Nicholas; Pathak, Himadri; Mejia Rodriguez, Daniel; Peng, Bo; Mutlu, Erdal; Xantheas, Sotiris; Govind, Niranjan; Kowalski, Karol; Krishnamoorthy, Sriram. **ExaChem: Open Source Exascale Computational Chemistry Software.** https://github.com/ExaChem/exachem  (June 2023) [DOI:10.11578/dc.20230628.1](https://doi.org/10.11578/dc.20230628.1)
 
 #### Please cite the following reference in addition if using the ground-state closed-shell CCSD and CCSD(T) capabilities.
 
 Kowalski, Karol, Bair, Raymond, Bauman, Nicholas P., Boschen, Jeffery S., Bylaska, Eric J., Daily, Jeff, de Jong, Wibe A., Dunning, Thom Jr., Govind, Niranjan, Harrison, Robert J., Keçeli, Murat, Keipert, Kristopher, Krishnamoorthy, Sriram, Kumar, Suraj, Mutlu, Erdal, Palmer, Bruce, Panyala, Ajay, Peng, Bo, Richard, Ryan M., Straatsma, T. P., Sushko, Peter, Valeev, Edward F., Valiev, Marat, van Dam, Hubertus J. J., Waldrop, Jonathan M., Williams-Young, David B., Yang, Chao, Zalewski, Marcin and Windus, Theresa L. **From NWChem to NWChemEx: Evolving with the Computational Chemistry Landscape.** Chemical Reviews (2021) [DOI:10.1021/acs.chemrev.0c00998](doi.org/10.1021/acs.chemrev.0c00998).
 
 ## Acknowledgements
 
-The TAMM library (core infrastructure and current optimizations), the ground-state formulations of the closed-shell CCSD, and CCSD(T) methods have been supported by the [NWChemEx](https://nwchemex-project.github.io/NWChemEx) project, funded through the Exascale Computing Project (ECP) (17-SC-20-SC), a collaborative effort of the U.S. Department of Energy Office of Science and the National Nuclear Security Administration. 
+The TAMM library (core infrastructure and current optimizations), the ground-state formulations of the closed-shell CCSD, and CCSD(T) methods have been supported by the [NWChemEx](https://nwchemex-project.github.io/NWChemEx) project, funded through the [Exascale Computing Project ECP](https://www.exascaleproject.org) (17-SC-20-SC), a collaborative effort of the U.S. Department of Energy Office of Science and the National Nuclear Security Administration. 
 
-The development of additional TAMM capabilities and methodologies (HF, MP2, CC2, CCSD-Lambda, EOM-CCSD, RT-EOM-CCSD, and GFCCSD) are supported by the [Center for Scalable Predictive Methods for Excitations and Correlated Phenomena  (SPEC)](https://spec.labworks.org/home) under FWP 70942, which is funded as part of the Computational Chemical Sciences (CCS) program by the U.S. Department of Energy (DOE), Office of Science, Office of Basic Energy Sciences (BES), Division of Chemical Sciences, Geosciences and Biosciences at PNNL. The double unitary coupled-cluster (DUCC) development is supported under FWP 72689 (Embedding QC into Many-body Frameworks for Strongly Correlated Molecular and Materials Systems) funded by the DOE BES "Materials and Chemical Sciences Research for Quantum Information Science" program. PNNL is a multi-program national laboratory operated by Battelle Memorial Institute for the United States Department of Energy under DOE contract number DE-AC05-76RL01830.
+The development of additional TAMM capabilities and methodologies (HF, MP2, CC2, CCSD-Lambda, EOM-CCSD, RT-EOM-CCSD, and GFCCSD) are supported by the Center for **S**calable **P**redictive Methods for **E**xcitations and **C**orrelated Phenomena  [(SPEC)](https://spec.labworks.org/home) under FWP 70942.
+
+The double unitary coupled-cluster (DUCC) development is supported under FWP 72689 (Embedding QC into Many-body Frameworks for Strongly Correlated Molecular and Materials Systems) funded by the DOE BES "Materials and Chemical Sciences Research for Quantum Information Science" program.
+
+Ongoing development of many-body methodologies for molecular polaritonic systems is being funded by FWP 79715, Center for **Ma**ny-Body Methods, Spectroscopies, and Dynamics for Molecular **Pol**aritonic Systems (MAPOL).
+
+The SPEC and MAPOL projects are funded as part of the Computational Chemical Sciences (CCS) program by the U.S. Department of Energy (DOE), Office of Science, Office of Basic Energy Sciences (BES), Division of Chemical Sciences, Geosciences and Biosciences at PNNL. PNNL is a multi-program national laboratory operated by Battelle Memorial Institute for the United States Department of Energy under DOE contract number **DE-AC05-76RL01830**.
+
+### Computing Resources
+
+- Allocation on [OLCF Summit](https://www.olcf.ornl.gov/summit), [NERSC Perlmutter](https://docs.nersc.gov/systems/perlmutter), [ALCF Sunspot](https://www.alcf.anl.gov/support-center/aurora-sunspot), and [OLCF Frontier](https://www.olcf.ornl.gov/frontier) for the [NWChemEx project](https://nwchemex-project.github.io/NWChemEx) (2017-2023) through the [Exascale Computing Project ECP](https://www.exascaleproject.org) (17-SC-20-SC). 
+
+- [NERSC Perlmutter](https://docs.nersc.gov/systems/perlmutter) allocations through the DOE Basic Energy Sciences (BES) Chemical Sciences, Geosciences, & Biosciences (CSGB) program:
+  * **m3196** (2020 - current): Scalable Predictive Methods for Excitations and Correlated Phenomena [(SPEC)](https://spec.labworks.org/home).
+  * **m4262** (2023 - current): Many-Body Methods, Spectroscopies, and Dynamics for Molecular Polaritonic Systems (MAPOL).
+
+<br />
+
+- [OLCF Summit](https://www.olcf.ornl.gov/summit) allocations awarded for the [SPEC](https://spec.labworks.org/home) project.
+  - INCITE 2021 for OLCF Summit: **Deciphering the Mysteries of Hydrogen Bonding in Water.**
+  - OLCF Director's Discretionary (DD) project for OLCF Summit (2019). **CHM159: Excited States of DNA/RNA oligomers.** 
+  - Early Science project for OLCF Summit (2019). **CHM146: Highly Accurate Electronic Structure Methods for Ground and Excited States at Scale: Addressing Problems in Energy Capture, Transfer, and Storage.**  

ci/reference_output/butanol2.sto-3g.ccsd.json

@@ -264,12 +264,12 @@
     },
     "CD": {
       "diagtol": 1e-06,
+      "itilesize": 1000,
       "max_cvecs_factor": 12
     },
     "CCSD": {
       "threshold": 1e-06,
       "tilesize": 40,
-      "itilesize": 1000,
       "ndiis": 5,
       "readt": "false",
       "writet": "true",

ci/reference_output/butanol2_lambda.sto-3g.ccsd_lambda.json

@@ -275,12 +275,12 @@
     },
     "CD": {
       "diagtol": 1e-06,
+      "itilesize": 1000,
       "max_cvecs_factor": 12
     },
     "CCSD": {
       "threshold": 1e-06,
       "tilesize": 40,
-      "itilesize": 1000,
       "ndiis": 5,
       "readt": "false",
       "writet": "false",

ci/reference_output/butanol2_pt.sto-3g.ccsd_t.json

@@ -282,12 +282,12 @@
     },
     "CD": {
       "diagtol": 1e-06,
+      "itilesize": 1000,
       "max_cvecs_factor": 12
     },
     "CCSD": {
       "threshold": 1e-06,
       "tilesize": 40,
-      "itilesize": 1000,
       "ndiis": 5,
       "readt": "false",
       "writet": "true",

ci/reference_output/co.cc-pvdz.gfccsd.json

@@ -468,12 +468,12 @@
     },
     "CD": {
       "diagtol": 1e-08,
+      "itilesize": 1000,
       "max_cvecs_factor": 12
     },
     "CCSD": {
       "threshold": 1e-06,
       "tilesize": 40,
-      "itilesize": 1000,
       "ndiis": 5,
       "readt": "false",
       "writet": "true",

ci/reference_output/h2o_ducc.cc-pvdz.ducc.json

@@ -303,12 +303,12 @@
     },
     "CD": {
       "diagtol": 1e-12,
+      "itilesize": 1000,
       "max_cvecs_factor": 40
     },
     "CCSD": {
       "threshold": 1e-06,
       "tilesize": 40,
-      "itilesize": 1000,
       "ndiis": 5,
       "readt": "false",
       "writet": "false",

ci/reference_output/h2o_eom.cc-pvdz.eomccsd.json

@@ -665,12 +665,12 @@
     },
     "CD": {
       "diagtol": 1e-12,
+      "itilesize": 1000,
       "max_cvecs_factor": 40
     },
     "CCSD": {
       "threshold": 1e-06,
       "tilesize": 40,
-      "itilesize": 1000,
       "ndiis": 5,
       "readt": "false",
       "writet": "false",

ci/reference_output/ubiquitin_dgrtl.sto-3g.ccsd.json

@@ -423,12 +423,12 @@
     },
     "CD": {
       "diagtol": 1e-06,
+      "itilesize": 1000,
       "max_cvecs_factor": 12
     },
     "CCSD": {
       "threshold": 1e-08,
       "tilesize": 40,
-      "itilesize": 1000,
       "ndiis": 5,
       "readt": "false",
       "writet": "false",

docs/conf.py

@@ -18,7 +18,7 @@
 # -- Project information -----------------------------------------------------
 
 project = u'ExaChem'
-copyright = u'2022, ExaChem Team'
+copyright = u'2022-2023, ExaChem Team'
 author = u'ExaChem Team'
 
 # Get the version from version.txt

docs/developer_guide/developer.rst

@@ -2,4 +2,5 @@
 ExaChem Developer Guide
 =======================
 
+TBD
 

docs/index.rst

@@ -1,11 +1,11 @@
 ExaChem Documentation
-================================
+=======================
 
 .. toctree::
    :maxdepth: 3
    :caption: Contents:
 
-   intro
+   introduction
    user_guide/user
    developer_guide/developer
 

docs/introduction.rst

@@ -0,0 +1,9 @@
+#############################
+Introduction to ExaChem
+#############################
+
+**ExaChem** is a suite of scalable electronic structure methods to perform ground and excited-state calculations on molecular systems. 
+These methodologies are implemented using the Tensor Algebra for Many-body Methods (`TAMM <https://github.com/NWChemEx-Project/TAMM>`_) library. 
+TAMM is a parallel tensor algebra library for performance-portable development of scalable electronic structure methods that can be run on modern exascale computing platforms. 
+ExaChem  currently includes implementations of: Hartree-Fock (HF), MP2, CC2, CCSD, CCSD(T), CCSD-Lambda, EOM-CCSD, RT-EOM-CCSD, GFCCSD and double unitary coupled-cluster (DUCC). 
+ExaChem and TAMM are actively being developed and maintained at the Pacific Northwest National Laboratory (`PNNL <https://pnnl.gov>`_) and distributed as open-source under the terms of the Apache License version 2.0.

docs/schema/input_schema.json

@@ -210,6 +210,12 @@
         },
         "write_vcount": {
           "type": "number"
+        },
+        "write_cv": {
+          "type": "boolean"
+        },
+        "itilesize": {
+          "type": "number"
         }
       }
     },
@@ -275,9 +281,6 @@
         "tilesize": {
           "type": "number"
         },
-        "itilesize": {
-          "type": "number"
-        },
         "lshift": {
           "type": "number"
         },
@@ -331,6 +334,9 @@
             },
             "ccsd_diagnostics": {
               "type": "string"
+            },
+            "rdm": {
+              "type": "array"
             }
           }
         },

docs/user_guide/basic_options.rst

@@ -0,0 +1,110 @@
+.. role:: aspect (emphasis)
+.. role:: sep (strong)
+.. rst-class:: dl-parameters
+
+.. TODO: Match defaults with code snippets
+
+========================
+Basic input options
+========================
+
+**The input is a JSON file with the following JSON objects documented below. 
+The** ``inputs`` **folder in this repository contains json files for several molecular systems.**
+
+| :ref:`Geometry <Geometry>`
+| :ref:`Common options <Common>`
+| :ref:`Basis set options <Basis>`
+
+.. _Geometry:
+
+Geometry
+~~~~~~~~
+
+A geometry can be specified as follows:
+
+.. literalinclude:: ../../inputs/example.json
+   :language: json
+   :lines: 3-10
+
+:coordinates: The atom *symbol* followed by the *x y z* coordinates
+
+:units: The following possible string values are recognized ``[default=angstrom]``
+
+   * :strong:`"bohr"`: Atomic units (A.U.) 
+   * :strong:`"angstrom"`: Angstroms, converted to A.U. using the conversion factor 1.8897259878858.
+
+.. _Common:
+
+Common options
+~~~~~~~~~~~~~~
+
+Some common options supported are as follows:
+
+.. literalinclude:: ../../inputs/example.json
+   :language: json
+   :lines: 16-23
+
+:maxiter: An integer used to specify the maximum number of iterations for all sections below.
+   This value can be changed on a per section basis. ``[default: 50]``
+
+:debug: A boolean used to turn on debugging mode. ``[default: false]``
+
+:output_file_prefix: A string indicating the prefix for the name of the output folder where the results of a run are stored.
+   The *default prefix* is the name of the input file without the *.json* extension.
+
+.. _Basis:
+
+Basis set options
+~~~~~~~~~~~~~~~~~
+Currently support basis sets consisting of generally contracted Cartesian Gaussian functions up to a maximum angular momentum of six (h functions)::
+
+ "basis": {
+   "basisset": "cc-pvdz",
+   "gaussian_type": "spherical",
+   "atom_basis": {
+     "H": "cc-pvtz",
+     "O": "aug-cc-pvtz"
+    }
+ }
+
+:basisset: String specifying the basis set name.
+
+:atom_basis: Specify the basis set for individual atoms.
+
+..  :df_basisset: Used to specify the auxiliary basisset for density fitting.
+
+:gaussian_type: The following values are recognized
+
+   * :strong:`spherical (default)`: spherical-harmonic (5 d, 7 f, 9 g, ...) angular functions are utilized.
+   * :strong:`cartesian`: Cartesian (6 d, 10 f, 15 g, ...) angular functions are utilized.
+
+.. note:: 
+
+   The correlation-consistent basis sets were designed using spherical harmonics and to use these, the spherical keyword should be specified. 
+
+.. _TASK:
+
+TASK Options
+~~~~~~~~~~~~
+
+The **TASK** block of the input file specifies the method to run. Only a single task can be specified at once. The supported task options are shown below.
+
+.. code-block:: json
+
+ "TASK": {
+   "scf": true,
+   "mp2": false,
+   "cc2": false,
+   "fcidump": false,
+   "cd_2e": false,
+   "ducc": false,
+   "ccsd": false,
+   "ccsd_t": false,
+   "ccsd_lambda": false,
+   "eom_ccsd": false,
+   "rteom_ccsd": false,
+   "gfccsd": false
+ }
+
+A task automatically runs the tasks it depends on. For e.g. if **ccsd** is enabled, it automatically runs the tasks **scf** (hartree fock) and **cd_2e** (cholesky decomposition of the 2e integrals).
+

docs/user_guide/bibliography.rst

@@ -73,6 +73,11 @@ Bibliography
    Cluster Calculations.” *J. Chem. Theory Comput.* 13 (9): 4179–92.
    https://doi.org/10.1021/acs.jctc.7b00605.
 
+.. .. [peng_201747]
+..    Peng, Bo, and Karol Kowalski. 2017.
+..    "Low-rank factorization of electron integral tensors and its application in electronic structure theory."
+..    *Chemical Physics Letters.* https://doi.org/10.1016/j.cplett.2017.01.056.
+
 .. [vanbeeumen17_4950]
    Van Beeumen, Roel, David B. Williams-Young, Joseph M. Kasper, Chao
    Yang, Esmond G. Ng, and Xiaosong Li. 2017. “Model Order Reduction