JDFTx IO module

.gitignore

@@ -27,6 +27,7 @@ setuptools*
 .*_cache
 # VS Code
 .vscode/*
+.coverage*
 
 # Environments
 .env
@@ -37,3 +38,7 @@ ENV/
 env.bak/
 venv.bak/
 .pdm-python
+
+# Local runners
+actions-runner/
+actions-runner/*

pyproject.toml

@@ -305,6 +305,7 @@ skip = """*.json,
 src/pymatgen/analysis/chemenv/coordination_environments/coordination_geometries_files/allcg.txt,
 src/pymatgen/entries/MPCompatibility.yaml,
 tests/io/lammps/test_inputs.py,
+tests/files/io/jdftx/*
 """
 check-filenames = true
 

src/pymatgen/core/periodic_table.py

@@ -33,6 +33,7 @@
 
     from pymatgen.util.typing import SpeciesLike
 
+
 # Load element data from JSON file
 with open(Path(__file__).absolute().parent / "periodic_table.json", encoding="utf-8") as ptable_json:
     _pt_data = json.load(ptable_json)
@@ -213,7 +214,7 @@ def __getattr__(self, item: str) -> Any:
             if val is None or str(val).startswith("no data"):
                 warnings.warn(f"No data available for {item} for {self.symbol}", stacklevel=2)
                 val = None
-            elif isinstance(val, list | dict):
+            elif isinstance(val, dict | list):
                 pass
             else:
                 try:
@@ -486,28 +487,35 @@ def n_electrons(self) -> int:
         return sum(t[-1] for t in self.full_electronic_structure)
 
     @property
-    def valence(self) -> tuple[int | np.nan, int]:
+    def valences(self) -> list[tuple[int | np.nan, int]]:
         """Valence subshell angular moment (L) and number of valence e- (v_e),
         obtained from full electron config, where L=0, 1, 2, or 3 for s, p, d,
         and f orbitals, respectively.
         """
         if self.group == 18:
-            return np.nan, 0  # The number of valence of noble gas is 0
+            return [(np.nan, 0)]  # The number of valence of noble gas is 0
 
         L_symbols = "SPDFGHIKLMNOQRTUVWXYZ"
-        valence: list[tuple[int, int]] = []
+        valences: list[tuple[int | np.nan, int]] = []
         full_electron_config = self.full_electronic_structure
         last_orbital = full_electron_config[-1]
         for n, l_symbol, ne in full_electron_config:
             idx = L_symbols.lower().index(l_symbol)
             if ne < (2 * idx + 1) * 2 or (
-                (n, l_symbol, ne) == last_orbital and ne == (2 * idx + 1) * 2 and len(valence) == 0
+                (n, l_symbol, ne) == last_orbital and ne == (2 * idx + 1) * 2 and len(valences) == 0
             ):  # check for full last shell (e.g. column 2)
-                valence.append((idx, ne))
-        if len(valence) > 1:
-            raise ValueError(f"{self} has ambiguous valence")
+                valences.append((idx, ne))
+        return valences
 
-        return valence[0]
+    @property
+    def valence(self) -> tuple[int | np.nan, int]:
+        """Valence subshell angular moment (L) and number of valence e- (v_e),
+        obtained from full electron config, where L=0, 1, 2, or 3 for s, p, d,
+        and f orbitals, respectively.
+        """
+        if len(self.valences) > 1:
+            raise ValueError(f"{self} has ambiguous valence")
+        return self.valences[0]
 
     @property
     def term_symbols(self) -> list[list[str]]:
@@ -534,7 +542,7 @@ def term_symbols(self) -> list[list[str]]:
         # Total ML = sum(ml1, ml2), Total MS = sum(ms1, ms2)
         TL = [sum(ml_ms[comb[e]][0] for e in range(v_e)) for comb in e_config_combs]
         TS = [sum(ml_ms[comb[e]][1] for e in range(v_e)) for comb in e_config_combs]
-        comb_counter = Counter(zip(TL, TS, strict=True))
+        comb_counter: Counter = Counter(zip(TL, TS, strict=True))
 
         term_symbols = []
         L_symbols = "SPDFGHIKLMNOQRTUVWXYZ"
@@ -1199,28 +1207,35 @@ def n_electrons(self) -> int:
     # NOTE - copied exactly from Element. Refactoring / inheritance may improve
     # robustness
     @property
-    def valence(self) -> tuple[int | np.nan, int]:
-        """Valence subshell angular moment (L) and number of valence e- (v_e),
+    def valences(self) -> list[tuple[int | np.nan, int]]:
+        """List of valence subshell angular moment (L) and number of valence e- (v_e),
         obtained from full electron config, where L=0, 1, 2, or 3 for s, p, d,
         and f orbitals, respectively.
         """
         if self.group == 18:
-            return np.nan, 0  # The number of valence of noble gas is 0
+            return [(np.nan, 0)]  # The number of valence of noble gas is 0
 
         L_symbols = "SPDFGHIKLMNOQRTUVWXYZ"
-        valence: list[tuple[int, int]] = []
+        valences: list[tuple[int | np.nan, int]] = []
         full_electron_config = self.full_electronic_structure
         last_orbital = full_electron_config[-1]
         for n, l_symbol, ne in full_electron_config:
             idx = L_symbols.lower().index(l_symbol)
             if ne < (2 * idx + 1) * 2 or (
-                (n, l_symbol, ne) == last_orbital and ne == (2 * idx + 1) * 2 and len(valence) == 0
+                (n, l_symbol, ne) == last_orbital and ne == (2 * idx + 1) * 2 and len(valences) == 0
             ):  # check for full last shell (e.g. column 2)
-                valence.append((idx, ne))
-        if len(valence) > 1:
-            raise ValueError(f"{self} has ambiguous valence")
+                valences.append((idx, ne))
+        return valences
 
-        return valence[0]
+    @property
+    def valence(self) -> tuple[int | np.nan, int]:
+        """Valence subshell angular moment (L) and number of valence e- (v_e),
+        obtained from full electron config, where L=0, 1, 2, or 3 for s, p, d,
+        and f orbitals, respectively.
+        """
+        if len(self.valences) > 1:
+            raise ValueError(f"{self} has ambiguous valence")
+        return self.valences[0]
 
     @property
     def ionic_radius(self) -> float | None:

src/pymatgen/io/jdftx/__init__.py

@@ -0,0 +1,53 @@
+"""Module for IO with JDFTx.
+
+This module contains all class objects and methods used for io operations with JDFTX.
+
+This includes:
+
+- JDFTXInfile in jdfxinfile.py:
+  - Mutable, sub-classes dictionary
+  - Initializable from pre-existing JDFTx "in" files or dictionaries
+  - Writes new "in" files
+  - Extracts Structure objects
+  - Depends on:
+     - jdftxinfile_master_format.py which contains information on allowed keys
+     - jdftxinfile_ref_options.py which contains lists of valid options
+- JDFTXOutfile in jdftxoutfile.py:
+  - Parses JDFTx "out" file
+  - Contains all typically relevant output variables from a JDFTx geometric optimization or single-point calculation.
+  - Contains hierarchy of class objects (each contained by the former) for storing data at the following
+    call frequencies.
+    - JDFTXOutfileSlice: Per call of JDFTx executable
+      - One "slice" contains all data output in a single call of JDFTx,
+          as broken up in the out file by the "**** JDFTx" flag
+      - JOutStructures: Per call of JDFTx executable (same frequency as parent)
+        - List of JOutStructure, used in building Trajectory objects by JDFTXOutfile
+            (does not inherit Trajectory or Structure)
+      - JOutStructure: Per geometric optimization update (only one for single-point)
+        - Inheritor of Structure object (contains structural data), also contains electronic minimization data
+            (see below) and convergence data relevant to the geometric optimization
+            (forces and Wolfe minimization variables)
+      - JElSteps: Per geometric optimization update (same frequency as parent)
+        - List of JElStep as well as convergence data relevant to electronic optimization.
+      - JElStep: Per SCF update
+        - Contains all electronic data logged in out file at SCF update frequency.
+
+This folder is currently missing:
+
+- Broader output parsing
+  - Future versions will still have JDFTXOutfile and all subclasses. However, this class object will likely not be
+    called directly, and will be a class property of a broader JDFTXOutput class capable of handling dumped output
+    files (ie electronic density arrays or DOS text files) in tandem to the out file.
+- File organization
+  - Future versions will streamline the user-end interface by having all output-related methods imported through the
+    outputs.py module and input-related methods imported through the inputs.py module. Class objects may be moved to
+    these modules from their standalone modules to keep the directory tidy.
+- Sets
+  - Common input sets are currently missing from the sets module.
+"""
+
+from __future__ import annotations
+
+# Importing these within in __init__ so that surface-level imports can be made from the module itself
+from pymatgen.io.jdftx.inputs import JDFTXInfile
+from pymatgen.io.jdftx.outputs import JDFTXOutfile

src/pymatgen/io/jdftx/_input_utils.py

@@ -0,0 +1,38 @@
+"""Module for JDFTx IO module input utils.
+
+Module for JDFTx IO module input utils. Functions kept in this module are here if they are
+used by multiple submodules, or if they are anticipated to be used by multiple
+submodules in the future.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def flatten_list(tag: str, list_of_lists: list[Any]) -> list[Any]:
+    """Flatten list of lists into a single list, then stop.
+
+    Flatten list of lists into a single list, then stop.
+
+    Parameters
+    ----------
+    tag : str
+        The tag to flatten the list of lists for.
+    list_of_lists : list[Any]
+        The list of lists to flatten.
+
+    Returns
+    -------
+    list[Any]
+        The flattened list.
+    """
+    if not isinstance(list_of_lists, list):
+        raise TypeError(f"{tag}: You must provide a list to flatten_list()!")
+    flist = []
+    for v in list_of_lists:
+        if isinstance(v, list):
+            flist.extend(flatten_list(tag, v))
+        else:
+            flist.append(v)
+    return flist