update doc

Author: fishjojo

doc/requirements.txt

@@ -3,7 +3,6 @@ jinja2
 sphinx
 numpydoc
 sphinx_copybutton
-sphinx-autodoc-typehints
 matplotlib
 sphinx_design
 nbsphinx

doc/source/conf.py

@@ -20,6 +20,18 @@ def _do_not_evaluate(
   return _evaluate(self, globalns, *args, **kwargs)
 ForwardRef._evaluate = _do_not_evaluate
 
+# Workaround for class attributes
+from sphinx.ext.napoleon.docstring import GoogleDocstring
+def _parse_attributes_section(self, section):
+    fields = []
+    for _name, _type, _desc in self._consume_fields():
+        if not _type:
+            _type = self._lookup_annotation(_name)
+        fields.append((_name, _type, _desc))
+    return self._format_fields('Attributes', fields)
+GoogleDocstring._parse_attributes_section = _parse_attributes_section
+
+
 project = "pyscfad"
 copyright = "2021-2026, Xing Zhang"
 author = "Xing Zhang"
@@ -37,13 +49,12 @@ def _do_not_evaluate(
 #    "IPython.sphinxext.ipython_directive",
 #    "IPython.sphinxext.ipython_console_highlighting",
     "matplotlib.sphinxext.plot_directive",
-#    "numpydoc",
     "sphinx_copybutton",
     "sphinx_design",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
-    "sphinx.ext.napoleon", # if using Google/NumPy docstrings
-    #"sphinx_autodoc_typehints",
+#    "numpydoc",
+    "sphinx.ext.napoleon",
     "sphinx.ext.coverage",
     "sphinx.ext.doctest",
     "sphinx.ext.extlinks",
@@ -57,6 +68,13 @@ def _do_not_evaluate(
     "myst_nb",
 ]
 
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'scipy': ('https://scipy.github.io/devdocs/', None),
+    'pyscf': ('https://pyscf.org/', None),
+}
+
 templates_path = ["_templates"]
 source_suffix = ['.rst', '.ipynb', '.md']
 source_encoding = "utf-8"
@@ -70,8 +88,9 @@ def _do_not_evaluate(
 autosummary_generate = True
 
 napolean_use_rtype = False
-autodoc_typehints_format = "short"
+napoleon_use_ivar = False
 
+autodoc_typehints_format = "short"
 autodoc_typehints = "description"
 autodoc_typehints_description_target = "all"
 autodoc_type_aliases = {

pyscfad/gto/mole_lite.py

@@ -11,10 +11,10 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+
 """
-Lightweight ``mole`` module.
+Lightweight :mod:`~pyscfad.gto.mole` module.
 """
-
 from __future__ import annotations
 from collections.abc import Callable
 import contextlib
@@ -212,12 +212,12 @@ def intor(
                 `0` (no symmetry), `1` (hermitian), and `2` (anti-hermitian).
             aosym: Permutation symmetry of 2e integrals, can be
                 `s1`, `s2`, `s4`, and `s8`.
-            out: Not used.
+            out: Unused.
             shls_slice: Label the start-stop shells for each index in the integral.
                 For example, the 8-element tuple for the 2e integral
                 tensor ``(ij|kl) = intor('int2e')`` are specified as
                 ``(i0, i1, j0, j1, k0, k1, l0, l1)``.
-            grids: Not used.
+            grids: Unused.
 
         Returns:
             Computed integral as an array.
@@ -311,7 +311,7 @@ def from_pyscf(
         trace_coords: bool = False,
         trace_basis: bool = False,
     ) -> MoleLite:
-        """Initialize from :class:`pyscf.gto.Mole` object.
+        """Initialize from the pyscf :class:`~pyscf.gto.mole.Mole` object.
         """
         if not mol._built:
             raise KeyError(f"{mol} not built")
@@ -348,7 +348,7 @@ def to_pyscf(
         output: str | None = None,
         max_memory: int | None = None,
     ) -> MoleBase:
-        """Convert to :class:`pyscf.gto.Mole` object.
+        """Convert to the pyscf :class:`~pyscf.gto.mole.Mole` object.
         """
         coords = ops.to_numpy(self.coords)
         atom = [[a, tuple(x.tolist())] for a, x in zip(self.symbols, coords)]
@@ -382,6 +382,7 @@ def gaussian_int(
     alpha: ArrayLike,
 ) -> Array:
     r"""Gaussian integral.
+
     Computes :math:`\int_0^\infty x^n exp(-\alpha x^2) dx`.
     """
     from pyscfad.scipy.special import gamma
@@ -457,7 +458,7 @@ def make_env(
     mol: MoleLite,
 ) -> tuple[numpy.ndarray, numpy.ndarray, Array]:
     """Make ``_atm``, ``_bas``, and ``_env`` for
-    interfacing with libcint.
+    interfacing with ``libcint``.
     """
     pre_env = np.zeros(PTR_ENV_START)
     _env = [pre_env]

pyscfad/pbc/scf/test/test_hf.py

@@ -140,5 +140,5 @@ def hf_energy(cell):
     e_tot_ref = mf_ref.kernel()
     mf_grad = pyscf_grad.krhf.Gradients(mf_ref)
     g0 = mf_grad.kernel()
-    assert abs(e_tot - e_tot_ref) < 1e-8
-    assert abs(jac_bwd.coords - g0).max() < 1e-8
+    assert abs(e_tot - e_tot_ref) < 1e-7
+    assert abs(jac_bwd.coords - g0).max() < 1e-7

pyscfad/pbc/scf/test/test_khf.py

@@ -155,6 +155,6 @@ def hf_energy(cell, kpts):
     mf_grad = pyscf_grad.krhf.Gradients(mf_ref)
     g0 = mf_grad.kernel()
 
-    assert abs(e_tot - e_tot_ref) < 1e-8
-    #assert abs(jac_fwd.coords - g0).max() < 1e-8
-    assert abs(jac_bwd.coords - g0).max() < 1e-8
+    assert abs(e_tot - e_tot_ref) < 1e-7
+    #assert abs(jac_fwd.coords - g0).max() < 1e-7
+    assert abs(jac_bwd.coords - g0).max() < 1e-7

pyscfad/scf/anderson.py

@@ -11,7 +11,9 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
+"""
+Anderson mixing
+"""
 from typing import NamedTuple, Any
 import operator
 import jax

pyscfad/scf/cphf.py

@@ -11,7 +11,9 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
+"""
+Coupled perturbed Hartree-Fock
+"""
 from jax.scipy.sparse.linalg import gmres
 from pyscfad.lib import logger
 

pyscfad/scf/diis.py

@@ -11,7 +11,9 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
+"""
+DIIS
+"""
 from pyscf.scf import diis as pyscf_cdiis
 from pyscfad import numpy as np
 from pyscfad import ops

pyscfad/scf/hf.py

@@ -11,7 +11,9 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
+"""
+Restricted Hartree-Fock
+"""
 from functools import partial
 import numpy
 

pyscfad/scf/hf_lite.py

@@ -12,6 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Lightweight :mod:`~pyscfad.scf.hf` module.
+"""
 from __future__ import annotations
 from typing import Any
 from functools import partial
@@ -115,9 +118,8 @@ def update_dm(
 ) -> tuple[float, float, Array, Array, Array, float, Any]:
     """Single SCF step updating the density matrix.
 
-    Notes
-    -----
-    This function generally has side effects to ``diis``.
+    Notes:
+        This function generally has side effects to ``diis``.
     """
     log = logger.new_logger(mf)
 
@@ -291,19 +293,26 @@ def kernel(
     return scf_conv, e_tot, mo_energy, mo_coeff, mo_occ
 
 class SCF(SCFBase):
-    """Molecular SCF (mean-field) methods.
-
-    Parameters
-    ----------
-    mol
-        Molecular information.
+    r"""Molecular SCF (mean-field) methods.
+
+    Args:
+        mol: Molecular information.
+
+    Attributes:
+        diis: SCF solver. Default uses the Anderson mixing.
+        use_sp2: Whether to use the SP2 density purification solver.
+        conv_tol_dm: Convergence threshold used for the SP2 solver.
+        sigma: Smearning temperature :math:`k_B T` in Eh.
+        smearing_method: Smearning method.
+            Only Fermi-Dirac (``fermi``) distribution is supported.
+        veff_with_ecoul: Whether ``get_veff`` returns a :class:`~pyscfad.dft.rks.VXC` object.
     """
-    diis = None
-    use_sp2 = False
-    conv_tol_dm = None
-    sigma = None
-    smearing_method = "fermi"
-    veff_with_ecoul = False
+    diis: Any | None = None
+    use_sp2: bool = False
+    conv_tol_dm: float | None = None
+    sigma: float | None = None
+    smearing_method: str = "fermi"
+    veff_with_ecoul: bool = False
 
     def __init__(
         self,
@@ -412,9 +421,8 @@ def mo_mask(
 
         Useful for e.g. padding, where there are fake MOs.
 
-        Returns
-        -------
-        mask : Mask array where elements with ``True`` values indicate real MOs.
+        Returns:
+            mask: Mask array where elements with ``True`` values indicate real MOs.
         """
         if mo_energy is None:
             mo_energy = self.mo_energy
@@ -442,10 +450,8 @@ def dip_moment(
     ) -> Array:
         """Molecular dipole moment.
 
-        Parameters
-        ----------
-        charges
-            Nuclear charges.
+        Parameters:
+            charges: Nuclear charges.
         """
         if mol is None:
             mol = self.mol