matcalc

A python library for calculating materials properties from the PES

https://github.com/materialsvirtuallab/matcalc

Science Score: 36.0%

This score indicates how likely this project is to be science-related based on various indicators:

○
CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
○
DOI references
○
Academic publication links
✓
Committers with academic emails
1 of 17 committers (5.9%) from academic institutions
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (15.3%) to scientific vocabulary

Keywords

learning machine materials pes properties

Keywords from Contributors

materials-science materials-informatics machine-learning-force-field materials-discovery spectroscopy mesh hydrology regionalization energy-system exoplanet

Last synced: 6 months ago · JSON representation

Repository

A python library for calculating materials properties from the PES

Basic Info

Host: GitHub
Owner: materialsvirtuallab
License: bsd-3-clause
Language: Python
Default Branch: main
Homepage: http://matcalc.ai/
Size: 223 MB

Statistics

Stars: 117
Watchers: 7
Forks: 27
Open Issues: 3
Releases: 18

Topics

learning machine materials pes properties

Created over 2 years ago · Last pushed 6 months ago

Metadata Files

Readme Changelog License Citation

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 and MAML packages, the MatPES dataset, and the MatCalc.

Documentation

The API documentation and tutorials are available at http://matcalc.ai.

Outline

The main base class in MatCalc is PropCalc (property calculator). All PropCalc subclasses 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.getstructurebymaterialid("mp-149") c = mtc.ElasticityCalc("TensorNet-MatPES-PBE-v2025.1-PES", relaxstructure=True) props = c.calc(si) print(f"KVRH = {props['bulkmodulusvrh'] * 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 be 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 parallelcalc(): # njobs = -1 uses all processors available. return list(c.calcmany(structures, njobs=-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.loadfp("TensorNet-MatPES-PBE-v2025.1-PES") benchmark = mtc.benchmark.ElasticityBenchmark(fmax=0.05, relaxstructure=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.loadfp("TensorNet-MatPES-PBE-v2025.1-PES") m3gnet = mtc.loadfp("M3GNet-MatPES-PBE-v2025.1-PES")

elasticitybenchmark = mtc.benchmark.ElasticityBenchmark(fmax=0.5, relaxstructure=True) phononbenchmark = mtc.benchmark.PhononBenchmark(writephonon=False) suite = mtc.benchmark.BenchmarkSuite(benchmarks=[elasticitybenchmark, phononbenchmark]) results = suite.run({"M3GNet": m3gnet, "TensorNet": tensornet}) results.tocsv("benchmarkresults.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.

Tutorials

Anubhav Jain (@computron) has created a nice YouTube tutorial on how to use MatCalc to quickly obtain properties of materials.

Citing

A manuscript on matcalc is currently in the works. In the meantime, please see citation.cff or the GitHub sidebar for a BibTeX and APA citation.

Owner

Name: Materials Virtual Lab
Login: materialsvirtuallab
Kind: organization
Email: ongsp@ucsd.edu
Location: La Jolla, CA

Website: www.materialsvirtuallab.org
Repositories: 33
Profile: https://github.com/materialsvirtuallab

The Materials Virtual Lab is dedicated to the application of first principles calculations and informatics to accelerate materials design.

GitHub Events

Total

Create event: 30
Commit comment event: 4
Release event: 16
Issues event: 19
Watch event: 44
Delete event: 15
Issue comment event: 109
Push event: 342
Pull request review event: 16
Pull request review comment event: 15
Pull request event: 83
Fork event: 12

Last Year

Create event: 30
Commit comment event: 4
Release event: 16
Issues event: 19
Watch event: 44
Delete event: 15
Issue comment event: 109
Push event: 342
Pull request review event: 16
Pull request review comment event: 15
Pull request event: 83
Fork event: 12

Committers

Last synced: 9 months ago

All Time

Total Commits: 688
Total Committers: 17
Avg Commits per committer: 40.471
Development Distribution Score (DDS): 0.503

Past Year

Commits: 495
Committers: 14
Avg Commits per committer: 35.357
Development Distribution Score (DDS): 0.347

Top Committers

Name	Email	Commits
Shyue Ping Ong	s**p@g**m	342
Runze Liu	1****8	121
Shyue Ping Ong	sp@o****i	71
Janosh Riebesell	j**l@g**m	70
Atul Thakur	a**0@g**m	21
PROA200	8****0	14
dependabot[bot]	4****]	11
kenko911	k**1@g**m	8
pre-commit-ci[bot]	6****]	8
Anthony Onwuli	a**6@i**k	6
Zihan Yu	d**u@l**v	5
BowenD-UCB	8****B	4
lbluque	l**e@m**m	3
Zihan Yu	d**u@l**v	1
Zihan Yu	d**u@l**v	1
Runze Liu	r**8@l**v	1
Ji Qi	5****5	1

Committer Domains (Top 20 + Academic)

login17.chn.perlmutter.nersc.gov: 1 login19.chn.perlmutter.nersc.gov: 1 login37.chn.perlmutter.nersc.gov: 1 meta.com: 1 login29.chn.perlmutter.nersc.gov: 1 imperial.ac.uk: 1 ong.ai: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 18
Total pull requests: 129
Average time to close issues: 9 days
Average time to close pull requests: 12 days
Total issue authors: 13
Total pull request authors: 16
Average comments per issue: 1.72
Average comments per pull request: 1.65
Merged pull requests: 106
Bot issues: 0
Bot pull requests: 48

Past Year

Issues: 13
Pull requests: 87
Average time to close issues: 7 days
Average time to close pull requests: 11 days
Issue authors: 11
Pull request authors: 13
Average comments per issue: 1.15
Average comments per pull request: 1.36
Merged pull requests: 70
Bot issues: 0
Bot pull requests: 36

View more stats

Top Authors

Issue Authors

shyuep (4)
Andrew-S-Rosen (3)
wakamiya0315 (1)
Asecretboy (1)
alinelena (1)
t-reents (1)
matthewkuner (1)
tankylz (1)
janosh (1)
atulcthakur (1)
svandenhaute (1)
esoteric-ephemera (1)
computron (1)

Pull Request Authors

rul048 (31)
dependabot[bot] (26)
pre-commit-ci[bot] (22)
atulcthakur (11)
janosh (9)
kenko911 (6)
Andrew-S-Rosen (5)
bowen-bd (4)
AntObi (4)
lbluque (2)
drakeyu (2)
leslie-zheng (2)
computron (2)
PROA200 (1)
JiQi535 (1)

Top Labels

Issue Labels

bug (7) enhancement (3) elast (1) relax (1)

Pull Request Labels

dependencies (28) ruby (20) fix (5) python (4) enhancement (4) docs (4) ux (2) breaking (2) tests (2) new calc (2) matgl (2) ase (2) neb (2) types (1) refactor (1) relax (1) needs testing (1) eos (1) elast (1)

Packages

Total packages: 1
Total downloads:
- pypi 4,408 last-month

Total dependent packages: 2
Total dependent repositories: 1
Total versions: 18
Total maintainers: 1

pypi.org: matcalc

Calculators for materials properties from the potential energy surface.

Documentation: https://matcalc.readthedocs.io/
License: BSD License
Latest release: 0.4.3
published 6 months ago

Versions: 18
Dependent Packages: 2
Dependent Repositories: 1
Downloads: 4,408 Last month

Rankings

Downloads: 4.5%

Dependent packages count: 4.7%

Average: 10.3%

Dependent repos count: 21.7%

Maintainers (1)

Shyue.Ping.Ong

Last synced: 6 months ago

Dependencies

.github/workflows/linting.yml actions

actions/checkout v3 composite
actions/setup-python v4 composite

.github/workflows/testing.yml actions

actions/checkout v3 composite
actions/download-artifact v3 composite
actions/setup-python v4 composite
actions/upload-artifact v3 composite
coverallsapp/github-action v2 composite
pypa/gh-action-pypi-publish release/v1 composite

pyproject.toml pypi

requirements-ci.txt pypi

black *
coverage *
coveralls *
matgl *
mypy *
pytest *
pytest-cov *
ruff *

requirements.txt pypi

ase ==3.22.1
joblib ==1.3.1
pymatgen ==2023.7.11

setup.py pypi

matcalc

Science Score: 36.0%

Keywords

Keywords from Contributors

Repository

Basic Info

Statistics

Topics

Metadata Files

README.md

Introduction

Documentation

Outline

Basic Usage

Output is 8.7 s 0 ns per loop (mean std. dev. of 1 run, 5 loops each)

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.

CLI tool

Benchmarking

Docker Images

Tutorials

Citing

Owner

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

pypi.org: matcalc

Rankings

Maintainers (1)

Dependencies