code(METADATA Support): adding support for metadata for gaussian dataset

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 <http://www.gnu.org/licenses/>.
+
+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