diff --git a/atomdb/datasets/__init__.py b/atomdb/datasets/__init__.py
index 4146fdae..8bb174da 100644
--- a/atomdb/datasets/__init__.py
+++ b/atomdb/datasets/__init__.py
@@ -12,3 +12,174 @@
#
# You should have received a copy of the GNU General Public License
# along with AtomDB. If not, see .
+
+DATASET_PROPERTIES = {
+ # General Properties
+ # ==================
+ "elem": {"TYPE": "GENERAL", "DESC": "Refers to an element from the Periodic Table."},
+ "dataset": {
+ "TYPE": "GENERAL",
+ "DESC": "Aggregated information about molecular structures and properties.",
+ },
+ "basis": {
+ "TYPE": "GENERAL",
+ "DESC": "Standard used to approximate the molecular orbitals within a computational method. "
+ "Provides a basis for expressing the wavefunction of a molecule. Significantly influence "
+ "the accuracy of quantum chemical calculations.",
+ },
+ # Scalar Properties
+ # =================
+ "mass": {"TYPE": "SCALAR", "DESC": "Atomic mass of the element."},
+ "energy": {
+ "TYPE": "SCALAR",
+ "DESC": "Energy associated with electronic config of species or energy levels of molecular orbitals.",
+ },
+ "ip": {
+ "TYPE": "SCALAR",
+ "DESC": "Ionization Potential (energy req. to remove an electron from atom or species / molecule. "
+ "Key parameter in understanding reactivity and electronic structure of species / molecules.",
+ },
+ "nexc": {
+ "TYPE": "SCALAR",
+ "DESC": "Electronic State Number. Currently defaults to ground state and is set to 0.",
+ },
+ "natom": {
+ "TYPE": "SCALAR",
+ "DESC": "Count of individual atoms within species / molecular system. Fundamental parameter used to "
+ "characterize size and complexity of molecules.",
+ },
+ "nelec": {
+ "TYPE": "SCALAR",
+ "DESC": "Count of electrons within a species / molecular system. Distribution of electrons among "
+ "atomic orbitals determines many chemical and physical properties of species / molecules.",
+ },
+ "nspin": {
+ "TYPE": "SCALAR",
+ "DESC": "Count of distinct spin configs available to a species / molecular system. Particularly "
+ "relevant in systems with unpaired electrons, where spin multiplicity influences electronic "
+ "properties and reactivity.",
+ },
+ "vdw_radii": {
+ "TYPE": "SCALAR",
+ "DESC": "Van der Waals radii. Represents effective size of atoms or molecules in terms "
+ "of their non-bonded interactions. Often used to estimate intermolecular distances "
+ "and important for understanding molecular packing and interactions.",
+ },
+ "cov_radii": {
+ "TYPE": "SCALAR",
+ "DESC": "Covalent radii. Represents sizes of atoms based on the lengths of their covalent "
+ "bonds in molecules. Important for estimating bond lengths and molecular geometries.",
+ },
+ "mu": {
+ "TYPE": "SCALAR",
+ "DESC": "Chemical potential. Partial derivative of the total energy of a system "
+ "with respect to the number of electrons. Signifies the energy required to add "
+ "an extra electron to a system.",
+ },
+ "eta": {
+ "TYPE": "SCALAR",
+ "DESC": "Damping / Broadening factor. Used in computational chemistry calculations. "
+ "Conceptual Density Functional Theory (DFT) related property.",
+ },
+ "rs": {
+ "TYPE": "SCALAR",
+ "DESC": "Radial Grid. Represents the distances between adjacent grid points on the "
+ "grid used to discretize the space around the molecular system. Crucial for "
+ "accurate representation of the distribution of electrons and other properties "
+ "within the system. Determines resolution and accuracy of calculations "
+ "involving the molecular structure.",
+ },
+ "dens_tot": {
+ "TYPE": "SCALAR",
+ "DESC": "Total electron density in the system. Includes contributions from all "
+ "electrons, regardless of their spin (both and up and down spins)",
+ },
+ "ked_tot": {
+ "TYPE": "SCALAR",
+ "DESC": "Total total kinetic energy density in the system. Includes contributions "
+ "from all electrons, regardless of their spin (both and up and down spins)",
+ },
+ # Vector Properties
+ # =================
+ "mo_e_up": {
+ "TYPE": "VECTOR",
+ "DESC": "Energy levels of the molecular orbitals for spin-up electrons",
+ },
+ "mo_e_dn": {
+ "TYPE": "VECTOR",
+ "DESC": "Energy levels of the molecular orbitals for spin-down electrons",
+ },
+ "occs_up": {
+ "TYPE": "VECTOR",
+ "DESC": "Occupation numbers (spin-up). Number of electrons in each molecular orbital for "
+ "spin-up electrons",
+ },
+ "occs_dn": {
+ "TYPE": "VECTOR",
+ "DESC": "Occupation numbers (spin-down). Number of electrons in each molecular orbital for "
+ "spin-down electrons",
+ },
+ "_orb_dens_up": {
+ "TYPE": "VECTOR",
+ "DESC": "Orbital densities for spin-up electrons. Describes the probability density "
+ "of finding an electron in a particular orbital",
+ },
+ "_orb_dens_dn": {
+ "TYPE": "VECTOR",
+ "DESC": "Orbital densities for spin-down electrons. Describes the probability density "
+ "of finding an electron in a particular orbital",
+ },
+ "_orb_ked_up": {
+ "TYPE": "VECTOR",
+ "DESC": "Kinetic Energy Densities (KED) for spin-up electrons. Describe the "
+ "distribution of kinetic energy per unit volume associated with the motion of electrons.",
+ },
+ "_orb_ked_dn": {
+ "TYPE": "VECTOR",
+ "DESC": "Kinetic Energy Densities (KED) for spin-down electrons. Describe the "
+ "distribution of kinetic energy per unit volume associated with the motion of electrons.",
+ },
+ # Default Property
+ # ================
+ "_": {"TYPE": "NA", "DESC": "Property Information Not Found"},
+}
+
+
+def generate_property_docs(properties, n=1, doctype="DOCSTRING"):
+ lookup, docs = {"GENERAL": [], "SCALAR": [], "VECTOR": [], "MISCELLANEOUS": []}, "\n"
+
+ for prop in properties:
+ attr = DATASET_PROPERTIES.get(prop, DATASET_PROPERTIES["_"])
+ if attr["TYPE"] == "GENERAL":
+ lookup["GENERAL"].append(prop)
+ elif attr["TYPE"] == "SCALAR":
+ lookup["SCALAR"].append(prop)
+ elif attr["TYPE"] == "VECTOR":
+ lookup["VECTOR"].append(prop)
+ else:
+ lookup["MISCELLANEOUS"].append(prop)
+
+ for category, props in lookup.items():
+ if len(props) > 0:
+ if doctype == "DOCSTRING":
+ docs += "\n" f"{category} Properties\n" "========================\n"
+ for prop in props:
+ attr = DATASET_PROPERTIES.get(prop, DATASET_PROPERTIES["_"])
+ docs += " ".join(
+ f"> \033[1;32;40m{prop}\033[0m ({attr['TYPE']}): {attr['DESC']}".split(".")[
+ :n
+ ]
+ + ["\n"]
+ )
+ else:
+ docs += (
+ f"""\n.. list-table:: **Table.** Available {category} Properties for Dataset.\n"""
+ """ :widths: 50 100 \n"""
+ """ :header-rows: 1 \n\n"""
+ )
+ docs += """ * - Property \n""" """ - Description \n"""
+ for prop in props:
+ attr = DATASET_PROPERTIES.get(prop, DATASET_PROPERTIES["_"])
+ docs += f""" * - ``{prop}`` \n""" f""" - {attr['DESC']} \n"""
+ docs += "\n"
+ return docs
diff --git a/atomdb/datasets/gaussian/__init__.py b/atomdb/datasets/gaussian/__init__.py
index d5790940..5710c6d4 100644
--- a/atomdb/datasets/gaussian/__init__.py
+++ b/atomdb/datasets/gaussian/__init__.py
@@ -37,12 +37,52 @@
import atomdb
from atomdb.periodic import Element
-
+from atomdb.datasets import generate_property_docs
__all__ = [
"run",
]
+METADATA = {}
+METADATA["PROPERTIES"] = {
+ "dataset",
+ "elem",
+ "natom",
+ "basis",
+ "nelec",
+ "nspin",
+ "nexc",
+ "cov_radii",
+ "vdw_radii",
+ "mass",
+ "energy",
+ "ip",
+ "mu",
+ "eta",
+ "rs",
+ "mo_e_up",
+ "mo_e_dn",
+ "occs_up",
+ "occs_dn",
+ "_orb_dens_up",
+ "_orb_dens_dn",
+ "dens_tot",
+ "_orb_ked_up",
+ "_orb_ked_dn",
+ "ked_tot",
+}
+METADATA[
+ "DOCSTRING"
+] = """Gaussian basis densities (UHF) Dataset
+Electronic structure and density properties evaluated with def2-svpd basis set"""
+
+# generating the table for the sphinx documentation
+__doc__ = METADATA["DOCSTRING"] + generate_property_docs(METADATA["PROPERTIES"], doctype="SPHINX")
+
+# augmenting the available properties and details to the DOCSTRING
+METADATA["DOCSTRING"] += generate_property_docs(METADATA["PROPERTIES"])
+
+DOCSTRING = METADATA["DOCSTRING"]
# Parameters to generate an atomic grid from uniform radial grid
# Use 170 points, lmax = 21 for the Lebedev grid since our basis
@@ -56,13 +96,6 @@
DEGREE = 21 # Lebedev grid degrees
-DOCSTRING = """Gaussian basis densities (UHF) Dataset
-
-Electronic structure and density properties evaluated with def2-svpd basis set
-
-"""
-
-
def _load_fchk(n_atom, element, n_elec, multi, basis_name, data_path):
r"""Load Gaussian fchk file and return the iodata object
@@ -101,19 +134,21 @@ def _load_fchk(n_atom, element, n_elec, multi, basis_name, data_path):
def eval_orbs_density(one_density_matrix, orb_eval):
r"""Return each orbital density evaluated at a set of points
- rho_i(r) = \sum_j P_ij \phi_i(r) \phi_j(r)
+ .. math::
+
+ rho_i(r) = \sum_j P_ij \phi_i(r) \phi_j(r)
Parameters
----------
- one_density_matrix : np.ndarray(K_orb, K_orb)
+ one_density_matrix : ``np.ndarray(K_orb, K_orb)``
One-electron density matrix (1DM) from K orbitals
- orb_eval : np.ndarray(K_orb, N)
+ orb_eval : ``np.ndarray(K_orb, N)``
orbitals evaluated at a set of grid points (N).
These orbitals must be the basis used to evaluate the 1DM.
Returns
-------
- orb_dens : np.ndarray(K_orb, N)
+ orb_dens : ``np.ndarray(K_orb, N)``
orbitals density at a set of grid points (N)
"""
#
@@ -125,26 +160,26 @@ def eval_orbs_density(one_density_matrix, orb_eval):
def eval_orbs_radial_d_density(one_density_matrix, basis, points, transform=None):
- """Compute the radial derivative of the density orbital components.
+ r"""Compute the radial derivative of the density orbital components.
For a set of points, compute the radial derivative of the density component for each orbital
given the basis set and the basis transformation matrix.
Parameters
----------
- one_density_matrix : np.ndarray(K_orb, K_orb)
+ one_density_matrix : ``np.ndarray(K_orb, K_orb)``
One-electron density matrix in terms of the given basis set.
- basis : gbasis.basis.Basis
+ basis : ``gbasis.basis.Basis``
Basis set used to evaluate the radial derivative of the density
- points : np.ndarray(N, 3)
+ points : ``np.ndarray(N, 3)``
Cartesian coordinates of the points in space (in atomic units) where the derivatives
are evaluated.
- Rows correspond to the points and columns correspond to the :math:`x, y, \text{and} z`
+ Rows correspond to the points and columns correspond to the :math:`x, y, \text{ and } z`
components.
Returns
-------
- radial_orb_d_dens : np.ndarray(K, N)
+ radial_orb_d_dens : ``np.ndarray(K, N)``
Radial derivative of the density at the set of points for each orbital component.
"""
# compute the basis values for the points output shape (K, N)
@@ -173,18 +208,18 @@ def eval_orbs_radial_d_density(one_density_matrix, basis, points, transform=None
def eval_orbs_radial_dd_density(one_density_matrix, basis, points, transform=None):
- """Compute the radial second derivative of the density orbital components.
+ r"""Compute the radial second derivative of the density orbital components.
For a set of points, compute the radial second derivative of the density component for each
orbital given the basis set and the basis transformation matrix.
Parameters
----------
- one_density_matrix : np.ndarray(K_orb, K_orb)
+ one_density_matrix : ``np.ndarray(K_orb, K_orb)``
One-electron density matrix in terms of the given basis set.
- basis : gbasis.basis.Basis
+ basis : ``gbasis.basis.Basis``
Basis set used to evaluate the radial derivative of the density
- points : np.ndarray(N, 3)
+ points : ``np.ndarray(N, 3)``
Cartesian coordinates of the points in space (in atomic units) where the derivatives
are evaluated.
Rows correspond to the points and columns correspond to the :math:`x, y, \text{and} z`
@@ -192,7 +227,7 @@ def eval_orbs_radial_dd_density(one_density_matrix, basis, points, transform=Non
Returns
-------
- radial_dd_orb_dens : np.ndarray(K, N)
+ radial_dd_orb_dens : ``np.ndarray(K, N)``
Radial second derivative of the density at the set of points for each orbital component.
"""
# compute unitary vectors for the directions of the points
@@ -243,23 +278,23 @@ def eval_orbs_radial_dd_density(one_density_matrix, basis, points, transform=Non
def eval_radial_d_density(one_density_matrix, basis, points):
- """Compute the radial derivative of the density.
+ r"""Compute the radial derivative of the density.
For a set of points, compute the radial derivative of the density
given the one-electron density matrix and the basis set.
Parameters
----------
- one_density_matrix : np.ndarray(K_orb, K_orb)
+ one_density_matrix : ``np.ndarray(K_orb, K_orb)``
One-electron density matrix (1DM) from K orbitals
- basis : gbasis.basis.Basis
+ basis : ``gbasis.basis.Basis``
Basis set used to evaluate the radial derivative of the density
- points : np.ndarray(N, 3)
+ points : ``np.ndarray(N, 3)``
Set of points where the radial derivative of the density is evaluated
Returns
-------
- radial_d_density : np.ndarray(N)
+ radial_d_density : ``np.ndarray(N)``
Radial derivative of the density at the set of points
"""
rho_grad = evaluate_density_gradient(one_density_matrix, basis, points)
@@ -270,23 +305,23 @@ def eval_radial_d_density(one_density_matrix, basis, points):
def eval_radial_dd_density(one_density_matrix, basis, points):
- """Compute the radial derivative of the density.
+ r"""Compute the radial derivative of the density.
For a set of points, compute the radial derivative of the density
given the one-electron density matrix and the basis set.
Parameters
----------
- one_density_matrix : np.ndarray(K_orb, K_orb)
+ one_density_matrix : ``np.ndarray(K_orb, K_orb)``
One-electron density matrix (1DM) from K orbitals
- basis : gbasis.basis.Basis
+ basis : ``gbasis.basis.Basis``
Basis set used to evaluate the radial derivative of the density
- points : np.ndarray(N, 3)
+ points : ``np.ndarray(N, 3)``
Set of points where the radial derivative of the density is evaluated
Returns
-------
- radial_dd_density : np.ndarray(N)
+ radial_dd_density : ``np.ndarray(N)``
Radial derivative of the density at the set of points
"""
rho_hess = evaluate_density_hessian(one_density_matrix, basis, points)
@@ -297,7 +332,7 @@ def eval_radial_dd_density(one_density_matrix, basis, points):
def eval_orb_ked(one_density_matrix, basis, points, transform=None):
- "Adapted from Gbasis"
+ r"""Adapted from `theochem/gbasis `_"""
orbt_ked = 0
for orders in np.identity(3, dtype=int):
deriv_orb_eval_one = evaluate_deriv_basis(basis, points, orders, transform=transform)
@@ -309,7 +344,7 @@ def eval_orb_ked(one_density_matrix, basis, points, transform=None):
def run(elem, charge, mult, nexc, dataset, datapath):
- r"""Compile the AtomDB database entry for densities from Gaussian wfn."""
+ r"""Compile the AtomDB database entry for densities from Gaussian Wavefunction File (wfn)."""
# Check arguments
if nexc != 0:
raise ValueError("Nonzero value of `nexc` is not currently supported")
diff --git a/docs/source/_static/css/override.css b/docs/source/_static/css/override.css
index d808337e..71ddd1d8 100644
--- a/docs/source/_static/css/override.css
+++ b/docs/source/_static/css/override.css
@@ -38,6 +38,11 @@ table.docutils tbody tr.row-odd td {
background-color: rgb(252, 252, 252);
}
-div.wy-table-responsive {
+/* div.wy-table-responsive {
max-height: 90vh;
-}
\ No newline at end of file
+} */
+
+p {
+ white-space: normal;
+ text-wrap: wrap;
+}