All Projects → mir-group → nequip

mir-group / nequip

Licence: MIT license
NequIP is a code for building E(3)-equivariant interatomic potentials

Programming Languages

python
139335 projects - #7 most used programming language

Projects that are alternatives of or similar to nequip

uf3
UF3: a python library for generating ultra-fast interatomic potentials
Stars: ✭ 19 (-93.91%)
Mutual labels:  molecular-dynamics, materials-science, force-fields, interatomic-potentials
CatKit
General purpose tools for high-throughput catalysis
Stars: ✭ 48 (-84.62%)
Mutual labels:  computational-chemistry, materials-science
screenlamp
screenlamp is a Python toolkit for hypothesis-driven virtual screening
Stars: ✭ 20 (-93.59%)
Mutual labels:  computational-chemistry, drug-discovery
QCxMS
Quantum mechanic mass spectrometry calculation program
Stars: ✭ 25 (-91.99%)
Mutual labels:  molecular-dynamics, computational-chemistry
matador
⚗️ matador is an aggregator, manipulator and runner of first-principles calculations, written with a bent towards battery 🔋 electrode materials.
Stars: ✭ 23 (-92.63%)
Mutual labels:  computational-chemistry, materials-science
Deepchem
Democratizing Deep-Learning for Drug Discovery, Quantum Chemistry, Materials Science and Biology
Stars: ✭ 3,324 (+965.38%)
Mutual labels:  drug-discovery, materials-science
calphy
A Python library and command line interface for automated free energy calculations
Stars: ✭ 28 (-91.03%)
Mutual labels:  molecular-dynamics, interatomic-potentials
FLAME
FLAME: a library for atomistic modeling environments
Stars: ✭ 18 (-94.23%)
Mutual labels:  atomistic-simulations, interatomic-potentials
tinker9
Tinker9: Next Generation of Tinker with GPU Support
Stars: ✭ 31 (-90.06%)
Mutual labels:  molecular-dynamics, force-fields
pylj
Teaching Utility for Classical Atomistic Simulation.
Stars: ✭ 23 (-92.63%)
Mutual labels:  molecular-dynamics, computational-chemistry
MDBenchmark
Quickly generate, start and analyze benchmarks for molecular dynamics simulations.
Stars: ✭ 64 (-79.49%)
Mutual labels:  molecular-dynamics, computational-chemistry
isicle
In silico chemical library engine for high-accuracy chemical property prediction
Stars: ✭ 31 (-90.06%)
Mutual labels:  molecular-dynamics, computational-chemistry
tinker
Tinker: Software Tools for Molecular Design
Stars: ✭ 79 (-74.68%)
Mutual labels:  molecular-dynamics, force-fields
MolDQN-pytorch
A PyTorch Implementation of "Optimization of Molecules via Deep Reinforcement Learning".
Stars: ✭ 58 (-81.41%)
Mutual labels:  drug-discovery, materials-science
openmm-tutorials
Quickstart Python tutorials helping molecular dynamics practitioners get up to speed with OpenMM
Stars: ✭ 37 (-88.14%)
Mutual labels:  molecular-dynamics
masci-tools
Tools, utility, parsers useful in daily material science work
Stars: ✭ 18 (-94.23%)
Mutual labels:  materials-science
awesome-molecular-dynamics
😎 A curated list of awesome Molecular Dynamics libraries, tools and software.
Stars: ✭ 76 (-75.64%)
Mutual labels:  molecular-dynamics
stda
stda program for computing excited states and response functions via simplified TD-DFT methods (sTDA, sTD-DFT, and SF-sTD-DFT)
Stars: ✭ 23 (-92.63%)
Mutual labels:  computational-chemistry
senpai
Molecular dynamics simulation software
Stars: ✭ 124 (-60.26%)
Mutual labels:  molecular-dynamics
pinot
Probabilistic Inference for NOvel Therapeutics
Stars: ✭ 15 (-95.19%)
Mutual labels:  drug-discovery

NequIP

NequIP is an open-source code for building E(3)-equivariant interatomic potentials.

Documentation Status

nequip

PLEASE NOTE: the NequIP code is under active development and is still in beta versions 0.x.x. In general changes to the patch version (the third number) indicate backward compatible beta releases, but please be aware that file formats and APIs may change. Bug reports are also welcomed in the GitHub issues!

Installation

NequIP requires:

  • Python >= 3.7
  • PyTorch >= 1.8, !=1.9, <=1.11.*. PyTorch can be installed following the instructions from their documentation. Note that neither torchvision nor torchaudio, included in the default install command, are needed for NequIP.

To install:

  • We use Weights&Biases to keep track of experiments. This is not a strict requirement — you can use our package without it — but it may make your life easier. If you want to use it, create an account here and install the Python package:

    pip install wandb
    
  • Install NequIP

    NequIP can be installed from PyPI:

    pip install nequip
    

    or directly from source:

    git clone https://github.com/mir-group/nequip.git
    cd nequip
    pip install . 
    

Installation Issues

The easiest way to check if your installation is working is to train a toy model:

$ nequip-train configs/minimal.yaml

If you suspect something is wrong, encounter errors, or just want to confirm that everything is in working order, you can also run the unit tests:

pip install pytest
pytest tests/unit/

To run the full tests, including a set of longer/more intensive integration tests, run:

pytest tests/

If a GPU is present, the unit tests will use it.

Tutorial

The best way to learn how to use NequIP is through the Colab Tutorial. This will run entirely on Google's cloud virtual machine; you do not need to install or run anything locally.

Usage

! PLEASE NOTE: the first few calls to a NequIP model can be painfully slow. This is expected behaviour as the profile-guided optimization of TorchScript models takes a number of calls to warm up before optimizing the model. (The nequip-benchmark script accounts for this.)

Basic network training

To train a network, you run nequip-train with a YAML config file that describes your data set, model hyperparameters, and training options.

$ nequip-train configs/example.yaml

A number of example configuration files are provided:

  • configs/minimal.yaml: A minimal example of training a toy model on force data.
  • configs/minimal_eng.yaml: The same, but for a toy model that predicts and trains on only energy labels.
  • configs/example.yaml: Training a more realistic model on forces and energies. Start here for real models!
  • configs/full.yaml: A complete configuration file containing all available options along with documenting comments. This file is for reference, example.yaml is the right starting point for a project.

Training runs can also be restarted by running the same nequip-train command if the append: True option is specified in the original YAML. (Otherwise, a new training run with a different name can be started from the loaded state of the previous run.)

All nequip-* commands accept the --help option to show their call signatures and options.

Evaluating trained models (and their error)

The nequip-evaluate command can be used to evaluate a trained model on a specified dataset, optionally computing error metrics or writing the results to an XYZ file for further processing.

The simplest command is:

$ nequip-evaluate --train-dir /path/to/training/session/

which will evaluate the original training error metrics over any part of the original dataset not used in the training or validation sets.

For more details on this command, please run nequip-evaluate --help.

Deploying models

The nequip-deploy command is used to deploy the result of a training session into a model that can be stored and used for inference. It compiles a NequIP model trained in Python to TorchScript. The result is an optimized model file that has no dependency on the nequip Python library, or even on Python itself:

nequip-deploy build --train-dir path/to/training/session/ where/to/put/deployed_model.pth

For more details on this command, please run nequip-deploy --help.

Using models in Python

An ASE calculator is also provided in nequip.dynamics.

LAMMPS Integration

NequIP is integrated with the popular Molecular Dynamics code LAMMPS which allows for MD simulations over large time- and length-scales and gives users access to the full suite of LAMMPS features.

The interface is implemented as pair_style nequip. Using it requires two simple steps:

  1. Deploy a trained NequIP model, as discussed above.
nequip-deploy build path/to/training/session/ path/to/deployed.pth

The result is an optimized model file that has no Python dependency and can be used by standalone C++ programs such as LAMMPS.

  1. Change the LAMMPS input file to the nequip pair_style and point it to the deployed NequIP model:
pair_style	nequip
pair_coeff	* * deployed.pth <NequIP type for LAMMPS type 1> <NequIP type for LAMMPS type 2> ...

For installation instructions, please see the pair_nequip repository.

References & citing

The theory behind NequIP is described in our preprint (1). NequIP's backend builds on e3nn, a general framework for building E(3)-equivariant neural networks (2). If you use this repository in your work, please consider citing NequIP (1) and e3nn (3):

  1. https://www.nature.com/articles/s41467-022-29939-5
  2. https://e3nn.org
  3. https://doi.org/10.5281/zenodo.3724963

Authors

NequIP is being developed by:

  • Simon Batzner
  • Albert Musaelian
  • Lixin Sun
  • Anders Johansson
  • Mario Geiger
  • Tess Smidt

under the guidance of Boris Kozinsky at Harvard.

Contact, questions, and contributing

If you have questions, please don't hesitate to reach out at batzner[at]g[dot]harvard[dot]edu.

If you find a bug or have a proposal for a feature, please post it in the Issues. If you have a question, topic, or issue that isn't obviously one of those, try our GitHub Discussions.

If you want to contribute to the code, please read CONTRIBUTING.md.

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].