matcalc 0.2.2__tar.gz → 0.3.2__tar.gz

{matcalc-0.2.2/src/matcalc.egg-info → matcalc-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matcalc
-Version: 0.2.2
+Version: 0.3.2
 Summary: Calculators for materials properties from the potential energy surface.
 Author-email: Runze Liu <rul048@ucsd.edu>, Eliott Liu <elliottliu17@gmail.com>, Janosh Riebesell <janosh@lbl.gov>, Ji Qi <j1qi@ucsd.edu>, Shyue Ping Ong <ongsp@ucsd.edu>, Tsz Wai Ko <t1ko@ucsd.edu>
 Keywords: AI,deep learning,force field,graph,interatomic potential,machine learning,materials,property prediction,science
@@ -19,32 +19,32 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: ase>=3.23.0
-Requires-Dist: joblib
-Requires-Dist: phonopy
-Requires-Dist: pymatgen
 Requires-Dist: numpy<2.0.0
-Requires-Dist: fsspec
 Requires-Dist: scikit-learn>=1.6.1
+Requires-Dist: pymatgen>=2025.3.10
+Requires-Dist: fsspec>=2025.3.0
+Requires-Dist: joblib>=1.4.2
+Requires-Dist: phonopy>=2.38.0
+Requires-Dist: phono3py>=3.15.0
 Provides-Extra: phonon
 Requires-Dist: seekpath; extra == "phonon"
 Provides-Extra: benchmark
 Requires-Dist: matminer>=0.9.3; extra == "benchmark"
-Provides-Extra: maml
-Requires-Dist: maml>=2025.2.25; extra == "maml"
-Provides-Extra: sevennet
-Requires-Dist: sevenn>=0.10.4; extra == "sevennet"
+Provides-Extra: ace
+Requires-Dist: pyace>=0.1.1; extra == "ace"
 Provides-Extra: mace
 Requires-Dist: mace-torch>=0.3.12; extra == "mace"
-Provides-Extra: nequip
-Requires-Dist: nequip>=0.6.2; extra == "nequip"
+Provides-Extra: deepmd
+Requires-Dist: deepmd-kit>=3.0.2; extra == "deepmd"
 Provides-Extra: grace
 Requires-Dist: tensorpotential>=0.5.1; extra == "grace"
-Provides-Extra: matgl
-Requires-Dist: matgl>=1.2.3; extra == "matgl"
+Provides-Extra: maml
+Requires-Dist: maml>=2025.2.25; extra == "maml"
 Provides-Extra: orb
 Requires-Dist: orb-models>=0.4.2; extra == "orb"
-Provides-Extra: ace
-Requires-Dist: pyace>=0.1.1; extra == "ace"
+Requires-Dist: pynanoflann>=0.10.0; extra == "orb"
+Provides-Extra: sevennet
+Requires-Dist: sevenn>=0.10.4; extra == "sevennet"
 Dynamic: license-file
 
 <h1 align="center">
@@ -52,8 +52,8 @@ Dynamic: license-file
 width="200" alt="MatCalc" style="vertical-align: middle;" /><br>
 </h1>
 
-[![Testing](https://github.com/materialsvirtuallab/matcalc/workflows/Testing/badge.svg)](https://github.com/materialsvirtuallab/matcalc/workflows/Testing/badge.svg)
-[![Linting](https://github.com/materialsvirtuallab/matcalc/workflows/Linting/badge.svg)](https://github.com/materialsvirtuallab/matcalc/workflows/Linting/badge.svg)
+[![Test](https://github.com/materialsvirtuallab/matcalc/workflows/Test/badge.svg)](https://github.com/materialsvirtuallab/matcalc/workflows/Test/badge.svg)
+[![Lint](https://github.com/materialsvirtuallab/matcalc/workflows/Lint/badge.svg)](https://github.com/materialsvirtuallab/matcalc/workflows/Lint/badge.svg)
 [![codecov](https://codecov.io/gh/materialsvirtuallab/matcalc/branch/main/graph/badge.svg?token=OR7Z9WWRRC)](https://codecov.io/gh/materialsvirtuallab/matcalc)
 [![Requires Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue.svg?logo=python&logoColor=white)](https://python.org/downloads)
 [![PyPI](https://img.shields.io/pypi/v/matcalc?logo=pypi&logoColor=white)](https://pypi.org/project/matcalc?logo=pypi&logoColor=white)
@@ -91,12 +91,12 @@ MatCalc provides convenient methods to quickly compute properties, using a minim
 an example of a computation of the elastic constants of Si using the `TensorNet-MatPES-PBE-v2025.1-PES` universal MLIP.
 
 ```python
-from matcalc import PESCalculator, ElasticityCalc, load_up
+import matcalc as mtc
 from pymatgen.ext.matproj import MPRester
 
 mpr = MPRester()
 si = mpr.get_structure_by_material_id("mp-149")
-c = ElasticityCalc(load_up("TensorNet-MatPES-PBE-v2025.1-PES"), relax_structure=True)
+c = mtc.ElasticityCalc(mtc.load_up("TensorNet-MatPES-PBE-v2025.1-PES"), relax_structure=True)
 props = c.calc(si)
 print(f"K_VRH = {props['bulk_modulus_vrh'] * 160.2176621} GPa")
 ```
@@ -107,9 +107,9 @@ While we generally recommend users to specify exactly the model they would like
 (case-insensitive) aliases to our recommended models for PBE and r2SCAN predictions. These can be loaded using:
 
 ```python
-from matcalc import load_up
-pbe_calculator = load_up("pbe")
-r2scan_calculator = load_up("r2scan")
+import matcalc as mtc
+pbe_calculator = mtc.load_up("pbe")
+r2scan_calculator = mtc.load_up("r2scan")
 ```
 
 At the time of writing, these are the TensorNet-MatPES models. However, these recommendations may updated as improved
@@ -142,20 +142,20 @@ computed by all steps. Note that the `relax_structure` should be set to False in
 do not redo the relatively expensive relaxation.
 
 ```python
-from matcalc import load_up, ElasticityCalc, RelaxCalc, EnergeticsCalc, ChainedCalc
+import matcalc as mtc
 import numpy as np
-calculator = load_up("pbe")
-relax_calc = RelaxCalc(
+calculator = mtc.load_up("pbe")
+relax_calc = mtc.RelaxCalc(
     calculator,
     optimizer="FIRE",
     relax_atoms=True,
     relax_cell=True,
 )
-energetics_calc = EnergeticsCalc(
+energetics_calc = mtc.EnergeticsCalc(
     calculator,
     relax_structure=False  # Since we are chaining, we do not need to relax structure in later steps.
 )
-elast_calc = ElasticityCalc(
+elast_calc = mtc.ElasticityCalc(
     calculator,
     fmax=0.1,
     norm_strains=list(np.linspace(-0.004, 0.004, num=4)),
@@ -164,7 +164,7 @@ elast_calc = ElasticityCalc(
     relax_structure=False,  # Since we are chaining, we do not need to relax structure in later steps.
     relax_deformed_structures=True,
 )
-prop_calc = ChainedCalc([relax_calc, energetics_calc, elast_calc])
+prop_calc = mtc.ChainedCalc([relax_calc, energetics_calc, elast_calc])
 results = prop_calc.calc(structure)
 ```
 
@@ -186,10 +186,10 @@ the `MatCalc-Benchmark`.
 For example, the following code can be used to run the ElasticityBenchmark on `TensorNet-MatPES-PBE-v2025.1-PES` UMLIP.
 
 ```python
-from matcalc import load_up
-calculator = load_up("TensorNet-MatPES-PBE-v2025.1-PES")
-from matcalc.benchmark import ElasticityBenchmark
-benchmark = ElasticityBenchmark(fmax=0.05, relax_structure=True)
+import matcalc as mtc
+
+calculator = mtc.load_up("TensorNet-MatPES-PBE-v2025.1-PES")
+benchmark = mtc.benchmark.ElasticityBenchmark(fmax=0.05, relax_structure=True)
 results = benchmark.run(calculator, "TensorNet-MatPES")
 ```
 
@@ -198,14 +198,14 @@ The entire run takes ~ 16mins when parallelized over 10 CPUs on a Mac.
 You can even run entire suites of benchmarks on multiple models, as follows:
 
 ```python
-from matcalc import PESCalculator
-tensornet = PESCalculator.load_universal("TensorNet-MatPES-PBE-v2025.1-PES")
-m3gnet = PESCalculator.load_universal("M3GNet-MatPES-PBE-v2025.1-PES")
-from matcalc.benchmark import BenchmarkSuite, ElasticityBenchmark, PhononBenchmark
-
-elasticity_benchmark = ElasticityBenchmark(fmax=0.5, relax_structure=True)
-phonon_benchmark = PhononBenchmark(write_phonon=False)
-suite = BenchmarkSuite(benchmarks=[elasticity_benchmark, phonon_benchmark])
+import matcalc as mtc
+
+tensornet = mtc.load_up("TensorNet-MatPES-PBE-v2025.1-PES")
+m3gnet = mtc.load_up("M3GNet-MatPES-PBE-v2025.1-PES")
+
+elasticity_benchmark = mtc.benchmark.ElasticityBenchmark(fmax=0.5, relax_structure=True)
+phonon_benchmark = mtc.benchmark.PhononBenchmark(write_phonon=False)
+suite = mtc.benchmark.BenchmarkSuite(benchmarks=[elasticity_benchmark, phonon_benchmark])
 results = suite.run({"M3GNet": m3gnet, "TensorNet": tensornet})
 results.to_csv("benchmark_results.csv")
 ```

{matcalc-0.2.2 → matcalc-0.3.2}/README.md

@@ -3,8 +3,8 @@
 width="200" alt="MatCalc" style="vertical-align: middle;" /><br>
 </h1>
 
-[![Testing](https://github.com/materialsvirtuallab/matcalc/workflows/Testing/badge.svg)](https://github.com/materialsvirtuallab/matcalc/workflows/Testing/badge.svg)
-[![Linting](https://github.com/materialsvirtuallab/matcalc/workflows/Linting/badge.svg)](https://github.com/materialsvirtuallab/matcalc/workflows/Linting/badge.svg)
+[![Test](https://github.com/materialsvirtuallab/matcalc/workflows/Test/badge.svg)](https://github.com/materialsvirtuallab/matcalc/workflows/Test/badge.svg)
+[![Lint](https://github.com/materialsvirtuallab/matcalc/workflows/Lint/badge.svg)](https://github.com/materialsvirtuallab/matcalc/workflows/Lint/badge.svg)
 [![codecov](https://codecov.io/gh/materialsvirtuallab/matcalc/branch/main/graph/badge.svg?token=OR7Z9WWRRC)](https://codecov.io/gh/materialsvirtuallab/matcalc)
 [![Requires Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue.svg?logo=python&logoColor=white)](https://python.org/downloads)
 [![PyPI](https://img.shields.io/pypi/v/matcalc?logo=pypi&logoColor=white)](https://pypi.org/project/matcalc?logo=pypi&logoColor=white)
@@ -42,12 +42,12 @@ MatCalc provides convenient methods to quickly compute properties, using a minim
 an example of a computation of the elastic constants of Si using the `TensorNet-MatPES-PBE-v2025.1-PES` universal MLIP.
 
 ```python
-from matcalc import PESCalculator, ElasticityCalc, load_up
+import matcalc as mtc
 from pymatgen.ext.matproj import MPRester
 
 mpr = MPRester()
 si = mpr.get_structure_by_material_id("mp-149")
-c = ElasticityCalc(load_up("TensorNet-MatPES-PBE-v2025.1-PES"), relax_structure=True)
+c = mtc.ElasticityCalc(mtc.load_up("TensorNet-MatPES-PBE-v2025.1-PES"), relax_structure=True)
 props = c.calc(si)
 print(f"K_VRH = {props['bulk_modulus_vrh'] * 160.2176621} GPa")
 ```
@@ -58,9 +58,9 @@ While we generally recommend users to specify exactly the model they would like
 (case-insensitive) aliases to our recommended models for PBE and r2SCAN predictions. These can be loaded using:
 
 ```python
-from matcalc import load_up
-pbe_calculator = load_up("pbe")
-r2scan_calculator = load_up("r2scan")
+import matcalc as mtc
+pbe_calculator = mtc.load_up("pbe")
+r2scan_calculator = mtc.load_up("r2scan")
 ```
 
 At the time of writing, these are the TensorNet-MatPES models. However, these recommendations may updated as improved
@@ -93,20 +93,20 @@ computed by all steps. Note that the `relax_structure` should be set to False in
 do not redo the relatively expensive relaxation.
 
 ```python
-from matcalc import load_up, ElasticityCalc, RelaxCalc, EnergeticsCalc, ChainedCalc
+import matcalc as mtc
 import numpy as np
-calculator = load_up("pbe")
-relax_calc = RelaxCalc(
+calculator = mtc.load_up("pbe")
+relax_calc = mtc.RelaxCalc(
     calculator,
     optimizer="FIRE",
     relax_atoms=True,
     relax_cell=True,
 )
-energetics_calc = EnergeticsCalc(
+energetics_calc = mtc.EnergeticsCalc(
     calculator,
     relax_structure=False  # Since we are chaining, we do not need to relax structure in later steps.
 )
-elast_calc = ElasticityCalc(
+elast_calc = mtc.ElasticityCalc(
     calculator,
     fmax=0.1,
     norm_strains=list(np.linspace(-0.004, 0.004, num=4)),
@@ -115,7 +115,7 @@ elast_calc = ElasticityCalc(
     relax_structure=False,  # Since we are chaining, we do not need to relax structure in later steps.
     relax_deformed_structures=True,
 )
-prop_calc = ChainedCalc([relax_calc, energetics_calc, elast_calc])
+prop_calc = mtc.ChainedCalc([relax_calc, energetics_calc, elast_calc])
 results = prop_calc.calc(structure)
 ```
 
@@ -137,10 +137,10 @@ the `MatCalc-Benchmark`.
 For example, the following code can be used to run the ElasticityBenchmark on `TensorNet-MatPES-PBE-v2025.1-PES` UMLIP.
 
 ```python
-from matcalc import load_up
-calculator = load_up("TensorNet-MatPES-PBE-v2025.1-PES")
-from matcalc.benchmark import ElasticityBenchmark
-benchmark = ElasticityBenchmark(fmax=0.05, relax_structure=True)
+import matcalc as mtc
+
+calculator = mtc.load_up("TensorNet-MatPES-PBE-v2025.1-PES")
+benchmark = mtc.benchmark.ElasticityBenchmark(fmax=0.05, relax_structure=True)
 results = benchmark.run(calculator, "TensorNet-MatPES")
 ```
 
@@ -149,14 +149,14 @@ The entire run takes ~ 16mins when parallelized over 10 CPUs on a Mac.
 You can even run entire suites of benchmarks on multiple models, as follows:
 
 ```python
-from matcalc import PESCalculator
-tensornet = PESCalculator.load_universal("TensorNet-MatPES-PBE-v2025.1-PES")
-m3gnet = PESCalculator.load_universal("M3GNet-MatPES-PBE-v2025.1-PES")
-from matcalc.benchmark import BenchmarkSuite, ElasticityBenchmark, PhononBenchmark
-
-elasticity_benchmark = ElasticityBenchmark(fmax=0.5, relax_structure=True)
-phonon_benchmark = PhononBenchmark(write_phonon=False)
-suite = BenchmarkSuite(benchmarks=[elasticity_benchmark, phonon_benchmark])
+import matcalc as mtc
+
+tensornet = mtc.load_up("TensorNet-MatPES-PBE-v2025.1-PES")
+m3gnet = mtc.load_up("M3GNet-MatPES-PBE-v2025.1-PES")
+
+elasticity_benchmark = mtc.benchmark.ElasticityBenchmark(fmax=0.5, relax_structure=True)
+phonon_benchmark = mtc.benchmark.PhononBenchmark(write_phonon=False)
+suite = mtc.benchmark.BenchmarkSuite(benchmarks=[elasticity_benchmark, phonon_benchmark])
 results = suite.run({"M3GNet": m3gnet, "TensorNet": tensornet})
 results.to_csv("benchmark_results.csv")
 ```

{matcalc-0.2.2 → matcalc-0.3.2}/pyproject.toml

@@ -37,45 +37,44 @@ classifiers = [
 ]
 dependencies = [
     "ase>=3.23.0",
-    "joblib",
-    "phonopy",
-    "pymatgen",
     "numpy<2.0.0",
-    "fsspec",
-    "scikit-learn>=1.6.1"
+    "scikit-learn>=1.6.1",
+    "pymatgen>=2025.3.10",
+    "fsspec>=2025.3.0",
+    "joblib>=1.4.2",
+    "phonopy>=2.38.0",
+    "phono3py>=3.15.0",
 ]
-version = "0.2.2"
+version = "0.3.2"
 
 [project.optional-dependencies]
 phonon = ["seekpath"]
 benchmark = ["matminer>=0.9.3"]
-maml = [
-    "maml>=2025.2.25",
-]
-sevennet = [
-    "sevenn>=0.10.4",
+ace = [
+    "pyace>=0.1.1",
 ]
 mace = [
     "mace-torch>=0.3.12",
 ]
-nequip = [
-    "nequip>=0.6.2",
+deepmd = [
+    "deepmd-kit>=3.0.2",
 ]
 grace = [
     "tensorpotential>=0.5.1",
 ]
-matgl = [
-    "matgl>=1.2.3",
+maml = [
+    "maml>=2025.2.25",
 ]
 orb = [
     "orb-models>=0.4.2",
+    "pynanoflann>=0.10.0",
 ]
-ace = [
-    "pyace>=0.1.1",
+sevennet = [
+    "sevenn>=0.10.4",
 ]
 
 [project.scripts]
-matcalc = "matcalc.cli:main"
+matcalc = "matcalc._cli:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]
@@ -117,12 +116,22 @@ maintain = [
 ]
 test-models = [
     "mace-torch>=0.3.12",
+    "nequip>=0.6.2",
     "orb-models>=0.4.2",
     "pynanoflann>=0.10.0",
     "sevenn>=0.10.4",
     "tensorpotential>=0.5.1",
 ]
 
+[tool.uv]
+conflicts = [
+    [
+      { extra = "mace" },
+      { extra = "fairchem" },
+      { extra = "mattersim" },
+    ],
+]
+
 [tool.ruff]
 target-version = "py310"
 line-length = 120
@@ -182,6 +191,9 @@ exclude_lines = [
     "@deprecated",
     "def __repr__",
     "except PackageNotFoundError:",
+    "except Exception:",
+    "except:",
+    "except FileNotFoundError:",
     "if 0:",
     "if TYPE_CHECKING:",
     "if typing.TYPE_CHECKING:",

{matcalc-0.2.2 → matcalc-0.3.2}/src/matcalc/__init__.py

@@ -9,15 +9,16 @@ try:
 except PackageNotFoundError:
     pass  # package not installed
 
-from .base import ChainedCalc, PropCalc
+from ._base import ChainedCalc, PropCalc
+from ._elasticity import ElasticityCalc
+from ._eos import EOSCalc
+from ._neb import NEBCalc
+from ._phonon import PhononCalc
+from ._phonon3 import Phonon3Calc
+from ._qha import QHACalc
+from ._relaxation import RelaxCalc
+from ._stability import EnergeticsCalc
 from .config import clear_cache
-from .elasticity import ElasticityCalc
-from .eos import EOSCalc
-from .neb import NEBCalc
-from .phonon import PhononCalc
-from .qha import QHACalc
-from .relaxation import RelaxCalc
-from .stability import EnergeticsCalc
 from .utils import UNIVERSAL_CALCULATORS, PESCalculator
 
 # Provide an alias for loading calculators quickly.

matcalc-0.2.2/src/matcalc/base.py → matcalc-0.3.2/src/matcalc/_base.py

@@ -14,21 +14,39 @@ if TYPE_CHECKING:
 
 
 class PropCalc(abc.ABC):
-    """API for a property calculator."""
+    """
+    Abstract base class for property calculations.
+
+    This class defines the interface for performing property calculations on
+    structures (using pymatgen's Structure objects or a dictionary containing a
+    pymatgen structure). Subclasses are expected to implement the `calc` method
+    to define specific property calculation logic. Additionally, this class provides
+    an implementation of the `calc_many` method, which enables concurrent calculations
+    on multiple structures using joblib.
+    """
 
     @abc.abstractmethod
     def calc(self, structure: Structure | dict[str, Any]) -> dict[str, Any]:
-        """All PropCalc subclasses should implement a calc method that takes in a pymatgen structure
-        and returns a dict. The method can return more than one property. Generally, subclasses should have a super()
-        call to the abstract base method to obtain an initial result dict.
+        """
+        Abstract method to calculate and return a standardized format of structural data.
 
-        Args:
-            structure: Pymatgen structure or a dict containing a pymatgen Structure under a "final_structure" or
-                "structure" key. Allowing dicts provide the means to chain calculators, e.g., do a relaxation followed
-                by an elasticity calculation.
+        This method processes input structural data, which could either be a dictionary
+        or a pymatgen Structure object, and returns a dictionary representation. If a
+        dictionary is provided, it must include either the key ``final_structure`` or
+        ``structure``. For a pymatgen Structure input, it will be converted to a dictionary
+        with the key ``final_structure``. To support chaining, a super() call should be made
+        by subclasses to ensure that the input dictionary is standardized.
 
-        Returns:
-            dict[str, Any]: In the form {"prop_name": value}.
+        :param structure: A pymatgen Structure object or a dictionary containing structural
+            data with keys such as ``final_structure`` or ``structure``.
+        :type structure: Structure | dict[str, Any]
+
+        :return: A dictionary with the key ``final_structure`` mapping to the corresponding
+            structural data.
+        :rtype: dict[str, Any]
+
+        :raises ValueError: If the input dictionary does not include the required keys
+            ``final_structure`` or ``structure``.
         """
         if isinstance(structure, dict):
             if "final_structure" in structure:
@@ -49,22 +67,30 @@ class PropCalc(abc.ABC):
         allow_errors: bool = False,  # noqa: FBT001,FBT002
         **kwargs: Any,
     ) -> Generator[dict | None]:
-        """Performs calc on many structures. The return type is a generator given that the calc method can
-        potentially be expensive. It is trivial to convert the generator to a list/tuple.
-
-        Args:
-            structures: List or generator of Structures.
-            n_jobs: The maximum number of concurrently running jobs. If -1 all CPUs are used. For n_jobs below -1,
-                (n_cpus + 1 + n_jobs) are used. None is a marker for `unset` that will be interpreted as n_jobs=1
-                unless the call is performed under a parallel_config() context manager that sets another value for
-                n_jobs.
-            allow_errors: Whether to skip failed calculations. For these calculations, None will be returned. For
-                large scale calculations, you may want this to be True to avoid the entire calculation failing.
-                Defaults to False.
-            **kwargs: Passthrough to joblib.Parallel.
-
-        Returns:
-            Generator of dicts.
+        """
+        Calculate properties for multiple structures concurrently.
+
+        This method leverages parallel processing to compute properties for a
+        given sequence of structures. It uses the `joblib.Parallel` library to
+        support multi-job execution and manage error handling behavior based
+        on user configuration.
+
+        :param structures: A sequence of `Structure` objects or dictionaries
+            representing the input structures to be processed. Each entry in
+            the sequence is processed independently.
+        :param n_jobs: The number of jobs to run in parallel. If set to None,
+            joblib will determine the optimal number of jobs based on the
+            system's CPU configuration.
+        :param allow_errors: A boolean flag indicating whether to tolerate
+            exceptions during processing. When set to True, any failed
+            calculation will result in a `None` value for that structure
+            instead of raising an exception.
+        :param kwargs: Additional keyword arguments passed directly to
+            `joblib.Parallel`, which allows customization of parallel
+            processing behavior.
+        :return: A generator yielding dictionaries with computed properties
+            for each structure or `None` if an error occurred (depending on
+            the `allow_errors` flag).
         """
         parallel = Parallel(n_jobs=n_jobs, return_as="generator", **kwargs)
         if allow_errors: