ase-calculator-kit

A thin ASE calculator factory for machine-learning interatomic potentials, VASP, Quantum ESPRESSO, and molecular PySCF/GPU4PySCF. It selects upstream calculators, validates inputs, and records calculation conditions.

MLIP settings are Python keyword arguments. DFT settings use YAML or a configuration dictionary. No heavy backend is imported until requested.

Install

pip install ase-calculator-kit                 # ASE + PyYAML core
pip install 'ase-calculator-kit[sevennet]'      # choose a backend
pip install 'ase-calculator-kit[orb]'           # OrbMol-v2; Python 3.12
pip install 'ase-calculator-kit[uma]'           # UMA (Hugging Face access)
pip install 'ase-calculator-kit[esen]'          # eSEN OMol25
pip install 'ase-calculator-kit[pyscf]'         # CPU molecular HF/DFT

For Linux x86_64 with NVIDIA CUDA 12:

pip install 'ase-calculator-kit[gpu4pyscf-cuda12x]'

[all] installs the co-installable MLIP extras and D3. MACE, Orb, and PySCF extras are separate. MACE requires its own environment because its e3nn pin conflicts with several other backends:

python -m venv .venv-mace
.venv-mace/bin/pip install 'ase-calculator-kit[mace]'

MACE-POLAR additionally needs graph_longrange; Orb has a documented dm-tree override on Python 3.13+. Follow installation instructions.

Quickstart: molecular MLIP

from ase.build import molecule
from ase_calculator_kit import get_calculator

atoms = molecule("H2O")
atoms.info.update(charge=0, spin=1)  # spin is MULTIPLICITY: 2S+1
atoms.calc = get_calculator("orb", model="orbmol-v2", device="cpu")
print(atoms.get_potential_energy())  # eV
print(atoms.get_forces())            # eV/Angstrom

UMA/eSEN OMol, OrbMol, MACE-OMOL-0 and MACE-POLAR require explicit electronic states. MACE-POLAR also reads atoms.info["external_field"] in V/Angstrom. See molecular inputs and cache behavior.

For a material, the same ASE interface accepts other backends:

from ase.build import bulk

atoms = bulk("Cu", "fcc", a=3.6)
atoms.calc = get_calculator("sevennet", model="7net-omni", modal="mpa")
print(atoms.get_potential_energy())

Quickstart: molecular DFT

from ase.build import molecule
from ase_calculator_kit import get_calculator

atoms = molecule("H2O")
atoms.info.update(charge=0, spin=1)
calc = get_calculator("pyscf", config={
    "calculator": "pyscf",  # use gpu4pyscf in both places for GPU
    "directory": "runs/water",
    "parameters": {
        "basis": "def2-svp",
        "xc": "pbe",
        "density_fit": True,
        "retain_scf": True,
    },
})
atoms.calc = calc
print(atoms.get_potential_energy())
print(atoms.get_forces())
hessian = calc.get_hessian(atoms)  # (3N, 3N), eV/Angstrom^2
print(calc.metadata["scf"])
calc.reset()  # release retained SCF/log resources

YAML spin is 2S; atoms.info["spin"] is multiplicity. Conflicts raise an error. Density fitting defaults to false on both CPU and GPU; the GPU examples explicitly enable it. Density reuse between geometries is opt-in too.

See PySCF settings, checkpoints and Hessians and complete DFT examples. VASP/QE require explicit execution commands and QE requires explicit pseudopotential settings.

Supported backends

Dispersion is model-dependent; the kit rejects double-counting. See the training levels and dispersion policy.

Documentation

Start at the documentation index.

• Installation and compatibility
• Factory API and model selection
• Charge, spin and electric fields
• D3 settings and Apple Silicon
• PySCF/GPU4PySCF
• Validation records
• Development, Japanese implementation guide, and releases
• Changes by version

Citation

If this package contributed to published work, please cite the archived release. CITATION.cff holds the machine-readable metadata — GitHub renders it under "Cite this repository", and Zenodo reads it when minting the DOI.

@software{ase_calculator_kit,
  title  = {ase-calculator-kit: a unified ASE calculator factory for MLIP and DFT calculators},
  author = {Wakamiya, Taishiro and Ishikawa, Atsushi},
  year   = {2026},
  doi    = {10.5281/zenodo.21807793},
  url    = {https://github.com/ishikawa-group/ase-calculator-kit}
}

10.5281/zenodo.21807793 is the concept DOI: it always resolves to the newest archived version. To cite one specific release instead, use its version DOI from the Zenodo record — 0.3.4 is 10.5281/zenodo.21807794.

License

MIT. Upstream software and model weights retain their own licenses; consult the backend documentation before selecting a checkpoint.