Inelastic Neutron Scattering Prediction for Instantaneous Results and Experimental Design (INSPIRED)

Introduction:

INSPIRED is a PyQt GUI that performs rapid prediction/calculation/visualization of inelastic neutron scattering (INS) spectra from a given structural model. This can be done in three different ways, each with its advantages and limitations:

1. Direct prediction from a symmetry-aware neural network

• Pros: any structure, minimum parameter setting, very fast (seconds)

• Cons: powder samples only, predefined Q and E ranges, less accurate, accuracy varies significantly from case to case

  

2. INS simulation based on existing DFT-calculated forces

• Pros: both powder and single crystal samples, more accurate

• Cons: only for crystals with DFT results found in the database (or provided by the users)

  

3. INS simulation using pre-trained universal machine learning force fields

• Pros: any structure, both powder and single crystal samples

• Cons: can be slow for large or low-symmetry systems, accuracy varies significantly from case to case

  

Installation:

INSPIRED is available on the Analysis cluster as a conda environment. To run INSPIRED, all you need to do is to activate "inspired-dev" in the global conda environment:

source /opt/anaconda/etc/profile.d/conda.sh

conda activate inspired-dev

inspired

To use INSPIRED on another computer, there are two installation options. One option is to download a pre-installed VirtualBox image and run INSPIRED as a virtual machine (VM) on any platform, including Windows, MacOS, and Linux (Option 1). If you have acess to a Linux machine and would like to have a native installation, you may also do so (Option 2).

Option 1

1. Install VirtualBox for your operating system. Unfortunately, VirtualBox does not support Apple M3 chips. There was a developer preview from an older version of VirtualBox that may support M1/M2 chips, but we did not test it. We are working on a solution to address this issue.

2. Download the VirtualBox appliance file (inspired_vm.ova) from Zenodo. The file is over 6GB, and it may take a while to download (depending on the speed of the internet). On MacOS/Linux, you may download by command line:

   wget https://zenodo.org/records/11478889/files/inspired_vm.ova

3. Start VirtualBox, import the inspired_vm.ova file as an appliance.

4. Run the “inspired_vm” VM. If prompted, use "inspired" for both user ID and password for authentication.

5. Set up the "shared folder" to access (read and write) files on your host computer. Click "Devices->Shared Folders->Shared folders settings" on the VM menu. Click the "add new shared folder" icon to the right. In "Folder Path", find the folder on your host computer you would like the guest VM to have access to. "Folder Name" is a label for this folder and can be anything you want (we use inspired_cwd as an example). "Mount point" is the path in the VM where the shared folder will be mounted (e.g., /home/inspired/cwd). Note that both "Folder Name" and "Mount point" must be consistent with the arguments used in the "sudo mount" command line in Step 6. You may check "Auto-mount" and "Make permanent" so you can skip this step in the future as long as you keep using this folder to share files between your host computer and the VM.

   

6. After finishing the setup, open a terminal in the VM (click the icon at the bottom left corner, "System Tools->QTerminal"), run (use "inspired" as password if prompted for authentication):

   sudo mount -t vboxsf -o rw,uid=1000,gid=1000 inspired_cwd /home/inspired/cwd

   

   To automatically run this command in the future when you start the VM, you may add it to the crontab file by running:

   crontab -e

   If asked to choose an editor and you are not sure, select nano. Add the following line to the end of the crontab file:

   @reboot echo "inspired" | sudo -S mount -t vboxsf -o rw,uid=1000,gid=1000 inspired_cwd /home/inspired/cwd

   Press Ctrl+S to save and Ctrl+X to exit (if using nano). This folder will now be automatically mounted when you run the VM on this computer.

7. Go to the shared folder (create a subfolder if needed) and run:

   inspired

Note: The VM desktop resolution can be changed at "Preferences->LXQt Settings->Monitor settings" within the VM. The VM window size can be changed on the VirtualBox menu (under View).

Option 2

1. Install Anaconda or Miniconda for Linux if it is not already installed.

2. Go to a location where you would like to install the program (e.g., $HOME/software), run:

   git clone https://github.com/neutrons/inspired.git

   After the download, you should see a folder named “inspired”. Go to the folder by running:

   cd inspired

   (Note: to get updated code in the future, you can simply run “git pull” in this folder)

3. With conda initiated, run the following commands in the project's root directory (inspired):

   .. code-block:: shell

   //Next, create the conda environment and activate

   conda env create

   conda activate inspired-dev

   //Then, install inspired in editable mode

   pip install -e .

4. To download the latest DFT database and ML models from Zenodo and extract the files, go to (create) a folder where you want to keep these files, run:

   wget https://zenodo.org/records/11478889/files/dftdb.tar.gz

   wget https://zenodo.org/records/10723108/files/model.tar.gz

   tar zxvf dftdb.tar.gz

   tar zxvf model.tar.gz

5. If all packages are installed successfully, you may now go to a working directory of your choice and start INSPIRED by running:

   inspired

   when you run the program for the first time, it may ask you to specify the paths to the DFT database and ML models. Set them to where you downloaded/extracted the files, and the main user interface should pop up.

Package Versions

The code related to already published work can be accessed (v0.2.0): git clone -b v0.2.0 https://github.com/neutrons/inspired.git

Additional notes:

When using INSPIRED, it is important to ensure the "Current Working Directory" (CWD) is correctly set, as this is where the program reads/writes all its input/output files. The default CWD is where you started INSPIRED, and once this program is running, you can change it in the Menu. It is strongly recommended that a new folder be created for each project to avoid mixed input/output files and potential errors. If you prefer not to change the working directory, then please make sure to run through all steps in each calculation (do not skip steps) to avoid accidently picking up input files from a previous calculation.

There is a "Help" button at the bottom right corner of each window. Click on the button for instructions.

Finally, but very importantly, INSPIRED is a GUI that provides streamlined access to various resources for users to obtain simulated INS spectra easily and quickly from a structure model. Many of the tools included in INSPIRED are under active development by their developers, such as the MLFFs. With growing computing power, larger training datasets, and more sophisticated models, the scope of the data and the accuracy of the models will keep improving. While we will try to keep the models included in INSPIRED up to date, we do not and cannot guarantee the accuracy of the results. Please check the references (1,8-12) for more details about these tools and their limitations. User discretion is extremely important while using INSPIRED, and please check the results carefully before using them for your analyses. Note that in some cases, even though the calculated phonon dispersion from the MLFFs appears fine, there could be a systematic softening (or, less likely, hardening) of the modes. Here are some additional resources on the benchmark of the MLFFs:

https://matbench-discovery.materialsproject.org/

https://arxiv.org/abs/2405.07105

Contact:

If you have any questions, please contact YQ Cheng at [email protected] for help.

Citation:

Bowen Han, Andrei T. Savici, Mingda Li, Yongqiang Cheng, INSPIRED: Inelastic Neutron Scattering Prediction for Instantaneous Results and Experimental Design, Computer Physics Communications, 304, 109288 (2024).

References:

1. Cheng, Y.; Wu, G.; Pajerowski, D. M.; Stone, M. B.; Savici, A. T.; Li, M.; Ramirez-Cuesta, A. J., Direct prediction of inelastic neutron scattering spectra from the crystal structure. Machine Learning: Science and Technology 2023, 4 (1), 015010.
2. Cheng, Y.; Stone, M. B.; Ramirez-Cuesta, A. J., A database of synthetic inelastic neutron scattering spectra from molecules and crystals. Scientific Data 2023, 10 (1), 54.
3. Chen, Z.; Andrejevic, N.; Smidt, T.; Ding, Z.; Xu, Q.; Chi, Y.-T.; Nguyen, Q. T.; Alatas, A.; Kong, J.; Li, M., Direct Prediction of Phonon Density of States With Euclidean Neural Networks. Advanced Science 2021, 8 (12), 2004214.
4. Togo, A. http://phonondb.mtl.kyoto-u.ac.jp/. (accessed 08/30/2022).
5. Togo, A.; Tanaka, I., First principles phonon calculations in materials science. Scripta Materialia 2015, 108, 1-5.
6. Cheng, Y.; Daemen, L.; Kolesnikov, A.; Ramirez-Cuesta, A., Simulation of inelastic neutron scattering spectra using OCLIMAX. Journal of chemical theory and computation 2019, 15 (3), 1974-1982.
7. Hjorth Larsen, A.; Jørgen Mortensen, J.; Blomqvist, J.; Castelli, I. E.; Christensen, R.; Dułak, M.; Friis, J.; Groves, M. N.; Hammer, B.; Hargus, C.; Hermes, E. D.; Jennings, P. C.; Bjerre Jensen, P.; Kermode, J.; Kitchin, J. R.; Leonhard Kolsbjerg, E.; Kubal, J.; Kaasbjerg, K.; Lysgaard, S.; Bergmann Maronsson, J.; Maxson, T.; Olsen, T.; Pastewka, L.; Peterson, A.; Rostgaard, C.; Schiøtz, J.; Schütt, O.; Strange, M.; Thygesen, K. S.; Vegge, T.; Vilhelmsen, L.; Walter, M.; Zeng, Z.; Jacobsen, K. W., The atomic simulation environment—a Python library for working with atoms. Journal of Physics: Condensed Matter 2017, 29 (27), 273002.
8. Batatia, I.; Kovacs, D. P.; Simm, G.; Ortner, C.; Csányi, G., MACE: Higher order equivariant message passing neural networks for fast and accurate force fields. Advances in Neural Information Processing Systems 2022, 35, 11423-11436.
9. Batatia, I.; Batzner, S.; Kovács, D. P.; Musaelian, A.; Simm, G. N.; Drautz, R.; Ortner, C.; Kozinsky, B.; Csányi, G., The design space of E (3)-equivariant atom-centered interatomic potentials. arXiv preprint arXiv:2205.06643 2022.
10. Batatia, I.; Benner, P.; Chiang, Y.; Elena, A. M.; Kovács, D. P.; Riebesell, J.; Advincula, X. R.; Asta, M.; Baldwin, W. J.; Bernstein, N., A foundation model for atomistic materials chemistry. arXiv preprint arXiv:2401.00096 2023.
11. Deng, B.; Zhong, P.; Jun, K.; Riebesell, J.; Han, K.; Bartel, C. J.; Ceder, G., CHGNet as a pretrained universal neural network potential for charge-informed atomistic modelling. Nature Machine Intelligence 2023, 5 (9), 1031-1041.
12. Chen, C.; Ong, S. P., A universal graph deep learning interatomic potential for the periodic table. Nature Computational Science 2022, 2 (11), 718-728.
13. Hinuma, Y.; Pizzi, G.; Kumagai, Y.; Oba, F.; Tanaka, I., Band structure diagram paths based on crystallography. Comp. Mat. Sci. 2017, 128, 140.
14. Togo, A.; Tanaka, I., Spglib: a software library for crystal symmetry search. 2018, arXiv:1808.01590
15. Geiger, M.; Smidt, T., e3nn: Euclidean neural networks. 2022, doi:10.48550/ARXIV.2207.09453.
16. Geiger, M.; et al., Euclidean neural networks: e3nn. 2022, doi:10.5281/zenodo.6459381.