Settings for using general-purpose graph neural network force fields¶
Open-source general-purpose graph neural network (GNN) force fields are developed in Python, and you need to set up and install the Python environment beforehand.
LAMMPS bundled with NanoLabo calls each force field package in the Python environment to execute calculations.
Setting up the Python environment¶
Install the software on the machine that will be used for the calculation (e.g. if you will plan to submit the job to a calculation server, the installation should be done on that server).
Preparing conda environment
Conda is utilized as the Python environment. If you are not already using conda, it is recommended to install Miniconda, which provides the minimum necessary recommended.
Download the Python 3.11 installer from the Miniconda page and proceed with its installation.
If you are using Windows and install Miniconda without altering the
PATHvariable, you should launch Anaconda Prompt from the Start menu and use it for subsequent procedure.If you need to use a proxy for internet connection, make sure to adjust the environment variable settings accordingly.
Example: Windows, without authentication¶set HTTP_PROXY=http://host:port set HTTPS_PROXY=http://host:port
Example: Linux, with authentication¶export HTTP_PROXY=http://user:pass@host:port export HTTPS_PROXY=http://user:pass@host:port
Creating and operating virtual environments
Due to the dependencies of force field packages, you may not be able to install multiple force field packages in the same Python environment. By creating virtual environments with conda, you can install force field packages in separate environments.
Create¶conda create -n (environment name) python=3.11You are not yet in the virtual environment at the time of creation.
Entering the virtual environment¶conda activate (environment name)The virtual environment name is displayed before the prompt. By performing installation operations in this state, it will be installed within that virtual environment.
Exiting the virtual environment¶conda deactivateDelete¶conda remove -n (environment name) --allList¶conda env listWhen using GPUs
Each GNN force field is implemented using PyTorch, and calculations can be accelerated by using the GPU version of PyTorch.
If NVIDIA driver is not already installed on your system, ensure you install it beforehand.
The installation method when using GPUs may be specified in the documentation of each package. If not, install the GPU version of PyTorch before installing the force field package (in the same virtual environment as the force field package if you are using one). For the latest version, refer to Get Started. For older versions, refer to Previous Versions and execute the installation command that matches your CUDA version. The PyTorch version may be specified by the force field package, so please follow that.
After completing the installation, you can verify whether the GPU is available or not by checking in the Python interactive environment.
python >>> import torch >>> print(torch.cuda.is_available()) # Check GPU availability True >>> exit() # Exit Python environment
When using DFT-D3 correction
Please install the torch-dftd package (in the same virtual environment as the force field package if you are using one).
pip install torch-dftd
Installation of each force field package¶
Hint
Each package is continuously updated, and the installation procedures described on this page may not be the latest. If installation or execution is unsuccessful, please refer to the original installation instructions.
MatGL
Execute the following command (after entering the virtual environment if you are using one).
When using GPUs¶pip install torch==2.2.0 --index-url https://download.pytorch.org/whl/cu121 pip install dgl -f https://data.dgl.ai/wheels/torch-2.2/cu121/repo.html pip install dglgo
pip install matglCHGNet
Execute the following command (after entering the virtual environment if you are using one).
pip install chgnetMACE
Execute the following command (after entering the virtual environment if you are using one).
pip install mace-torchOrb
Execute the following command (after entering the virtual environment if you are using one).
pip install orb-modelsIt is recommended to install cuML (GPU usage) for simulations of large systems (5000 atoms or more in the case of periodic boundary conditions).
pip install --extra-index-url=https://pypi.nvidia.com "cuml-cu11==25.2.*" # For cuda versions >=11.4, <11.8 pip install --extra-index-url=https://pypi.nvidia.com "cuml-cu12==25.2.*" # For cuda versions >=12.0, <13.0
MatterSim
Execute the following command (after entering the virtual environment if you are using one).
pip install mattersimFAIR-Chem
Currently, NanoLabo does not support FAIRChem version 2. In the following steps, version 1.10.0 is specified for installation.
FAIR-Chem provides installation instructions that create a virtual environment from an environment file. Executing it will create a virtual environment named fair-chem.
When using GPUs¶conda create -n fair-chem python=3.11 conda activate fair-chem curl -O https://raw.githubusercontent.com/facebookresearch/fairchem/refs/tags/fairchem_core-1.10.0/packages/env.gpu.yml # Edit the pytorch-cuda version in the yml if you want to change the CUDA version conda env update -f env.gpu.yml pip install fairchem-core==1.10.0
When not using GPUs¶conda create -n fair-chem python=3.11 conda activate fair-chem curl -O https://raw.githubusercontent.com/facebookresearch/fairchem/refs/tags/fairchem_core-1.10.0/packages/env.cpu.yml conda env update -f env.cpu.yml pip install fairchem-core==1.10.0
Trained models from Open Materials (those with OMat in the model name) require the creation of a Hugging Face account and agreement to the terms of use. Please refer to fairchem/OMAT24. Place the downloaded checkpoint file in the
gnnp/fairchem-omat24folder in the NanoLabo installation directory.
Configuring NanoLabo¶
To run locally (on the machine running NanoLabo)
Set the path for the Python executable in from the
located in the upper left corner of the screen(or 
button in the Force Field setting screen).On Windows, the Python executable is located at the
conda installation destination\python.exe. For Linux or mac OS, it is located in theconda installation destination/bin/python.Also, if you installed in a virtual environment, set
conda installation path\envs\virtual environment name\python.exeon Windows, andconda installation path/envs/virtual environment name/bin/pythonon Linux/macOS.To run remotely (on calculation server etc.)
You need to add the Python environment’s lib folder to
LD_LIBRARY_PATH.The following folders are automatically added to the job script by NanoLabo. Note that the virtual environment name part will be replaced with the one according to the force field settings.
${HOME}/miniconda3/lib`${HOME}/anaconda3/lib${HOME}/miniconda3/envs/{m3gnet,matgl,chgnet,mace,orb,mattersim,fairchem}/lib${HOME}/anaconda3/envs/{m3gnet,matgl,chgnet,mace,orb,mattersim,fairchem}/lib
If Conda is installed in a different location, click the icon
located in the upper left corner, open , and then add the LD_LIBRARY_PATHto your job script.export LD_LIBRARY_PATH=(conda installation destination)/lib:$LD_LIBRARY_PATHWhen installed in a virtual environment¶export LD_LIBRARY_PATH=(conda installation destination)/envs/(environment name)/lib:$LD_LIBRARY_PATH
Importing model files¶
If you want to use a model that is not in the Model list box, such as a fine-tuned model or a model distributed by a third party, import the model file from the icon at the top left of the screen via . The imported model will be added to the Model list box and will be available for selection.
Troubleshooting¶
With MatGL, the following error may occur at runtime.
ValueError: No valid model found in pre-trained_models at https://github.com/materialsvirtuallab/matgl/raw/main/pretrained_models/.This message suggests that the required pretrained model data for execution is missing. Since the m3gnet package does not come with the model data, it attempts to download it during the initial run. However, if there is a problem with the internet connection, the download cannot proceed.
Alternatively, you can manually download the model data. In the matgl repository, there is a folder for each model name. Download the files for the model you want to use and save them in
(home directory)/.cache/matgl/(model name).
On Windows, you may encounter the following error during runtime.
OMP: Error #15: Initializing libiomp5md.dll, but found libiomp5md.dll already initialized.In this case, rename
(conda installation path)\Library\bin\libiomp5md.dlltolibiomp5md.dll_for example.
The following error may occur during runtime when DFT-D3 is enabled.
version `GOMP_5.0' not foundIf you encounter this issue, set the following environment variable.
export LD_PRELOAD=(conda installation destination)/lib/libgomp.so
When using a GPU on Windows, you may encounter certain errors that can prevent execution.
FileNotFoundError: Could not find module 'C:\Program Files\NVIDIA Corporation\NVSMI\nvml.dll' (or one of its dependencies). Try using the full path with constructor syntax.pynvml.NVMLError_LibraryNotFound: NVML Shared Library Not FoundIf you encounter such issues, try copying the file
C:\Windows\System32\nvml.dlltoC:\Program Files\NVIDIA Corporation\NVSMI\nvml.dll(if the folder doesn’t exist, create it first) and then execute the process again.
With pymatgen 2024.8.9 or later, the following error may occur at runtime.
ValueError: Buffer dtype mismatch, expected 'const int64_t' but got 'long'ValueError: Buffer dtype mismatch, expected 'const long' but got 'long long'In this case, downgrading the pymatgen version may resolve the issue.
pip install -U pymatgen==2024.7.18
The following error may occur at runtime.
torch._dynamo.exc.BackendCompilerFailedThis is an error from torch.compile(), which optimizes PyTorch models at runtime. While you can fix this by installing and configuring compilers based on the error message, it is also possible to work around it by setting the environment variable
TORCH_COMPILE_DISABLE=1.
Using LAMMPS directly¶
This guidance is for running LAMMPS in a standalone mode, not through NanoLabo.
Use the executable lammps_gnnp included with NanoLabo Tool.
MPI parallel computation is not supported. Some force fields do not support virial stress calculations (NPT/NPH ensembles, cell optimization).
Setting Environment Variables¶
Since Python dynamic libraries are used at runtime, set the environment variable LD_LIBRARY_PATH on Linux/macOS, or the environment variable PATH on Windows.
On Linux, OpenMPI dynamic libraries are required, so add their path to LD_LIBRARY_PATH as well.
$ export LD_LIBRARY_PATH=(conda installation destination)/envs/(environment name)/lib:(NanoLabo Tool installation destination)/exec.LINUX/mpi/lib:$LD_LIBRARY_PATH
> set PATH=(conda installation destination)/envs/(environment name);%PATH%
Additionally, on Linux, you should set the environment variable OPAL_PREFIX .
$ export OPAL_PREFIX=/opt/AdvanceSoft/NanoLabo/exec.LINUX/mpi
Since LAMMPS calls gnnp_driver.py during its operation, you need to add the gnnp folder, located in the NanoLabo Tool installation directory, to Python’s module search path. You can do this by adding it to the PYTHONPATH environment variable.
$ export PYTHONPATH=(NanoLabo Tool installation destination)/gnnp:$PYTHONPATH
Setting Input File¶
Set the unit system to
units metal.Set periodic boundary conditions in the X, Y, and Z directions.
Set the
pair_styleas follows.
pair_style gnnp
pair_coeff * * <gnnptype> <modelname> <element1 element2 ...> # Example specifying model name
pair_style gnnp/d3
pair_coeff * * <gnnptype> path <modelfile> <element1 element2 ...> # Example specifying model file
pair_style gnnp/gpu
pair_coeff * * <gnnptype> <modelname> <element1 element2 ...>
pair_style gnnp/d3/gpu
pair_coeff * * <gnnptype> <modelname> <element1 element2 ...>
Parameter
element
list the element names in the same order as the atom types used in LAMMPS
Name of the available pre-trained model
Available models may be added or removed due to updates of each force field. Please check the documentation or GitHub repository of each force field for the latest list.
*:sup Reads the model file located in
(folder where gnn_driver.py is)/mace-osaka24.** Reads the model file located in
folder where gnn_driver.py is/fairchem-omat24. Obtaining the file requires creating a Hugging Face account and agreeing to the terms of use. See fairchem/OMAT24.
Hint
The following error may appear at runtime.
Fatal Python error: init_fs_encoding: failed to get the Python codec of the filesystem encoding
Python runtime state: core initialized
ModuleNotFoundError: No module named 'encodings'
In this case, ensure that the environment variable PYTHONHOME is set correctly.
set PYTHONHOME=(conda installation destination)/envs/(environment name)