{"id":25882078,"url":"https://github.com/materialsvirtuallab/matcalc","last_synced_at":"2025-04-05T05:02:50.902Z","repository":{"id":183972444,"uuid":"670410006","full_name":"materialsvirtuallab/matcalc","owner":"materialsvirtuallab","description":"A python library for calculating materials properties from the PES","archived":false,"fork":false,"pushed_at":"2025-04-02T01:50:33.000Z","size":177555,"stargazers_count":78,"open_issues_count":3,"forks_count":19,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-02T02:21:49.746Z","etag":null,"topics":["learning","machine","materials","pes","properties"],"latest_commit_sha":null,"homepage":"http://matcalc.ai/","language":"Jupyter Notebook","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/materialsvirtuallab.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}},"created_at":"2023-07-25T02:04:04.000Z","updated_at":"2025-04-01T17:06:50.000Z","dependencies_parsed_at":"2023-07-26T15:39:53.213Z","dependency_job_id":"cdc0aec0-59c3-4e86-918c-507c3d06013b","html_url":"https://github.com/materialsvirtuallab/matcalc","commit_stats":null,"previous_names":["materialsvirtuallab/matcalc"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/materialsvirtuallab%2Fmatcalc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/materialsvirtuallab%2Fmatcalc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/materialsvirtuallab%2Fmatcalc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/materialsvirtuallab%2Fmatcalc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/materialsvirtuallab","download_url":"https://codeload.github.com/materialsvirtuallab/matcalc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246742793,"owners_count":20826401,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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-03-02T15:57:10.366Z","updated_at":"2025-04-05T05:02:50.896Z","avatar_url":"https://github.com/materialsvirtuallab.png","language":"Jupyter Notebook","funding_links":[],"categories":["Interatomic Potentials (ML-IAP)"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/materialsvirtuallab/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/materialsvirtuallab/matcalc/workflows/Test/badge.svg)](https://github.com/materialsvirtuallab/matcalc/workflows/Test/badge.svg)\n[![Lint](https://github.com/materialsvirtuallab/matcalc/workflows/Lint/badge.svg)](https://github.com/materialsvirtuallab/matcalc/workflows/Lint/badge.svg)\n[![codecov](https://codecov.io/gh/materialsvirtuallab/matcalc/branch/main/graph/badge.svg?token=OR7Z9WWRRC)](https://codecov.io/gh/materialsvirtuallab/matcalc)\n[![Requires Python 3.10+](https://img.shields.io/badge/Python-3.10+-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/materialsvirtuallab/matcalc)](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) -\u003e 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 universal MLIPs as well as an interface to\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(mtc.load_up(\"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 output is `K_VRH = 102.08363100102596 GPa`.\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_up(\"pbe\")\nr2scan_calculator = mtc.load_up(\"r2scan\")\n```\n\nAt the time of writing, these are the TensorNet-MatPES models. However, these recommendations may updated as improved\nmodels 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 ± 0 ns per loop (mean ± std. dev. of 1 run, 5 loops each)\n\n%timeit -n 5 -r 1 parallel_calc()\n# Output is 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\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_up(\"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 universal MLIPs 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` UMLIP.\n\n```python\nimport matcalc as mtc\n\ncalculator = mtc.load_up(\"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_up(\"TensorNet-MatPES-PBE-v2025.1-PES\")\nm3gnet = mtc.load_up(\"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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaterialsvirtuallab%2Fmatcalc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaterialsvirtuallab%2Fmatcalc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaterialsvirtuallab%2Fmatcalc/lists"}