Formation energies in ML potentials

[zulissimeta]

Summary of Changes

This PR adds support for formation energy calculations in MLP recipes via the FAIRChem FormationEnergyCalculator wrapper. Formation energies are now accessible through two new parameters in static_job() and relax_job():

• use_formation_energy (bool): Enables formation energy calculation (currently FAIRChem UMA with task_name='omat' only)
• formation_energy_kwargs (dict): Optional custom kwargs to pass to the FormationEnergyCalculator

Key Changes

1. Core Implementation (src/quacc/recipes/mlp/_base.py):

   • Added use_formation_energy and formation_energy_kwargs parameters to pick_calculator()
   • Implemented validation chain ensuring FAIRChem UMA omat configuration is used
   • Calculator wrapping handled transparently at the factory level, benefiting all recipes

2. API Exposure (src/quacc/recipes/mlp/core.py):

   • Added explicit parameters to static_job() and relax_job() for clarity and IDE autocomplete
   • Updated comprehensive docstrings

3. Testing (tests/core/recipes/mlp_recipes/test_core_recipes.py):

   • Added 6 new test functions covering:
     • Static calculations (elemental and binary compounds)
     • Relaxations (atomic and cell relaxation)
     • Multiple compound types
     • Error handling for unsupported configurations
   • All tests properly skip if fairchem not installed

4. Documentation (src/quacc/recipes/mlp/__init__.py):

   • Updated module docstring with FAIRChem-specific examples
   • Clarified limitations and supported configuration

Usage Example

from ase.build import bulk
from quacc.recipes.mlp.core import static_job

# Calculate formation energy for MgO
atoms = bulk("MgO", crystalstructure="rocksalt", a=4.2)
result = static_job(
    atoms,
    method="fairchem",
    name_or_path="uma-s-1",
    task_name="omat",
    use_formation_energy=True,
)
# result["results"]["energy"] contains formation energy (total energy, not per atom)

Requirements

• My PR is focused on a single feature addition or bugfix.
• My PR has relevant, comprehensive unit tests.
• My PR is on a custom branch (i.e. is not named main).

Note: If you are an external contributor, you will see a comment from @buildbot-princeton. This is solely for the maintainers.

[buildbot-princeton]

Can one of the admins verify this patch?

[codecov]

Codecov Report

❌ Patch coverage is 23.80952% with 32 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.88%. Comparing base (173dc82) to head (64c104e).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/quacc/recipes/mlp/_base.py	17.94%	32 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3122      +/-   ##
==========================================
- Coverage   97.69%   96.88%   -0.82%     
==========================================
  Files          97       97              
  Lines        4172     4210      +38     
==========================================
+ Hits         4076     4079       +3     
- Misses         96      131      +35     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.