Add customized potential interface to matcalc/utils.py

[rul048]

With the emergence and continuous advancement of universal machine learning interatomic potentials (uMLIPs), the high-throughput computation of material properties directly from the potential energy surface (PES) has become increasingly efficient. However, users may sometimes want to use their own potentials, like SNAP, which are specifically tailored to the systems of interest. These potentials may not even be based on graph neural networks (GNNs), but we still want to provide flexibility for incorporating such models with MatCalc.

As suggested by Dr. Ong, I built an interface to load customized potentials to use MatCalc to do property calculations.

Specifically, I create a class called PESCalculator that included static factory methods like load_matgl, load_snap, load_ace, etc. These methods allowed users to load customized potentials from libraries such as MatGL, MAML, and PyACE.

This approach is also compatible with universal potentials. Users can load them by calling load_universal and specifying the model name, which follows a similar logic to the get_universal_calculators method.

The existing get_universal_calculator method will be deprecated in the future. When users call this method, they will receive a warning recommending they use PESCalculator.load_YOUR_MODEL() instead.

Currently, the supported potentials include:

• Customized potentials: MatGL(M3GNet, CHGNet, TensorNet and SO3Net), MAML(MTP, GAP, NNP, SNAP and qSNAP) and ACE.
• Universal potentials: M3GNet, CHGNet, MACE and SevenNet.

I also plan to add support for the ORB universal potential, as well as CHGNet, MACE, etc. customized potentials in the future.

Summary

Major changes:

• feature 1: ...
• fix 1: ...

Todos

If this is work in progress, what else needs to be done?

• feature 2: ...
• fix 2:

Checklist

• Google format doc strings added. Check with ruff.
• Type annotations included. Check with mypy.
• Tests added for new features/fixes.
• If applicable, new classes/functions/modules have duecredit @due.dcite decorators to reference relevant papers by DOI (example)

Tip: Install pre-commit hooks to auto-check types and linting before every commit:

pip install -U pre-commit
pre-commit install

[shyuep]

1. Pls make sure your PRs have properly filled in information. It is very difficult for maintenance if the information is inaccurate.
2. Unittests are needed.
3. I would suggest the following organization instead of the one you did:
   a. Rename PotentialCalculator to PESCalculator.
   b. Instead of a method called get_custom_calculator, you have PESCalculator.load_mtp, load_gap, load_nnp static factory methods. People need to define what the potential is and the types of args kwargs required should be explicity. You should not depend on the name to determine whether it is an MTP, NNP or GAP and use **kwargs. This makes it extremely difficult for an outsider who is not familiar with maml to use.. I do not even really know what the "name" is for. It does not seem to be used except for loading.
   c. Add a load_universal static method. This replicates the functionality of the get_unversal_calculator method. Do not remove the get_universal_calculator for now. I will think of how to properly deprecate it.

[kenko911]

Already learned a lot from the comments.

[rul048]

1. Pls make sure your PRs have properly filled in information. It is very difficult for maintenance if the information is inaccurate.
2. Unittests are needed.
3. I would suggest the following organization instead of the one you did:
   a. Rename PotentialCalculator to PESCalculator.
   b. Instead of a method called get_custom_calculator, you have PESCalculator.load_mtp, load_gap, load_nnp static factory methods. People need to define what the potential is and the types of args kwargs required should be explicity. You should not depend on the name to determine whether it is an MTP, NNP or GAP and use **kwargs. This makes it extremely difficult for an outsider who is not familiar with maml to use.. I do not even really know what the "name" is for. It does not seem to be used except for loading.
   c. Add a load_universal static method. This replicates the functionality of the get_unversal_calculator method. Do not remove the get_universal_calculator for now. I will think of how to properly deprecate it.

What great suggestions! Thanks for your feedback, professor. I would like to make good use of any opportunity to learn how to be an excellent developer and programmer from you.

For the load_universal static method, we still need the uses to specify the uMLIP type that they're using by an argument. How about I directly add functions like load_chgnet, load_mace and load_sevennet?

[shyuep]

For the load universal, it is usually a pre-trained model. So for these, we can just have a load_universal method.

[rul048]

I noticed there seemed to be a new open-source universal model released yesterday called ORB developed by Orbital Materials Ltd, which is the new SOTA model on MatBench Discovery. Their licence agreement looks a little complicated. Do you want to add it to our MatCalc?

[janosh]

Their licence agreement looks a little complicated.

not complicated actually, the only real requirement on their license is that you prefix derivative models as ORB-XYZ and have a prominent "Built with ORB" statement if you use it commercially.

[rul048]

Okay, then I think it should be fine if we just use their models to do our own MatCalc calculations.

[AntObi]

I noticed there seemed to be a new open-source universal model released yesterday called ORB developed by Orbital Materials Ltd, which is the new SOTA model on MatBench Discovery. Their licence agreement looks a little complicated. Do you want to add it to our MatCalc?

One thing to point out is that while orb-models is on PyPI, the dependency pynanoflann is not. You should be able to add the pre-trained orb-models to matcalc but there should be some instructions in the repo informing users that to use the pre-trained orb with matcalc, they would also need to install pynanoflann from it's GitHub repository:

pip install "pynanoflann@git+https://github.com/dwastberg/pynanoflann#egg=af434039ae14bedcbb838a7808924d6689274168"

The CI should also include this installation for testing purposes. At least until pynanoflann is made an optional dependency for orb-models.

[janosh]

it's 4-5 times faster than MACE in initial testing (though at higher OOD MD force errors) which would make it a compelling addition to matcalc

[rul048]

Thanks for your kind reminder Anthony. Glad to see you here and glad to see this pull request finally getting more active. I have completed the code for loading the ORBCalculator and it still needs more testing.

[shyuep]

No need. They can add their model if they wish.

[shyuep]

Also, one PR at a time. We deal with this Pr. The Orb, even if we want to add it, is another PR.

[shyuep]

How long do we need to wait for the unittests?

[rul048]

It is extremely difficult to test the python-ace and lammps dependent features on GitHub, particularly some potentials need to be compiled into lammps. As a solution, I will skip these tests on GitHub but provide screenshots to demonstrate successful execution on my local machine.

Specifically, on GitHub, I will mainly focus on testing whether the MAML potentials can be successfully loaded into the PESCalculator. Meanwhile, I will test the PESCalculator loading for ACE potential and EFS calculation for MAML potentials on my PC.

[rul048]

It seems that some essential parameter files like maml/apps/pes/params/GAP.json are missing from the installed package using pip install maml or pip install git+https://github.com/materialsvirtuallab/maml.git. This results in a FileNotFoundError when loading with maml.

I think this appears to occur because the package data is not correctly specified in the installation configuration of the maml package, specifically in the pyproject.toml file. The tool.setuptools.package-data does not include maml/apps/pes/params/*.json, so these parameter files are not copied to the installation directory during installation. The issue is resolved when using git clone https://github.com/materialsvirtuallab/maml.git and installing locally, but this workaround is not ideal for GitHub testing.

Please check whether this is the cause and try to fix it. Thank you.@zz11ss11zz

[rul048]

I am so upset that the codecov decreased from 100% to 96%.😞

[rul048]

I would like to thank Prof. Ong (@shyuep) and Dr. Wang (@zz11ss11zz) for their invaluable assistance in fixing MAML. Currently, I am installing the package using pip install git+https://github.com/materialsvirtuallab/maml.git since the latest version has not yet been released. Once the new version is available on PyPI, I will switch to installing MAML directly from PyPI for a more streamlined and stable setup.