{"id":9978,"library":"nequip-allegro","title":"Allegro Equivariant Deep Learning Interatomic Potentials","description":"Allegro is an open-source Python library for building highly scalable and accurate equivariant deep learning interatomic potentials, often used in materials science and molecular dynamics. It is currently at version 0.8.2 and sees active development with frequent minor releases and occasional breaking changes in major versions.","status":"active","version":"0.8.2","language":"en","source_language":"en","source_url":"https://github.com/mir-group/allegro","tags":["deep learning","interatomic potentials","physics","equivariant neural networks","molecular dynamics","materials science","AI for science"],"install":[{"cmd":"pip install nequip-allegro","lang":"bash","label":"Install latest version"},{"cmd":"pip install nequip-allegro[cu-equiv]","lang":"bash","label":"Install with CuEquivariance acceleration (requires NVIDIA GPU)"}],"dependencies":[{"reason":"Allegro is built on top of the NequIP framework and requires a compatible version.","package":"nequip","optional":false},{"reason":"Core deep learning framework.","package":"torch","optional":false},{"reason":"Optional dependency for NVIDIA CuEquivariance acceleration.","package":"cu-equiv","optional":true}],"imports":[{"symbol":"AllegroModel","correct":"from allegro.model import AllegroModel"},{"symbol":"EMALightningModule","correct":"from allegro.train import EMALightningModule"}],"quickstart":{"code":"import torch\nfrom allegro.model import AllegroModel\n\n# Minimal configuration for an Allegro model\n# In a real-world scenario, this would often be loaded from a YAML config file.\nconfig = {\n    \"r_max\": 3.0,\n    \"l_max\": 1,\n    \"parity_l_max\": 1,\n    \"chemical_species\": [\"H\", \"O\"], # Define the species the model will handle\n    \"output_keys\": {\"energy\": \"total_energy\"},\n    \"avg_num_neighbors\": 10.0,\n    \"num_hidden_layers\": 1,\n    \"layer_l_maxs\": [1, 1],\n    \"feature_irreps_hidden\": \"16x0e + 16x1o\",\n    \"nonlinearity_type\": \"gate\",\n    \"cutoff_type\": \"wigner_d\",\n    \"radial_basis\": \"gaussian\",\n    \"radial_basis_kwargs\": {\"max_radial\": 10, \"num_basis\": 8},\n    \"num_basis_f\": 8,\n    \"embedding_units\": 16,\n    \"num_layers\": 1\n}\n\n# Create an instance of the Allegro model\n# This initializes the model structure, but it is not yet trained.\nmodel = AllegroModel(config)\n\nprint(\"AllegroModel created successfully.\")\nprint(f\"Model output irreps: {model.num_irreps_out}\")\n\n# Example of forward pass (requires a nequip.data.Graph object)\n# For a full example, refer to nequip and allegro documentation\n# on creating datasets and training graphs.","lang":"python","description":"This quickstart demonstrates how to programmatically define and instantiate a basic `AllegroModel` instance. It sets up a minimal configuration dictionary and passes it to the `AllegroModel` constructor. Note that this only builds the model architecture; training or inference requires additional steps using the NequIP framework, including data loading and graph creation."},"warnings":[{"fix":"Replace `AllegroEnergyModel(...)` with `AllegroModel(..., do_derivatives=False)`.","message":"The `AllegroEnergyModel` class was removed in version 0.8.0. For energy-only models, use `AllegroModel` with `do_derivatives=False`.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Always check the `nequip-allegro` release notes (e.g., `minimum nequip version is v0.17.0` for Allegro 0.8.2) and install the specified `nequip` version using `pip install nequip==X.Y.Z` before or alongside `nequip-allegro`.","message":"Allegro has strict compatibility requirements with `nequip` versions. Installing an incompatible `nequip` version will lead to runtime errors or unexpected behavior.","severity":"breaking","affected_versions":"All versions"},{"fix":"Refer to the official Allegro documentation for the updated method of integrating custom Triton TP kernels, or revert to versions <0.6.0 if custom kernels are critical and unmigrated.","message":"The mechanism for using custom Triton TP kernels was changed in version 0.6.0, potentially breaking existing custom implementations.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Consult the 'CuEquivariance Acceleration' section in the official Allegro documentation for detailed instructions on configuring your NequIP training pipeline to leverage CuEquivariance.","message":"Integrating CuEquivariance for acceleration requires specific configuration modifications within your `nequip` config file (e.g., using `nequip.model.modify` with the `training_module`). It is not activated by direct Python imports alone.","severity":"gotcha","affected_versions":">=0.7.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Use `from allegro.model import AllegroModel` and set `do_derivatives=False` in its constructor if you need an energy-only model: `AllegroModel(..., do_derivatives=False)`.","cause":"The `AllegroEnergyModel` class was removed in Allegro v0.8.0.","error":"AttributeError: module 'allegro.model' has no attribute 'AllegroEnergyModel'"},{"fix":"Uninstall existing `nequip` and `nequip-allegro` and reinstall `nequip` with the required version, then `nequip-allegro`. For example, for Allegro 0.8.2, run `pip uninstall nequip nequip-allegro` then `pip install nequip>=0.17.0` followed by `pip install nequip-allegro`.","cause":"The installed `nequip` package version does not meet the minimum requirement for the installed `nequip-allegro` version.","error":"RuntimeError: The installed version of nequip (X.Y.Z) is incompatible with allegro (requires >=0.17.0)"},{"fix":"Ensure `nequip-allegro` is installed by running `pip install nequip-allegro`. Verify the import statement `from allegro.model import AllegroModel` is correct and matches the official documentation.","cause":"The `nequip-allegro` package might not be correctly installed, or there's a typo in the import statement.","error":"ImportError: cannot import name 'AllegroModel' from 'allegro.model' (.../allegro/model/__init__.py)"}]}