{"id":9977,"library":"nequip","title":"NequIP","description":"NequIP is an open-source Python library for building E(3)-equivariant interatomic potentials, primarily used in molecular dynamics and materials science simulations. It leverages PyTorch and e3nn for deep learning models that respect physical symmetries, enabling accurate and robust simulations. The current stable version is 0.17.1, with releases typically tied to significant feature additions or dependency updates.","status":"active","version":"0.17.1","language":"en","source_language":"en","source_url":"https://github.com/mir-group/nequip","tags":["machine learning","molecular dynamics","materials science","deep learning","equivariant neural networks","interatomic potentials","pytorch"],"install":[{"cmd":"pip install nequip","lang":"bash","label":"Install NequIP"}],"dependencies":[{"reason":"Core deep learning framework","package":"torch","optional":false},{"reason":"E(3)-equivariant neural network building blocks","package":"e3nn","optional":false},{"reason":"Atomic Simulation Environment for I/O and calculator interfaces","package":"ase","optional":false}],"imports":[{"symbol":"NequIP","correct":"from nequip.model import NequIP"},{"symbol":"Config","correct":"from nequip.utils import Config"},{"note":"Commonly used for programmatically invoking the training script.","symbol":"train_main","correct":"from nequip.scripts.train import main as train_main"}],"quickstart":{"code":"import torch\nfrom nequip.utils import Config\nfrom nequip.model import NequIP\n\n# Example minimal configuration for a NequIP model\n# In real applications, this would typically be loaded from a YAML file.\nconfig_dict = {\n    'r_max': 5.0,\n    'max_ell': 1,\n    'num_layers': 3,\n    'chemical_species_set': ['H', 'O'], # Example species\n    'num_species': 2,\n    'l_max_hidden': 1,\n    'nonlinearity_type': 'silu',\n    'resnet': True,\n    'env_embed_multi_head': True,\n    'mlp_output_irreps': '64x0e+64x1o+64x1e',\n    'weight_init': 'xavier_uniform',\n    'irreps_out_per_structure': '1x0e',\n    'cutoff_type': 'polynomial', \n    'activation': 'silu'\n}\n\n# Create a Config object\nconfig = Config(config_dict)\n\n# Initialize the NequIP model\n# This model is a placeholder; it would need to be trained or loaded from a checkpoint.\nmodel = NequIP(config)\n\nprint(f\"NequIP model initialized with {sum(p.numel() for p in model.parameters())} parameters.\")\n# Example of model structure for a single atom\n# x = torch.zeros(1, 3)\n# z = torch.tensor([1]) # Atomic number for H\n# model(x, z) # Requires a full batch of positions and atomic numbers\n","lang":"python","description":"Initializes a basic NequIP model from a configuration dictionary. In practice, configurations are often loaded from YAML files and models are either trained or loaded from pre-existing checkpoints. This example demonstrates the fundamental model instantiation."},"warnings":[{"fix":"Re-train your models using NequIP v0.17.0+, or refer to the NequIP documentation for any experimental conversion scripts if available (not officially supported for all versions).","message":"The internal structure of the `NequIP` model's parameters and buffers significantly changed in v0.17.0. Saved models trained with NequIP versions <0.17.0 are incompatible and will fail to load or produce incorrect results. They require re-training or conversion.","severity":"breaking","affected_versions":">=0.17.0"},{"fix":"Ensure your `e3nn` installation is compatible with your `nequip` version. For NequIP v0.16.0+, run `pip install e3nn>=0.5.0` to guarantee the correct version.","message":"NequIP has a strict dependency on `e3nn` versions. Specifically, NequIP >=0.16.0 requires `e3nn>=0.5.0`. Mismatched `e3nn` versions can lead to `AttributeError` or unexpected behavior during model definition or computation.","severity":"gotcha","affected_versions":">=0.16.0"},{"fix":"Always refer to the documentation for your specific NequIP version for the correct configuration file schema. Adapt older YAML files to the new format, or regenerate them using updated examples.","message":"Configuration file formats (YAML) have changed across major NequIP versions. Using an older configuration file with a newer NequIP version can lead to `KeyError`, schema validation errors, or incorrect model behavior.","severity":"gotcha","affected_versions":"<0.4.0, >0.4.0, various intermediate"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Upgrade `e3nn` to the version required by your NequIP installation. For NequIP v0.16.0+, use `pip install e3nn>=0.5.0`.","cause":"This typically indicates an incompatibility between your installed `e3nn` and `nequip` versions. Older `e3nn` versions (e.g., v0.4.x) lack symbols or have different API signatures required by newer NequIP.","error":"AttributeError: module 'e3nn' has no attribute 'o3' (or similar e3nn related errors like 'TensorProduct' object has no attribute 'irrep_out')"},{"fix":"Review the NequIP documentation for your installed version and compare your YAML config file to the latest examples. Update keys, structure, or re-create the config based on the current schema.","cause":"Your configuration file (YAML) is either malformed or uses a schema/keys that are no longer valid for your current NequIP version. This is common when upgrading NequIP and reusing old config files.","error":"KeyError: 'some_config_key' or 'yaml.scanner.ScannerError: while scanning a block scalar'"},{"fix":"The model checkpoint is fundamentally incompatible. You must re-train the model with NequIP v0.17.0+ or revert your NequIP installation to the version the model was trained with.","cause":"This error occurs when trying to load a pre-trained model checkpoint that was saved with an older NequIP version (pre-0.17.0) into a newer NequIP installation. The model's internal parameter structure has changed.","error":"RuntimeError: Error(s) in loading state_dict for NequIP: Missing key(s) in state_dict: \"_c_rescalers.0.x_in\"..."}]}