Merge pull request #11 from BoothGroup/docs

Documentation via gh-pages

.github/workflows/ci.yaml

@@ -22,6 +22,10 @@ jobs:
 
     steps:
       - uses: actions/checkout@v2
+      - uses: actions/cache@v2
+        with:
+          key: ${{ github.ref }}
+          path: .cache
       - name: Set up python ${{ matrix.python-version }}
         uses: actions/setup-python@v2
         with:
@@ -55,3 +59,6 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
           verbose: true
         if: matrix.coverage
+      - name: Deploy documentation
+        run: mkdocs gh-deploy --force -f docs/mkdocs.yaml
+        if: matrix.documentation && github.ref == 'refs/heads/master'

docs/features.md

@@ -0,0 +1,4 @@
+{%
+   include-markdown "../FEATURES.md"
+%}
+

docs/gen_files.py

@@ -0,0 +1,28 @@
+"""
+Generate the code reference pages.
+"""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+
+for path in sorted(Path("ebcc").rglob("*.py")):
+    module_path = path.relative_to("ebcc").with_suffix("")
+    doc_path = path.relative_to("ebcc").with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+    parts = ["ebcc", *module_path.parts]
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+
+    if not len(parts) or parts[-1] == "__main__" or parts[0] == "codegen":
+        continue
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        identifier = ".".join(parts)
+        fd.write("::: " + identifier + "\n")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)

docs/index.md

@@ -0,0 +1,3 @@
+{%
+   include-markdown "../README.md"
+%}

docs/mkdocs.yaml

@@ -0,0 +1,71 @@
+site_name: ebcc
+
+watch:
+- ../ebcc
+
+theme:
+  name: readthedocs
+
+docs_dir: .
+
+site_dir: ../site
+
+plugins:
+- search
+- gen-files:
+    scripts:
+    - gen_files.py
+- section-index
+- include-markdown
+- mkdocstrings:
+    default_handler: python
+    handlers:
+        python:
+            rendering:
+                show_source: false
+            options:
+                docstring_style: google
+                members_order: source
+                line_length: 100
+                merge_init_into_class: true
+                show_if_no_docstring: false
+                show_root_members_full_path: true
+                show_object_full_path: true
+
+nav:
+- Home: "index.md"
+- Features: "features.md"
+- Code Reference:
+  - Coupled cluster:
+    - Restricted: reference/cc/rebcc.md
+    - Unrestricted: reference/cc/uebcc.md
+    - Generalised: reference/cc/gebcc.md
+    - Base: reference/cc/base.md
+  - Equation of motion:
+    - Restricted: reference/eom/reom.md
+    - Unrestricted: reference/eom/ueom.md
+    - Generalised: reference/eom/geom.md
+    - Base: reference/eom/base.md
+  - Orbital optimisation:
+    - Brueckner:
+      - Restricted: reference/opt/rbrueckner.md
+      - Unrestricted: reference/opt/ubrueckner.md
+      - Generalised: reference/opt/gbrueckner.md
+    - Base: reference/opt/base.md
+  - Core:
+    - Ansatz: reference/core/ansatz.md
+    - Damping: reference/core/damping.md
+    - Dumping: reference/core/dump.md
+    - Logging: reference/core/logging.md
+    - Precision: reference/core/precision.md
+  - Hamiltonian:
+    - Space: reference/ham/space.md
+    - Fock: reference/ham/fock.md
+    - ERIs: reference/ham/eris.md
+    - CDERIs: reference/ham/cderis.md
+    - Bosonic: reference/ham/elbos.md
+    - Base: reference/ham/base.md
+  - Utility:
+    - Permutations: reference/util/permutations.md
+    - Einstein summations: reference/util/einsumfunc.md
+    - Miscellaneous: reference/util/misc.md

ebcc/cc/base.py

@@ -60,19 +60,7 @@ class BaseOptions:
 
 
 class BaseEBCC(ABC):
-    """Base class for electron-boson coupled cluster.
-
-    Attributes:
-        mf: PySCF mean-field object.
-        log: Log to write output to.
-        options: Options for the EBCC calculation.
-        e_corr: Correlation energy.
-        amplitudes: Cluster amplitudes.
-        converged: Convergence flag.
-        lambdas: Cluster lambda amplitudes.
-        converged_lambda: Lambda convergence flag.
-        name: Name of the method.
-    """
+    """Base class for electron-boson coupled cluster."""
 
     # Types
     Options: type[BaseOptions] = BaseOptions

ebcc/cc/gebcc.py

@@ -33,19 +33,7 @@
 
 
 class GEBCC(BaseEBCC):
-    """Restricted electron-boson coupled cluster.
-
-    Attributes:
-        mf: PySCF mean-field object.
-        log: Log to write output to.
-        options: Options for the EBCC calculation.
-        e_corr: Correlation energy.
-        amplitudes: Cluster amplitudes.
-        converged: Convergence flag.
-        lambdas: Cluster lambda amplitudes.
-        converged_lambda: Lambda convergence flag.
-        name: Name of the method.
-    """
+    """Restricted electron-boson coupled cluster."""
 
     # Types
     ERIs = GERIs

ebcc/cc/rebcc.py

@@ -29,19 +29,7 @@
 
 
 class REBCC(BaseEBCC):
-    """Restricted electron-boson coupled cluster.
-
-    Attributes:
-        mf: PySCF mean-field object.
-        log: Log to write output to.
-        options: Options for the EBCC calculation.
-        e_corr: Correlation energy.
-        amplitudes: Cluster amplitudes.
-        converged: Convergence flag.
-        lambdas: Cluster lambda amplitudes.
-        converged_lambda: Lambda convergence flag.
-        name: Name of the method.
-    """
+    """Restricted electron-boson coupled cluster."""
 
     # Types
     ERIs = RERIs

ebcc/cc/uebcc.py

@@ -31,19 +31,7 @@
 
 
 class UEBCC(BaseEBCC):
-    """Unrestricted electron-boson coupled cluster.
-
-    Attributes:
-        mf: PySCF mean-field object.
-        log: Log to write output to.
-        options: Options for the EBCC calculation.
-        e_corr: Correlation energy.
-        amplitudes: Cluster amplitudes.
-        converged: Convergence flag.
-        lambdas: Cluster lambda amplitudes.
-        converged_lambda: Lambda convergence flag.
-        name: Name of the method.
-    """
+    """Unrestricted electron-boson coupled cluster."""
 
     # Types
     ERIs = UERIs

ebcc/core/ansatz.py

@@ -83,16 +83,7 @@ def identifity_to_name(iden: str) -> str:
 
 
 class Ansatz:
-    """Ansatz class.
-
-    Attributes:
-        fermion_ansatz: Fermionic ansatz.
-        boson_ansatz: Rank of bosonic excitations.
-        fermion_coupling_rank: Rank of fermionic term in coupling.
-        boson_coupling_rank: Rank of bosonic term in coupling.
-        density_fitting: Use density fitting.
-        module_name: Name of the module containing the generated equations.
-    """
+    """Ansatz class."""
 
     def __init__(
         self,

ebcc/core/damping.py

@@ -11,13 +11,7 @@
 
 
 class DIIS(diis.DIIS):
-    """Direct inversion in the iterative subspace.
-
-    Attributes:
-        space: The number of vectors to store in the DIIS space.
-        min_space: The minimum number of vectors to store in the DIIS space.
-        damping: The damping factor to apply to the extrapolated vector.
-    """
+    """Direct inversion in the iterative subspace."""
 
     def __init__(self, space: int = 6, min_space: int = 1, damping: float = 0.0) -> None:
         """Initialize the DIIS object.

ebcc/eom/base.py

@@ -47,12 +47,7 @@ class BaseOptions:
 
 
 class BaseEOM(ABC):
-    """Base class for equation-of-motion coupled cluster.
-
-    Attributes:
-        ebcc: Parent `EBCC` object.
-        options: Options for the EBCC calculation.
-    """
+    """Base class for equation-of-motion coupled cluster."""
 
     # Types
     Options = BaseOptions

ebcc/ham/base.py

@@ -33,17 +33,7 @@ def __getitem__(self, key: str) -> Any:
 
 
 class BaseFock(BaseHamiltonian):
-    """Base class for Fock matrices.
-
-    Attributes:
-        cc: Coupled cluster object.
-        space: Space object.
-        mo_coeff: Molecular orbital coefficients.
-        array: Fock matrix in the MO basis.
-        g: Namespace containing blocks of the electron-boson coupling matrix.
-        shift: Shift parameter.
-        xi: Boson parameters.
-    """
+    """Base class for Fock matrices."""
 
     def __init__(
         self,
@@ -109,13 +99,7 @@ def __init__(
 
 
 class BaseElectronBoson(BaseHamiltonian):
-    """Base class for electron-boson coupling matrices.
-
-    Attributes:
-        cc: Coupled cluster object.
-        space: Space object.
-        array: Electron-boson coupling matrix in the MO basis.
-    """
+    """Base class for electron-boson coupling matrices."""
 
     def __init__(
         self,

ebcc/ham/cderis.py

@@ -18,14 +18,7 @@
 
 
 class RCDERIs(BaseERIs):
-    """Restricted Cholesky-decomposed ERIs container class.
-
-    Attributes:
-        cc: Coupled cluster object.
-        space: Space object for each index.
-        mo_coeff: Molecular orbital coefficients for each index.
-        array: ERIs in the MO basis.
-    """
+    """Restricted Cholesky-decomposed ERIs container class."""
 
     def __getitem__(self, key: str, e2: Optional[bool] = False) -> NDArray[float]:
         """Just-in-time getter.
@@ -93,14 +86,7 @@ def __getitem__(self, key: str, e2: Optional[bool] = False) -> NDArray[float]:
 
 
 class UCDERIs(BaseERIs):
-    """Unrestricted Cholesky-decomposed ERIs container class.
-
-    Attributes:
-        cc: Coupled cluster object.
-        space: Space object for each index.
-        mo_coeff: Molecular orbital coefficients for each index.
-        array: ERIs in the MO basis.
-    """
+    """Unrestricted Cholesky-decomposed ERIs container class."""
 
     _members: dict[str, RCDERIs]
 

ebcc/ham/elbos.py

@@ -12,13 +12,7 @@
 
 
 class RElectronBoson(BaseElectronBoson):
-    """Restricted electron-boson coupling matrices.
-
-    Attributes:
-        cc: Coupled cluster object.
-        space: Space object.
-        array: Electron-boson coupling matrix in the MO basis.
-    """
+    """Restricted electron-boson coupling matrices."""
 
     _members: dict[str, NDArray[float]]
 
@@ -40,13 +34,7 @@ def __getitem__(self, key: str) -> NDArray[float]:
 
 
 class UElectronBoson(BaseElectronBoson):
-    """Unrestricted electron-boson coupling matrices.
-
-    Attributes:
-        cc: Coupled cluster object.
-        space: Space object.
-        array: Electron-boson coupling matrix in the MO basis.
-    """
+    """Unrestricted electron-boson coupling matrices."""
 
     _members: dict[str, RElectronBoson]
 
@@ -72,13 +60,7 @@ def __getitem__(self, key: str) -> RElectronBoson:
 
 
 class GElectronBoson(BaseElectronBoson):
-    """Generalised electron-boson coupling matrices.
-
-    Attributes:
-        cc: Coupled cluster object.
-        space: Space object.
-        array: Electron-boson coupling matrix in the MO basis.
-    """
+    """Generalised electron-boson coupling matrices."""
 
     _members: dict[str, NDArray[float]]