<h1 align="center">
<img src="https://raw.githubusercontent.com/materialsvirtuallab/matcalc/refs/heads/main/docs/assets/matcalc.png"
width="200" alt="MatCalc" style="vertical-align: middle;" /><br>
</h1>
[](https://github.com/materialsvirtuallab/matcalc/workflows/Test/badge.svg)
[](https://github.com/materialsvirtuallab/matcalc/workflows/Lint/badge.svg)
[](https://codecov.io/gh/materialsvirtuallab/matcalc)
[](https://python.org/downloads)
[](https://pypi.org/project/matcalc?logo=pypi&logoColor=white)
[](https://github.com/materialsvirtuallab/matcalc/blob/main/LICENSE)
## Introduction
MatCalc is a Python library for calculating and benchmarking material properties from the potential energy surface
(PES). The PES can come from DFT or, more commonly, from machine learning interatomic potentials (MLIPs).
Calculating material properties often requires involved setups of various simulation codes. The
goal of MatCalc is to provide a simplified, consistent interface to access these properties with any
parameterization of the PES.
MatCalc is part of the MatML ecosystem, which includes the [MatGL] (Materials Graph Library) and [MAML] (MAterials
Machine Learning) packages, the [MatPES] (Materials Potential Energy Surface) dataset, and the [MatCalc] (Materials
Calculator).
## Documentation
The API documentation and tutorials are available at https://matcalc.ai.
## Outline
The main base class in MatCalc is `PropCalc` (property calculator). [All `PropCalc` subclasses](https://github.com/search?q=repo%3Amaterialsvirtuallab%2Fmatcalc%20%22(PropCalc)%22) should implement a
`calc(pymatgen.Structure | ase.Atoms | dict) -> dict` method that returns a dictionary of properties.
In general, `PropCalc` should be initialized with an ML model or [ASE] calculator, which is then used by either ASE,
LAMMPS or some other simulation code to perform calculations of properties. The `matcalc.PESCalculator` class
provides easy access to many foundation potentials (FPs) as well as an interface to MAML for custom MLIPs
such as MTP, NNP, GAP, etc.
# Basic Usage
MatCalc provides convenient methods to quickly compute properties, using a minimal amount of code. The following is
an example of a computation of the elastic constants of Si using the `TensorNet-MatPES-PBE-v2025.1-PES` universal MLIP.
```python
import matcalc as mtc
from pymatgen.ext.matproj import MPRester
mpr = MPRester()
si = mpr.get_structure_by_material_id("mp-149")
c = mtc.ElasticityCalc("TensorNet-MatPES-PBE-v2025.1-PES", relax_structure=True)
props = c.calc(si)
print(f"K_VRH = {props['bulk_modulus_vrh'] * 160.2176621} GPa")
```
The calculated `K_VRH` is about 102 GPa, in reasonably good agreement with the experimental and DFT values.
You can easily access a list of universal calculators (not comprehensive) using the UNIVERSAL_CALCULATORS enum.
```python
print(mtc.UNIVERSAL_CALCULATORS)
```
While we generally recommend users to specify exactly the model they would like to use, MatCalc provides useful
(case-insensitive) aliases to our recommended models for PBE and r2SCAN predictions. These can be loaded using:
```python
import matcalc as mtc
pbe_calculator = mtc.load_fp("pbe")
r2scan_calculator = mtc.load_fp("r2scan")
```
At the time of writing, these are the `TensorNet-MatPES-v2025.1` models for these functionals. However, these
recommendations may updated as improved models become available.
MatCalc also supports trivial parallelization using joblib via the `calc_many` method.
```python
structures = [si] * 20
def serial_calc():
return [c.calc(s) for s in structures]
def parallel_calc():
# n_jobs = -1 uses all processors available.
return list(c.calc_many(structures, n_jobs=-1))
%timeit -n 5 -r 1 serial_calc()
# Output is 8.7 s ± 0 ns per loop (mean ± std. dev. of 1 run, 5 loops each)
%timeit -n 5 -r 1 parallel_calc()
# Output is 2.08 s ± 0 ns per loop (mean ± std. dev. of 1 run, 5 loops each)
# This was run on 10 CPUs on a Mac.
```
MatCalc also supports chaining of `PropCalc`. Typically, you will start with a relaxation calc, followed by a series
of other calculators to get the properties you need. For example, the following snippet performs a relaxation,
followed by an energetics calculation and then an elasticity calculation. The final `results` contain all properties
computed by all steps. Note that the `relax_structure` should be set to False in later `PropCalc` to ensure that you
do not redo the relatively expensive relaxation.
```python
import matcalc as mtc
import numpy as np
calculator = mtc.load_fp("pbe")
relax_calc = mtc.RelaxCalc(
calculator,
optimizer="FIRE",
relax_atoms=True,
relax_cell=True,
)
energetics_calc = mtc.EnergeticsCalc(
calculator,
relax_structure=False # Since we are chaining, we do not need to relax structure in later steps.
)
elast_calc = mtc.ElasticityCalc(
calculator,
fmax=0.1,
norm_strains=list(np.linspace(-0.004, 0.004, num=4)),
shear_strains=list(np.linspace(-0.004, 0.004, num=4)),
use_equilibrium=True,
relax_structure=False, # Since we are chaining, we do not need to relax structure in later steps.
relax_deformed_structures=True,
)
prop_calc = mtc.ChainedCalc([relax_calc, energetics_calc, elast_calc])
results = prop_calc.calc(structure)
```
Chaining can also be used with the `calc_many` method, with parallelization.
### CLI tool
A CLI tool provides a means to use FPs to obtain properties for any structure. Example usage:
```shell
matcalc calc -p ElasticityCalc -s Li2O.cif
```
## Benchmarking
MatCalc makes it easy to perform a large number of calculations rapidly. With the release of MatPES, we have released
the `MatCalc-Benchmark`.
For example, the following code can be used to run the ElasticityBenchmark on `TensorNet-MatPES-PBE-v2025.1-PES` FP.
```python
import matcalc as mtc
calculator = mtc.load_fp("TensorNet-MatPES-PBE-v2025.1-PES")
benchmark = mtc.benchmark.ElasticityBenchmark(fmax=0.05, relax_structure=True)
results = benchmark.run(calculator, "TensorNet-MatPES")
```
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
import matcalc as mtc
tensornet = mtc.load_fp("TensorNet-MatPES-PBE-v2025.1-PES")
m3gnet = mtc.load_fp("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")
```
These will usually take a long time to run. Running on HPC resources is recommended. Please set `n_samples` when
initializing the benchmark to limit the number of calculations to do some testing before running the full benchmark.
## Docker Images
Docker images with MatCalc and LAMMPS support are available at the [Materials Virtual Lab Docker Repository].
## Citing
A manuscript on `matcalc` is currently in the works. In the meantime, please see [`citation.cff`](citation.cff) or the GitHub
sidebar for a BibTeX and APA citation.
[MAML]: https://materialsvirtuallab.github.io/maml/
[MatGL]: https://matgl.ai
[MatPES]: https://matpes.ai
[MatCalc]: https://matcalc.ai
[ASE]: https://wiki.fysik.dtu.dk/ase/
[Materials Virtual Lab Docker Repository]: https://hub.docker.com/orgs/materialsvirtuallab/repositories
Raw data
{
"_id": null,
"home_page": null,
"name": "matcalc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "AI, deep learning, force field, graph, interatomic potential, machine learning, materials, property prediction, science",
"author": null,
"author_email": "Runze Liu <rul048@ucsd.edu>, Eliott Liu <elliottliu17@gmail.com>, Ji Qi <j1qi@ucsd.edu>, Shyue Ping Ong <ongsp@ucsd.edu>, Tsz Wai Ko <t1ko@ucsd.edu>",
"download_url": "https://files.pythonhosted.org/packages/76/4d/5c15fba418597d31cb9022c4d50f1cc08b5b123f64705d6f66871428252a/matcalc-0.4.2.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">\n <img src=\"https://raw.githubusercontent.com/materialsvirtuallab/matcalc/refs/heads/main/docs/assets/matcalc.png\"\nwidth=\"200\" alt=\"MatCalc\" style=\"vertical-align: middle;\" /><br>\n</h1>\n\n[](https://github.com/materialsvirtuallab/matcalc/workflows/Test/badge.svg)\n[](https://github.com/materialsvirtuallab/matcalc/workflows/Lint/badge.svg)\n[](https://codecov.io/gh/materialsvirtuallab/matcalc)\n[](https://python.org/downloads)\n[](https://pypi.org/project/matcalc?logo=pypi&logoColor=white)\n[](https://github.com/materialsvirtuallab/matcalc/blob/main/LICENSE)\n\n## Introduction\n\nMatCalc is a Python library for calculating and benchmarking material properties from the potential energy surface\n(PES). The PES can come from DFT or, more commonly, from machine learning interatomic potentials (MLIPs).\n\nCalculating material properties often requires involved setups of various simulation codes. The\ngoal of MatCalc is to provide a simplified, consistent interface to access these properties with any\nparameterization of the PES.\n\nMatCalc is part of the MatML ecosystem, which includes the [MatGL] (Materials Graph Library) and [MAML] (MAterials\nMachine Learning) packages, the [MatPES] (Materials Potential Energy Surface) dataset, and the [MatCalc] (Materials\nCalculator).\n\n## Documentation\n\nThe API documentation and tutorials are available at https://matcalc.ai.\n\n## Outline\n\nThe main base class in MatCalc is `PropCalc` (property calculator). [All `PropCalc` subclasses](https://github.com/search?q=repo%3Amaterialsvirtuallab%2Fmatcalc%20%22(PropCalc)%22) should implement a\n`calc(pymatgen.Structure | ase.Atoms | dict) -> dict` method that returns a dictionary of properties.\n\nIn general, `PropCalc` should be initialized with an ML model or [ASE] calculator, which is then used by either ASE,\nLAMMPS or some other simulation code to perform calculations of properties. The `matcalc.PESCalculator` class\nprovides easy access to many foundation potentials (FPs) as well as an interface to MAML for custom MLIPs\nsuch as MTP, NNP, GAP, etc.\n\n# Basic Usage\n\nMatCalc provides convenient methods to quickly compute properties, using a minimal amount of code. The following is\nan example of a computation of the elastic constants of Si using the `TensorNet-MatPES-PBE-v2025.1-PES` universal MLIP.\n\n```python\nimport matcalc as mtc\nfrom pymatgen.ext.matproj import MPRester\n\nmpr = MPRester()\nsi = mpr.get_structure_by_material_id(\"mp-149\")\nc = mtc.ElasticityCalc(\"TensorNet-MatPES-PBE-v2025.1-PES\", relax_structure=True)\nprops = c.calc(si)\nprint(f\"K_VRH = {props['bulk_modulus_vrh'] * 160.2176621} GPa\")\n```\n\nThe calculated `K_VRH` is about 102 GPa, in reasonably good agreement with the experimental and DFT values.\n\nYou can easily access a list of universal calculators (not comprehensive) using the UNIVERSAL_CALCULATORS enum.\n\n```python\nprint(mtc.UNIVERSAL_CALCULATORS)\n```\n\nWhile we generally recommend users to specify exactly the model they would like to use, MatCalc provides useful\n(case-insensitive) aliases to our recommended models for PBE and r2SCAN predictions. These can be loaded using:\n\n```python\nimport matcalc as mtc\npbe_calculator = mtc.load_fp(\"pbe\")\nr2scan_calculator = mtc.load_fp(\"r2scan\")\n```\n\nAt the time of writing, these are the `TensorNet-MatPES-v2025.1` models for these functionals. However, these\nrecommendations may updated as improved models become available.\n\nMatCalc also supports trivial parallelization using joblib via the `calc_many` method.\n\n```python\nstructures = [si] * 20\n\ndef serial_calc():\n return [c.calc(s) for s in structures]\n\ndef parallel_calc():\n # n_jobs = -1 uses all processors available.\n return list(c.calc_many(structures, n_jobs=-1))\n\n%timeit -n 5 -r 1 serial_calc()\n# Output is 8.7 s \u00b1 0 ns per loop (mean \u00b1 std. dev. of 1 run, 5 loops each)\n\n%timeit -n 5 -r 1 parallel_calc()\n# Output is 2.08 s \u00b1 0 ns per loop (mean \u00b1 std. dev. of 1 run, 5 loops each)\n# This was run on 10 CPUs on a Mac.\n```\n\nMatCalc also supports chaining of `PropCalc`. Typically, you will start with a relaxation calc, followed by a series\nof other calculators to get the properties you need. For example, the following snippet performs a relaxation,\nfollowed by an energetics calculation and then an elasticity calculation. The final `results` contain all properties\ncomputed by all steps. Note that the `relax_structure` should be set to False in later `PropCalc` to ensure that you\ndo not redo the relatively expensive relaxation.\n\n```python\nimport matcalc as mtc\nimport numpy as np\ncalculator = mtc.load_fp(\"pbe\")\nrelax_calc = mtc.RelaxCalc(\n calculator,\n optimizer=\"FIRE\",\n relax_atoms=True,\n relax_cell=True,\n)\nenergetics_calc = mtc.EnergeticsCalc(\n calculator,\n relax_structure=False # Since we are chaining, we do not need to relax structure in later steps.\n)\nelast_calc = mtc.ElasticityCalc(\n calculator,\n fmax=0.1,\n norm_strains=list(np.linspace(-0.004, 0.004, num=4)),\n shear_strains=list(np.linspace(-0.004, 0.004, num=4)),\n use_equilibrium=True,\n relax_structure=False, # Since we are chaining, we do not need to relax structure in later steps.\n relax_deformed_structures=True,\n)\nprop_calc = mtc.ChainedCalc([relax_calc, energetics_calc, elast_calc])\nresults = prop_calc.calc(structure)\n```\n\nChaining can also be used with the `calc_many` method, with parallelization.\n\n### CLI tool\n\nA CLI tool provides a means to use FPs to obtain properties for any structure. Example usage:\n\n```shell\nmatcalc calc -p ElasticityCalc -s Li2O.cif\n```\n\n## Benchmarking\n\nMatCalc makes it easy to perform a large number of calculations rapidly. With the release of MatPES, we have released\nthe `MatCalc-Benchmark`.\n\nFor example, the following code can be used to run the ElasticityBenchmark on `TensorNet-MatPES-PBE-v2025.1-PES` FP.\n\n```python\nimport matcalc as mtc\n\ncalculator = mtc.load_fp(\"TensorNet-MatPES-PBE-v2025.1-PES\")\nbenchmark = mtc.benchmark.ElasticityBenchmark(fmax=0.05, relax_structure=True)\nresults = benchmark.run(calculator, \"TensorNet-MatPES\")\n```\n\nThe entire run takes ~ 16mins when parallelized over 10 CPUs on a Mac.\n\nYou can even run entire suites of benchmarks on multiple models, as follows:\n\n```python\nimport matcalc as mtc\n\ntensornet = mtc.load_fp(\"TensorNet-MatPES-PBE-v2025.1-PES\")\nm3gnet = mtc.load_fp(\"M3GNet-MatPES-PBE-v2025.1-PES\")\n\nelasticity_benchmark = mtc.benchmark.ElasticityBenchmark(fmax=0.5, relax_structure=True)\nphonon_benchmark = mtc.benchmark.PhononBenchmark(write_phonon=False)\nsuite = mtc.benchmark.BenchmarkSuite(benchmarks=[elasticity_benchmark, phonon_benchmark])\nresults = suite.run({\"M3GNet\": m3gnet, \"TensorNet\": tensornet})\nresults.to_csv(\"benchmark_results.csv\")\n```\n\nThese will usually take a long time to run. Running on HPC resources is recommended. Please set `n_samples` when\ninitializing the benchmark to limit the number of calculations to do some testing before running the full benchmark.\n\n## Docker Images\n\nDocker images with MatCalc and LAMMPS support are available at the [Materials Virtual Lab Docker Repository].\n\n## Citing\n\nA manuscript on `matcalc` is currently in the works. In the meantime, please see [`citation.cff`](citation.cff) or the GitHub\nsidebar for a BibTeX and APA citation.\n\n[MAML]: https://materialsvirtuallab.github.io/maml/\n[MatGL]: https://matgl.ai\n[MatPES]: https://matpes.ai\n[MatCalc]: https://matcalc.ai\n[ASE]: https://wiki.fysik.dtu.dk/ase/\n[Materials Virtual Lab Docker Repository]: https://hub.docker.com/orgs/materialsvirtuallab/repositories\n",
"bugtrack_url": null,
"license": null,
"summary": "Calculators for materials properties from the potential energy surface.",
"version": "0.4.2",
"project_urls": null,
"split_keywords": [
"ai",
" deep learning",
" force field",
" graph",
" interatomic potential",
" machine learning",
" materials",
" property prediction",
" science"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "764d5c15fba418597d31cb9022c4d50f1cc08b5b123f64705d6f66871428252a",
"md5": "6137ae6313822636f27708fbd9120b4e",
"sha256": "0e3575c997751e28b25a5d3c5378093b396502a51a775e3cb8c0481fe2334010"
},
"downloads": -1,
"filename": "matcalc-0.4.2.tar.gz",
"has_sig": false,
"md5_digest": "6137ae6313822636f27708fbd9120b4e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 552332,
"upload_time": "2025-07-31T05:48:13",
"upload_time_iso_8601": "2025-07-31T05:48:13.678714Z",
"url": "https://files.pythonhosted.org/packages/76/4d/5c15fba418597d31cb9022c4d50f1cc08b5b123f64705d6f66871428252a/matcalc-0.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 05:48:13",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "matcalc"
}
JSON