{"id":33861082,"url":"https://github.com/materialyzeai/matcalc","last_synced_at":"2026-05-28T22:01:02.384Z","repository":{"id":183972444,"uuid":"670410006","full_name":"materialyzeai/matcalc","owner":"materialyzeai","description":"A python library for calculating materials properties from the PES","archived":false,"fork":false,"pushed_at":"2026-05-12T03:59:44.000Z","size":240947,"stargazers_count":141,"open_issues_count":1,"forks_count":35,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-05-12T05:39:20.869Z","etag":null,"topics":["learning","machine","materials","pes","properties"],"latest_commit_sha":null,"homepage":"http://matcalc.ai/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/materialyzeai.png","metadata":{"files":{"readme":"README.md","changelog":"changes.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"citation.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-07-25T02:04:04.000Z","updated_at":"2026-05-12T03:59:47.000Z","dependencies_parsed_at":"2023-07-26T15:39:53.213Z","dependency_job_id":"cdc0aec0-59c3-4e86-918c-507c3d06013b","html_url":"https://github.com/materialyzeai/matcalc","commit_stats":null,"previous_names":["materialsvirtuallab/matcalc","materialyzeai/matcalc"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/materialyzeai/matcalc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/materialyzeai%2Fmatcalc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/materialyzeai%2Fmatcalc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/materialyzeai%2Fmatcalc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/materialyzeai%2Fmatcalc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/materialyzeai","download_url":"https://codeload.github.com/materialyzeai/matcalc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/materialyzeai%2Fmatcalc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33627939,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["learning","machine","materials","pes","properties"],"created_at":"2025-12-09T07:00:47.136Z","updated_at":"2026-05-28T22:01:02.373Z","avatar_url":"https://github.com/materialyzeai.png","language":"Python","funding_links":[],"categories":["Interatomic Potentials (ML-IAP)"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/materialyzeai/matcalc/refs/heads/main/docs/assets/matcalc.png\"\nwidth=\"200\" alt=\"MatCalc\" style=\"vertical-align: middle;\" /\u003e\u003cbr\u003e\n\u003c/h1\u003e\n\n[![Test](https://github.com/materialyzeai/matcalc/workflows/Test/badge.svg)](https://github.com/materialyzeai/matcalc/workflows/Test/badge.svg)\n[![Lint](https://github.com/materialyzeai/matcalc/workflows/Lint/badge.svg)](https://github.com/materialyzeai/matcalc/workflows/Lint/badge.svg)\n[![codecov](https://codecov.io/gh/materialyzeai/matcalc/branch/main/graph/badge.svg?token=OR7Z9WWRRC)](https://codecov.io/gh/materialyzeai/matcalc)\n[![Requires Python 3.11+](https://img.shields.io/badge/Python-3.11+-blue.svg?logo=python\u0026logoColor=white)](https://python.org/downloads)\n[![PyPI](https://img.shields.io/pypi/v/matcalc?logo=pypi\u0026logoColor=white)](https://pypi.org/project/matcalc?logo=pypi\u0026logoColor=white)\n[![GitHub license](https://img.shields.io/github/license/materialyzeai/matcalc)](https://github.com/materialyzeai/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 [MatGL] (Materials Graph Library) and [MAML] (MAterials\nMachine Learning), the [MatPES] (Materials Potential Energy Surface) dataset, and the [MatCalc] documentation site.\n\n## Documentation\n\nThe API documentation and tutorials are available at https://matcalc.ai.\n\n## Installation\n\n```bash\npip install matcalc\n```\n\nFor MatGL foundation potential support (TensorNet, M3GNet, CHGNet):\n\n```bash\npip install matcalc[matgl]\n```\n\nFor MAML classical potential support (MTP, GAP, NNP, SNAP):\n\n```bash\npip install matcalc[maml]\n```\n\nFor benchmarking support:\n\n```bash\npip install matcalc[benchmark]\n```\n\nFor phonon band paths via Seekpath:\n\n```bash\npip install matcalc[phonon]\n```\n\n## Architecture\n\nThe main base class in MatCalc is `PropCalc` (property calculator). All `PropCalc` subclasses implement a\n`calc(pymatgen.Structure | ase.Atoms | dict) -\u003e dict` method that returns a dictionary of properties.\n\nIn general, `PropCalc` is initialized with an ML model or [ASE] calculator. The `matcalc.PESCalculator` class\nprovides convenient access to many foundation potentials (FPs) as well as an interface to MAML for classical\nMLIPs such as MTP, NNP, GAP, SNAP, ACE, etc.\n\n### Available Calculators\n\n| Calculator | Description | Key Output Keys |\n|---|---|---|\n| `RelaxCalc` | Structural relaxation | `energy`, `forces`, `stress`, `a`, `b`, `c`, `alpha`, `beta`, `gamma`, `volume`, `final_structure` |\n| `ElasticityCalc` | Elastic constants via strain-stress fitting | `elastic_tensor`, `bulk_modulus_vrh`, `shear_modulus_vrh`, `youngs_modulus`, `residuals_sum` |\n| `EOSCalc` | Birch-Murnaghan equation of state | `eos`, `bulk_modulus_bm`, `r2_score_bm` |\n| `PhononCalc` | Phonon band structure and thermal properties | `phonon`, `thermal_properties`, `frequencies`, `disp_supercells` |\n| `Phonon3Calc` | Third-order force constants and thermal conductivity | `phonon3` (Phono3py object), `temperatures`, `thermal_conductivity` |\n| `QHACalc` | Quasi-harmonic approximation | `gibbs_temperature`, `thermal_expansion`, `bulk_modulus_temperature` |\n| `MDCalc` | Molecular dynamics simulation | `md_structures`, `md_energies` |\n| `NEBCalc` | Nudged elastic band / minimum energy path | `mep`, `barrier_energy` |\n| `EnergeticsCalc` | Formation and cohesive energies | `formation_energy_per_atom`, `cohesive_energy_per_atom` |\n| `SurfaceCalc` | Surface energy calculation | `surface_energy`, `slab_energy`, `final_slab` |\n| `AdsorptionCalc` | Adsorption energy on surfaces | `adsorption_energy` |\n| `InterfaceCalc` | Coherent interface energy between two bulk structures | `interface_energy` |\n| `LAMMPSMDCalc` | LAMMPS-based molecular dynamics | `md_structures`, `md_energies` |\n| `ChainedCalc` | Chain multiple PropCalcs in sequence | Combined outputs of all constituent calculators |\n\n### Supported Foundation Potentials\n\n`PESCalculator.load_universal()` — aliased as `matcalc.load_fp()` and `matcalc.load_up()` — supports these models out of the box:\n\n| Model | String Name / Alias | Package |\n|---|---|---|\n| TensorNet-MatPES-PBE | `\"TensorNet-PES-MatPES-PBE-2025.2\"` or `\"pbe\"` | matgl |\n| TensorNet-MatPES-r²SCAN | `\"TensorNet-PES-MatPES-r2SCAN-2025.2\"` or `\"r2scan\"` | matgl |\n| M3GNet-MatPES-PBE | `\"M3GNet-PES-MatPES-PBE-v2025.1\"` or `\"m3gnet\"` | matgl |\n| CHGNet | `\"CHGNet-PES-MatPES-PBE-2025.2.10\"` or `\"chgnet\"` | matgl |\n| MACE-MP | `\"MACE\"` | mace-torch |\n| SevenNet | `\"SevenNet\"` | sevenn |\n| GRACE / TensorPotential | `\"GRACE\"` or `\"TensorPotential\"` | tensorpotential |\n| ORB | `\"ORB\"` | orb-models |\n| MatterSim | `\"MatterSim\"` | mattersim |\n| FAIRChem | `\"FAIRChem\"` | fairchem-core |\n| PET-MAD | `\"PETMAD\"` | pet-mad |\n| DeePMD | `\"DeePMD\"` | deepmd-kit |\n\nAliases are case-insensitive. All pretrained MatGL PES models are auto-discovered if MatGL is installed.\n\n## Basic Usage\n\nMatCalc provides convenient methods to quickly compute properties with minimal code. The following example\ncomputes the elastic constants of Si using the `TensorNet-PES-MatPES-PBE-2025.2` 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-PES-MatPES-PBE-2025.2\", 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 list all supported universal calculators using the `UNIVERSAL_CALCULATORS` enum:\n\n```python\nprint(mtc.UNIVERSAL_CALCULATORS)\n```\n\nMatCalc provides case-insensitive aliases for the recommended PBE and r²SCAN models:\n\n```python\nimport matcalc as mtc\npbe_calculator = mtc.load_fp(\"pbe\")\nr2scan_calculator = mtc.load_fp(\"r2scan\")\n```\n\nThese currently resolve to the `TensorNet-PES-MatPES-*-2025.2` models, but may be updated as better models\nbecome available.\n\n`matcalc.load_up` is the same as `matcalc.load_fp` (historical alias).\n\n### Parallelization\n\nMatCalc supports trivial parallelization via joblib through 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 available processors.\n    return list(c.calc_many(structures, n_jobs=-1))\n\n%timeit -n 5 -r 1 serial_calc()\n# Output: 8.7 s ± 0 ns per loop (mean ± std. dev. of 1 run, 5 loops each)\n\n%timeit -n 5 -r 1 parallel_calc()\n# Output: 2.08 s ± 0 ns per loop (mean ± std. dev. of 1 run, 5 loops each)\n# This was run on 10 CPUs on a Mac.\n```\n\n### Chaining Calculators\n\n`ChainedCalc` runs a sequence of `PropCalc` instances on a structure, accumulating all output properties.\nTypically, you start with a `RelaxCalc` followed by property calculators. Set `relax_structure=False` in\ndownstream calculators to avoid redundant relaxations.\n\n```python\nimport matcalc as mtc\nimport numpy as np\n\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  # Skip re-relaxation since we already relaxed above.\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,  # Skip re-relaxation since we already relaxed above.\n    relax_deformed_structures=True,\n)\nprop_calc = mtc.ChainedCalc([relax_calc, energetics_calc, elast_calc])\nresults = prop_calc.calc(structure)\n```\n\n`ChainedCalc` also works with `calc_many` for parallel execution over many structures.\n\n### CLI Tool\n\nA command-line interface allows computing properties for any structure file:\n\n```shell\n# Compute elastic constants for a CIF file using the default TensorNet model\nmatcalc calc -p ElasticityCalc -s Li2O.cif\n\n# Use a specific model and write output to a JSON file\nmatcalc calc -p RelaxCalc -m TensorNet -s structure.cif -o results.json\n\n# Clear the local benchmark data cache\nmatcalc clear\n```\n\nAny format supported by pymatgen's `Structure.from_file()` method is accepted for input structures.\nAvailable property calculators can be checked with `matcalc calc -h`.\n\n## Benchmarking\n\nMatCalc includes a benchmarking framework released alongside [MatPES].\n\n```python\nimport matcalc as mtc\n\ncalculator = mtc.load_fp(\"TensorNet-PES-MatPES-PBE-2025.2\")\nbenchmark = mtc.benchmark.ElasticityBenchmark(fmax=0.05, relax_structure=True)\nresults = benchmark.run(calculator, \"TensorNet-MatPES\")\n```\n\nThe entire run takes about 16 minutes when parallelized over 10 CPUs on a Mac.\n\nTo run multiple benchmarks on multiple models:\n\n```python\nimport matcalc as mtc\n\ntensornet = mtc.load_fp(\"TensorNet-PES-MatPES-PBE-2025.2\")\nm3gnet = mtc.load_fp(\"M3GNet-PES-MatPES-PBE-2025.1\")\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\nFull benchmark runs are computationally intensive. Set `n_samples` when initializing a benchmark to test on a\nsubset before running the full suite. HPC resources are recommended for full benchmark runs.\n\n## Docker Images\n\nDocker images with MatCalc and LAMMPS support are available at the [Materialyze AI Docker Repository].\n\n## Tutorials\n\nAnubhav Jain (@computron) has created a [YouTube tutorial](https://youtu.be/57Elhe4IIhI?si=KbZh5s7HAyNGvmFT) on\nusing MatCalc to quickly obtain material properties.\n\n## FAQs\n\n### Which MLIP or foundation potential should I use?\n\nThink of a model as **architecture + training data**, and pick the dataset first — it usually matters more than the\narchitecture. We currently recommend three:\n\n- **MatPES** (PBE or r2SCAN) for solids\n- **OMat24** for solids where rattled-structure coverage matters (e.g. phonons)\n- **OMol25** for molecules\n\nMost other public models are trained on **MPTrj**, which is noisy and outdated; we don't recommend it. The [MatPES]\nwebsite provides head-to-head benchmarks between MatPES and OMat24 to help you choose.\n\n**MatPES** uses the latest pseudopotentials with tight energy and force convergence, and is also available at the\n**r2SCAN** level. MatPES-trained models tend to be the most stable and give excellent property predictions across the\nboard. The main caveat is the absence of a Hubbard U, so PBE-trained MatPES models can be off for oxidation-state\nenergies, voltages, and similar quantities — the r2SCAN variant largely addresses this.\n\n**OMat24** suffers from PBE / PBE+U discontinuities and looser convergence criteria, but its rattled structures tend to\nyield slightly better phonons and phonon-derived properties.\n\nOnce the dataset is fixed, there is little to separate the architectures. We default to **TensorNet** for its parameter\nefficiency and speed; **GRACE** and **MACE** are also excellent choices. TensorNet and MACE have MatPES-trained checkpoints\navailable via `matcalc.load_fp`.\n\nThere is no substitute for benchmarking on the property you actually care about — MatCalc is built to make that easy.\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://materialyzeai.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[Materialyze AI Docker Repository]: https://hub.docker.com/orgs/materialyzeai/repositories\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaterialyzeai%2Fmatcalc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaterialyzeai%2Fmatcalc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaterialyzeai%2Fmatcalc/lists"}