Doc cleanup.

Author: shyuep

pyproject.toml

@@ -238,6 +238,7 @@ exclude_lines = [
 
 [tool.pyright]
 reportMissingImports = false
+reportMissingModuleSource = false
 reportPossiblyUnboundVariable = true
 reportUnboundVariable = true
 exclude = ["tests"]

src/matcalc/__init__.py

@@ -24,7 +24,7 @@
 from ._stability import EnergeticsCalc
 from ._surface import SurfaceCalc
 from .config import SIMULATION_BACKEND, clear_cache
-from .utils import UNIVERSAL_CALCULATORS, PESCalculator
+from .utils import UNIVERSAL_CALCULATOR_NAMES, UNIVERSAL_CALCULATORS, PESCalculator
 
 # Provide an alias for loading calculators quickly.
 load_up = PESCalculator.load_universal

src/matcalc/_adsorption.py

@@ -27,32 +27,10 @@
 
 class AdsorptionCalc(PropCalc):
     """
-    Calculator for adsorption energies on surfaces.
-    Combines bulk relaxation, slab generation and relaxation, adsorbate
-    relaxation, and adsorption energy calculations.
-    Uses :class:`RelaxCalc` for structure relaxations.
-    Parameters allow control over which parts are relaxed and how.
-
-    :param calculator: An ASE calculator object used to perform energy and force
-        calculations. If string is provided, the corresponding universal calculator is loaded.
-    :type calculator: Calculator | str
-    :param relax_adsorbate: Whether to relax the adsorbate structure. If note relaxed,
-        a single point or the adsorbate energy provided downstream is used. Default is True.
-    :type relax_adsorbate: bool, optional
-    :param relax_slab: Whether to relax each clean slab structure (cell fixed). Default is True.
-    :type relax_slab: bool, optional
-    :param relax_bulk: Whether to relax the bulk structure used to generate slabs, including its cell. Default is True.
-    :type relax_bulk: bool, optional
-    :param fmax: Force tolerance in eV/Å for relaxation. Default is 0.1.
-    :type fmax: float, optional
-    :param optimizer: The ASE optimizer to use in RelaxCalc. Can be a string (e.g. "BFGS") or
-        an :class:`Optimizer` instance. Default is "BFGS".
-    :type optimizer: str | Optimizer, optional
-    :param max_steps: Maximum number of optimization steps for relaxation. Default is 500.
-    :type max_steps: int, optional
-    :param relax_calc_kwargs: Additional keyword arguments passed to the
-        :class:`RelaxCalc` constructor for both bulk and slabs. Default is None.
-    :type relax_calc_kwargs: dict | None, optional
+    Adsorption energies on surfaces via bulk, slab, adsorbate, and adslab relaxations.
+
+    Uses ``RelaxCalc`` for geometry optimizations. Attributes mirror constructor arguments
+    plus optional cached bulk state after ``calc_bulk`` / ``calc_adslabs``.
     """
 
     def __init__(
@@ -68,27 +46,15 @@ def __init__(
         relax_calc_kwargs: dict[str, Any] | None = None,
     ) -> None:
         """
-        Initialize the AdsorptionCalc.
-
-        :param calculator: An ASE calculator object used to perform energy and force
-            calculations. If string is provided, the corresponding universal calculator is loaded.
-        :type calculator: Calculator | str
-        :param relax_adsorbate: Whether to relax the adsorbate structure. Default is True.
-        :type relax_adsorbate: bool, optional
-        :param relax_slab: Whether to relax each slab structure (cell fixed). Default is True.
-        :type relax_slab: bool, optional
-        :param relax_bulk: Whether to relax the bulk structure, including its cell. Default is True.
-        :type relax_bulk: bool, optional
-        :param fmax: Force tolerance in eV/Å for relaxation. Default is 0.1.
-        :type fmax: float, optional
-        :param optimizer: The ASE optimizer to use. Can be a string (e.g. "BFGS") or
-            an :class:`Optimizer` instance. Default is "BFGS".
-        :type optimizer: str | Optimizer, optional
-        :param max_steps: Maximum number of optimization steps for relaxation. Default is 500.
-        :type max_steps: int, optional
-        :param relax_calc_kwargs: Additional keyword arguments passed to the
-            :class:`RelaxCalc` constructor for both bulk and slabs. Default is None.
-        :type relax_calc_kwargs: dict | None, optional
+        Args:
+            calculator: ASE calculator or universal model name string.
+            relax_adsorbate: Relax isolated adsorbate in a box when True.
+            relax_slab: Relax clean slab (fixed cell) when True.
+            relax_bulk: Relax bulk with cell when True.
+            fmax: Force tolerance (eV/Å).
+            optimizer: ASE optimizer name or class.
+            max_steps: Max relaxation steps.
+            relax_calc_kwargs: Optional kwargs for ``RelaxCalc``.
         """
         self.calculator = calculator  # type: ignore[assignment]
         self.relax_adsorbate = relax_adsorbate
@@ -109,15 +75,12 @@ def calc_bulk(
         bulk_energy: float | None = None,
     ) -> dict[str, Any]:
         """
-        Prepare the bulk structure for slab generation, optionally relaxing it.
-
-        :param bulk: The bulk structure to be calculated.
-        :type bulk: Structure | Atoms
-        :param bulk_energy: Optional pre-calculated energy of the bulk. If not provided,
-            the bulk will be relaxed and its energy calculated.
-        :type bulk_energy: float | None, optional
-        :return: A dictionary containing the bulk energy and final structure.
-        :rtype: dict[str, Any]
+        Args:
+            bulk: Bulk pymatgen structure or ASE atoms.
+            bulk_energy: If ``relax_bulk`` is False and this is set, used as energy; else relaxed.
+
+        Returns:
+            Dict with ``final_structure`` and ``energy`` (when available).
         """
         initial_bulk = to_pmg_structure(bulk)
 
@@ -147,12 +110,12 @@ def calc_adsorbate(
         adsorbate_energy: float | None = None,
     ) -> dict[str, Any]:
         """
-        Calculate the energy of the adsorbate, optionally relaxing it.
+        Args:
+            adsorbate: Adsorbate as molecule or atoms.
+            adsorbate_energy: Optional fixed energy; otherwise from calculator on final geometry.
 
-        :param adsorbate: The adsorbate structure to be calculated.
-        :type adsorbate: Molecule | Atoms
-        :return: A dictionary containing the adsorbate energy and final structure.
-        :rtype: dict[str, Any]
+        Returns:
+            Dict with ``adsorbate_energy``, ``adsorbate``, ``final_adsorbate``.
         """
         initial_adsorbate = to_pmg_molecule(adsorbate)
 
@@ -196,15 +159,12 @@ def calc_slab(
         slab_energy: float | None = None,
     ) -> dict[str, Any]:
         """
-        Calculate the energy of the slab, optionally relaxing it.
-
-        :param slab: The slab structure to be calculated.
-        :type slab: Structure | Atoms
-        :param slab_energy: Optional pre-calculated energy of the slab. If not provided,
-            the slab will be relaxed and its energy calculated.
-        :type slab_energy: float | None, optional
-        :return: A dictionary containing the slab energy and final structure.
-        :rtype: dict[str, Any]
+        Args:
+            slab: Slab structure or atoms.
+            slab_energy: Optional total slab energy; if None, taken from calculator.
+
+        Returns:
+            Dict with ``slab``, ``slab_energy``, ``slab_energy_per_atom``, ``final_slab``.
         """
         if self.relax_slab:
             relaxer = RelaxCalc(
@@ -257,53 +217,28 @@ def calc_adslabs(  # noqa: C901
         **kwargs: dict[str, Any],
     ) -> list[dict[str, Any]] | dict[Any, Any]:
         """
-        Calculate adsorption energies for adsorbates on slabs generated from a bulk structure.
-        :param adsorbate: The adsorbate structure to be placed on the slab.
-        :type adsorbate: Molecule | Atoms
-        :param bulk: The bulk structure from which slabs will be generated. Be careful
-            to provide conventional cells if that is your intention for miller indices.
-        :type bulk: Structure | Atoms
-        :param miller_index: The Miller index defining the slab orientation.
-        :type miller_index: tuple[int, int, int]
-        :param adsorbate_energy: Optional pre-calculated energy of the adsorbate. If not provided,
-            the adsorbate will be relaxed and its energy calculated.
-        :type adsorbate_energy: float | None, optional
-        :param min_slab_size: Minimum thickness of the slab in Å. Default is 10.0.
-        :type min_slab_size: float, optional
-        :param min_vacuum_size: Minimum size of the vacuum layer in Å. Default is 20.0.
-        :type min_vacuum_size: float, optional
-        :param min_area_extent: Minimum in-plane dimensions of the slab in Å. If provided,
-            the slab will be expanded to at least these dimensions in the a and perpendicular
-            to a directions by projecting the b lattice vector onto a. Default is None.
-        :type min_area_extent: tuple[float, float] | None, optional
-        :param inplane_supercell: Tuple defining the in-plane supercell size. Default is (1, 1).
-        :type inplane_supercell: tuple[int, int], optional
-        :param slab_gen_kwargs: Additional keyword arguments passed to the SlabGenerator. Default is None.
-        :type slab_gen_kwargs: dict[str, Any] | None, optional
-        :param get_slabs_kwargs: Additional keyword arguments passed to the get_slabs method of
-            SlabGenerator. Default is None.
-        :type get_slabs_kwargs: dict[str, Any] | None, optional
-        :param adsorption_sites: Either a string specifying which adsorption sites to consider
-            (e.g., "all", "ontop", "bridge", "hollow"), or a dictionary specifying custom adsorption sites
-            with site names as keys and lists of fractional coordinates as values.
-            Default is "all".
-        :type adsorption_sites: dict[str:tuple[float, float]] | str, optional
-        :param height: Height above the surface to place the adsorbate in Å. Default is 0.9.
-        :type height: float, optional
-        :param mi_vec: Optional in-plane vector defining the slab orientation. If None, it is
-            automatically determined. Default is None.
-        :type mi_vec: tuple[float, float] | None, optional
-        :param fixed_height: Height below which slab atoms are fixed during relaxation in Å.
-            Default is 5 Å.
-        :type fixed_height: float, optional
-        :param find_adsorption_sites_args: Additional keyword arguments passed to the
-            find_adsorption_sites method of AdsorbateSiteFinder. Default is None.
-        :type find_adsorption_sites_args: dict[str, Any] | None, optional
-        :param dry_run: If True, only generates the adslab structures without performing calculations.
-            Default is False.
-        :type dry_run: bool, optional
-        :return: A list of dictionaries containing results for each adslab, or just the structures if dry_run is True.
-        :rtype: list[dict[str, Any]] | dict[Any, Any].
+        Args:
+            adsorbate: Adsorbate species.
+            bulk: Bulk structure (use conventional cell if needed for Miller indices).
+            miller_index: Surface orientation.
+            adsorbate_energy: Optional fixed adsorbate energy.
+            slab_energy: Optional fixed clean-slab energy for all slabs.
+            min_slab_size: Minimum slab thickness (Å).
+            min_vacuum_size: Vacuum thickness (Å).
+            min_area_extent: Minimum in-plane extent (Å); may expand ``inplane_supercell``.
+            inplane_supercell: In-plane supercell factors.
+            slab_gen_kwargs: Kwargs for ``SlabGenerator``.
+            get_slabs_kwargs: Kwargs for ``SlabGenerator.get_slabs``.
+            adsorption_sites: ``"all"``, site name string, or custom fractional-coordinate dict.
+            height: Adsorbate height above surface (Å).
+            mi_vec: Optional in-plane vector for ``AdsorbateSiteFinder``.
+            fixed_height: Fix slab atoms below this height (Å) during relaxation.
+            find_adsorption_sites_args: Kwargs for ``find_adsorption_sites``.
+            dry_run: If True, return adslab dicts without ``calc_many``.
+            **kwargs: Forwarded to ``calc_many``.
+
+        Returns:
+            List of per-configuration results, or raw adslab dicts if ``dry_run``.
         """
         adslab_dict = {}
         bulk = to_pmg_structure(bulk)
@@ -406,13 +341,12 @@ def calc(
         structure: dict[str, Any],  # type: ignore[override]
     ) -> dict[str, Any]:
         """
-        Calculate the adsorption energy for a given adslab structure.
+        Args:
+            structure: Dict with ``adslab``, ``slab``, ``adsorbate``; optional ``slab_energy`` /
+                ``adsorbate_energy``.
 
-        :param structure: A dictionary containing 'adslab', 'slab', and 'adsorbate' structures,
-            and optionally 'slab_energy' and/or 'adsorbate_energy'.
-        :type structure: dict[str, Any]
-        :return: A dictionary containing the adsorption energy and related information.
-        :rtype: dict[str, Any]
+        Returns:
+            Dict including ``adsorption_energy`` and merged slab/adsorbate fields.
         """
         result_dict = structure.copy()
 

src/matcalc/_base.py

@@ -40,7 +40,7 @@ def calculator(self) -> Calculator:
         and controlled access to the underlying calculator.
 
         Returns:
-            Calculator: The internal `Calculator` instance.
+            The internal ASE calculator instance.
         """
         return self._pes_calculator
 
@@ -51,16 +51,8 @@ def calculator(self, val: str | Calculator) -> None:
         loads the universal PESCalculator using the given value. Otherwise, it sets
         the provided Calculator instance.
 
-        Parameters:
-            val (str | Calculator): The new value to assign to the calculator property.
-            It can either be a string representing a PESCalculator configuration or an
-            existing Calculator object.
-
-        Returns:
-            None
-
-        Exceptions:
-            None
+        Args:
+            val: Universal model name string or an existing ASE calculator instance.
         """
         self._pes_calculator = PESCalculator.load_universal(val) if isinstance(val, str) else val
 
@@ -116,25 +108,16 @@ def calc_many(
         `None` for those structures, without raising exceptions.
 
         Args:
-            structures (Sequence[Structure | dict[str, Any] | Atoms]): A sequence of structures
-                to be processed. Each structure can be represented as `Structure`, a dictionary
-                containing structure-related data, or `Atoms`.
-            n_jobs (None | int, optional): The number of jobs to use for parallel processing. If
-                `None`, the default parallelism settings of the `Parallel` utility will be used.
-                Defaults to `None`.
-            allow_errors (bool, optional): If `True`, exceptions encountered during the
-                calculation of a structure will be caught, and `None` will be returned for that
-                structure. If `False`, the exception is raised. Defaults to `False`.
-            **kwargs (Any): Additional keyword arguments to pass to the `Parallel` utility.
+            structures: Sequence of structures or structure dicts.
+            n_jobs: ``joblib`` worker count; ``None`` uses joblib defaults.
+            allow_errors: If True, failed structures yield ``None`` instead of raising.
+            **kwargs: Forwarded to ``joblib.Parallel``.
 
-        Returns:
-            Generator[dict | None, None, None]: A generator that yields the results of the
-                calculations for the input structures. If an exception occurs and `allow_errors`
-                is `True`, `None` will be yielded for the corresponding structure.
+        Yields:
+            Result dict from ``calc``, or ``None`` when ``allow_errors`` and a structure fails.
 
         Raises:
-            Exception: If any error occurs during the calculation of a structure and
-                `allow_errors` is `False`, the exception will be raised.
+            Exception: Any error from ``calc`` when ``allow_errors`` is False.
         """
         parallel = Parallel(n_jobs=n_jobs, return_as="generator", **kwargs)
 
@@ -177,7 +160,7 @@ def calc(self, structure: Structure | Atoms | dict[str, Any]) -> dict[str, Any]:
                 by an elasticity calculation.
 
         Returns:
-            dict[str, Any]: In the form {"prop_name": value}.
+            Merged dict from all steps (final keys depend on the chain).
         """
         results = structure  # type:ignore[assignment]
         for prop_calc in self.prop_calcs:

src/matcalc/_cli.py

@@ -17,12 +17,7 @@
 
 
 def calculate_property(args: Any) -> None:
-    """
-    Implements calculate property.
-
-    :param args:
-    :return:
-    """
+    """Run the selected PropCalc on input structure files (from parsed CLI args)."""
     calculator = mtc.load_fp(args.model)
     mod = mtc.__dict__[args.property](calculator)
     results = []
@@ -39,12 +34,7 @@ def calculate_property(args: Any) -> None:
 
 
 def clear_cache(args: Any) -> None:
-    """
-    Clear the benchmark cache.
-
-    :param args:
-    :return:
-    """
+    """Clear the MatCalc benchmark cache (from parsed CLI args)."""
     mtc.clear_cache(confirm=args.yes)
 
 
@@ -74,7 +64,7 @@ def main() -> None:
         "--model",
         dest="model",
         type=str,
-        choices=mtc.UNIVERSAL_CALCULATORS,
+        choices=mtc.UNIVERSAL_CALCULATOR_NAMES,
         default="TensorNet",
         help="Universal MLIP to use.",
     )