mir-group/pair_nequip_allegro

중요

이러한 pair 스타일은 2025년 9월 10일 LAMMPS 릴리스 또는 그 이후 버전을 요구합니다. 또한, LAMMPS KOKKOS 패키지는 기본 더블-더블 정밀도(double-double precision) 모드로 컴파일되어야 합니다.

이 pair 스타일들은 NequIP 프레임워크의 모델을 LAMMPS 시뮬레이션에서 사용할 수 있게 해줍니다. 이 저장소는 두 가지 pair 스타일을 제공합니다: pair_nequip은 단일 MPI 랭크로 제한되는 NequIP 메시지 전달 GNN 모델용이며, pair_allegro는 병렬 실행과 LAMMPS에서의 MPI를 지원하는 엄격하게 로컬한 Allegro 모델용입니다.

중요

nequip 프레임워크에 대한 주요하고 하위 호환성이 깨지는 업데이트가 2025년 4월 23일에 버전 v0.7.0으로 출시되었으며, 여기에는 업데이트된 pair 스타일이 포함되어 있습니다. 이전 모델과 함께 사용하기 위한 pair_allegro의 이전 버전은 이 저장소에서 버전 v0.6.0으로 찾을 수 있습니다. pair_nequip의 이전 버전은 pair_nequip 저장소에서 버전 v0.6.0으로 찾을 수 있습니다.

LAMMPS에서 모델을 사용하기 전에, 반드시 nequip-compile을 사용하여 컴파일해야 합니다. 더 자세한 정보는 NequIP 프레임워크 문서를 참조하십시오. nequip-compile의 출력물은 각각 TorchScript 및 AOTI 컴파일러를 위한 .nequip.pth 또는 .nequip.pt2 파일이어야 합니다.

LAMMPS 스크립트에서, NequIP 모델용으로 먼저 pair 스타일을 정의하고

pair_style nequip

그리고 Allegro 모델용으로 다음을 정의합니다.

pair_style allegro

그런 다음 다음을 사용하여 사용할 모델 파일을 지정합니다.

pair_coeff * * my-compiled-model.nequip.pth/pt2 <LAMMPS 타입 1에 대한 모델 유형 이름> <LAMMPS 타입 2에 대한 모델 유형 이름> ...

여기서 my-compiled-model.nequip.pth/pt2는 nequip-compile의 출력물인 학습되고 컴파일된 모델의 파일 이름입니다.

모델 파일 이름 뒤에 오는 이름들은 순서대로 LAMMPS의 원자 유형 1, 2 등에 사용될 모델의 원자 유형 이름을 나타냅니다. 제공되는 이름의 개수는 LAMMPS 설정 파일에 있는 원자 유형의 개수와 같아야 합니다 (NequIP/Allegro 모델의 원자 유형 개수가 아님!).
제공된 이름들은 type_names 옵션( training_module.model 아래)에서 훈련 YAML 파일에 지정된 모델의 유형 이름과 일치해야 합니다. 일반적으로 이는 각 LAMMPS 유형의 화학 기호가 됩니다.

Kokkos로 실행하려면 (Allegro 모델에서만 지원), LAMMPS Kokkos 문서를 참조하십시오. 예시:

mpirun -np 8 lmp -sf kk -k on g 4 -pk kokkos newton on neigh half -in in.script

이는 2개의 노드에 각각 4개의 GPU로 실행하는 명령어입니다.

git clone --depth=1 https://github.com/lammps/lammps

또는 선호하는 방법으로 사용하십시오 (--depth=1은 LAMMPS 저장소의 전체 기록을 다운로드하는 것을 방지합니다).

git clone --depth=1 https://github.com/mir-group/pair_nequip_allegro

또는 소스 ZIP 파일을 다운로드하여 사용하십시오.

pair_nequip_allegro 디렉토리에서 다음을 실행합니다:

./patch_lammps.sh /path/to/lammps/

LAMMPS를 CMake로 빌드하는 일반적인 정보는 LAMMPS 문서를 참조하십시오.

LAMMPS 소스 디렉토리에서는 다음과 같은 작업을 수행하게 됩니다:

cd lammps
mkdir build
cd build
...

다음 하위 섹션들은 pair_nequip_allegro에 특화된 옵션들을 논의합니다. 아래 섹션들을 다시 방문하면서 LAMMPS를 여러 번 구성하고 빌드해야 할 수도 있습니다.

PyTorch 2 Ahead-of-Time Inductor (AOTI) 컴파일을 사용하려면(본 논문에서 설명), 최소 PyTorch 2.6.0 (및/또는 해당 libtorch)를 사용해야 하며 추가적인 컴파일 시간 플래그를 구성해야 합니다:

-DNEQUIP_AOT_COMPILE=ON

다음 내용을 CMake 출력에서 확인하여 확인하십시오:

-- << NEQUIP flags >>
-- NEQUIP_AOT_COMPILE is enabled/disabled.

이러한 단계들은 AOTI 컴파일 모델(.nequip.pt2를 가진 모델)로 페어 스타일을 실행하는 데 필수적입니다.

확장(extension)을 가지고 있다면).

Python 환경에 PyTorch가 설치되어 있는 경우:

-DCMAKE_PREFIX_PATH=python -c 'import torch;print(torch.utils.cmake_prefix_path)'``

PyTorch가 설치되어 있지 않고 AOTI를 사용하지 않을 예정이라면, PyTorch 다운로드 페이지에서 libtorch를 다운로드할 수 있습니다. 다운로드한 파일을 압축 해제한 다음 LAMMPS를 구성합니다:

-DCMAKE_PREFIX_PATH=/path/to/unzipped/libtorch

PyTorch가 설치되어 있는 경우, 다음 명령을 실행합니다:

python -c "import torch; print(torch._C._GLIBCXX_USE_CXX11_ABI)"

만약 True를 반환하면,

-DCMAKE_PREFIX_PATH=python -c 'import torch;print(torch.utils.cmake_prefix_path)'``을 사용하고,

만약 False를 반환하면, 먼저 PyTorch 다운로드 페이지에서 libtorch를 사용해 보십시오. 반드시 cxx11 abi 버전을 다운로드해야 합니다. 다운로드한 파일을 압축 해제하고 다음을 사용합니다:

-DCMAKE_PREFIX_PATH=/path/to/unzipped/libtorch

AOTI 컴파일을 사용하는 경우, 사전 빌드된 libtorch가 작동하지 않을 수 있습니다. 이 경우, ABI11 플래그를 사용하여 새 Python 환경에서 PyTorch 전체를 설치하고 빌드해 보십시오. 그런 다음 해당 Python 환경만을 사용하여 nequip-compile을 실행하고 LAMMPS를 다음과 같이 빌드합니다:

-DCMAKE_PREFIX_PATH=python -c 'import torch;print(torch.utils.cmake_prefix_path)'``

이 새 Python 환경에서 상단의 명령은 True를 반환해야 합니다.

PyTorch의 CMake는 이유 없이 자동으로 MKL을 찾습니다. 만약 찾지 못한다면 (MKL_INCLUDE_DIR가 발견되지 않으면), 기존 경로로 설정할 수 있습니다. 예를 들어:

-DMKL_INCLUDE_DIR=/tmp

CMake는 CUDA와 cuDNN을 찾습니다. 사용자의 CUDA 설치 경로를 명시적으로 제공해야 할 수도 있습니다 (예: -DCUDA_TOOLKIT_ROOT_DIR=/usr/lib/cuda/).

conda로 설치된 PyTorch에 포함된 CUDA는 다음 사항에 유의하십시오.

불충분할 수 있으며, 전체 CUDA를 별도로 설치해야 할 수도 있습니다. 사용 가능한 CUDA 버전과 PyTorch의 CUDA 버전 간에 사소한 버전 불일치는 일반적으로 문제가 아닙니다. 시스템 CUDA의 마이너 버전이 같거나 더 최신인 한도 내에서 그렇습니다. cuDNN 역시 PyTorch에 의해 필요합니다.

pair_allegro

은 Kokkos를 사용하여 GPU 상에서 페어 스타일(pair style)을 가속화하고 호스트-GPU 전송을 피하는 것을 지원합니다.
pair_allegro

은 Kokkos에 대해 두 가지 설정을 지원합니다: pair_style과 model 모두 CPU에서 실행하거나, 둘 다 GPU에서 실행하는 방식입니다. 사용 사례에 맞게 적절한 Kokkos 백엔드가 활성화되도록 LAMMPS를 빌드했는지 확인하십시오. 예를 들어, CUDA GPU를 사용하려면 cmake 명령어에 다음을 추가하십시오:

-DPKG_KOKKOS=ON -DKokkos_ENABLE_CUDA=ON

더 많은 빌드 옵션과 Kokkos를 사용하여 LAMMPS를 올바르게 실행하는 방법은 LAMMPS 문서를 참조하십시오.

Kokkos 지원은 현재 pair_style allegro에 대해서만 가능합니다.

pair_allegro

은 OpenMP 사용을 통해 페어 스타일의 특정 부분을 가속화하는 것을 지원하며, 이때 OMP_NUM_THREADS를 설정하고 LAMMPS OpenMP 패키지를 사용합니다.
OpenMP와 Kokkos는 상호 배타적입니다.

OpenMP는 pair_style nequip과 pair_style allegro 모두를 지원합니다.

make -j$(nproc)

이 명령어는 실행 파일 lammps/build/lmp를 생성하며, 이는 평소처럼 /path/to/lmp -in in.script로 실행할 수 있습니다. 더 자세한 내용은 LAMMPS 문서를 참고하십시오.

본 소프트웨어의 전체 또는 일부 사용은 이 저장소를 명확하게 언급하고 링크해야 합니다.

관련 인용을 위해서는 nequip 및 allegro 저장소를 참조하십시오.

질문: 제 시뮬레이션이 즉시 또는 이상하게 불안정합니다.
답변: pair_coeff 라인에 지정된 LAMMPS 원자 유형에서 NequIP 프레임워크 원자 유형으로의 매핑이 올바른지, 그리고 훈련 데이터와 LAMMPS 시뮬레이션 간 단위가 일관적인지 확인하십시오.
질문: 다음과 같은 오류가 발생합니다:

instance of 'c10::Error' what(): PytorchStreamReader failed locating file constants.pkl: file not found

A: TorchScript를 사용하려는 의도가 맞는지, 그리고 nequip-compile을 사용하여 모델을 TorchScript로 올바르게 컴파일했는지 확인하세요.

버그를 발견했거나 기능 제안이 있다면 Issues에 게시해 주세요. 자체적으로 해결 가능한 질문이나 다른 토론 주제가 있다면 GitHub Discussions를 이용해 보세요.

만약 게시글이 NequIP 소프트웨어 프레임워크 전반 또는 allegro 확장 패키지와 관련되어 있다면, 해당 저장소의 issues나 discussions에 게시해 주십시오. 이 저장소에서의 논의는 pair 스타일과 구체적으로 관련된 내용이어야 합니다.

활성 사용자 및 관심 있는 개발자분들은 훌륭한 Zulip 소프트웨어에서 호스팅되는 NequIP 커뮤니티 채팅 서버에 참여하시기 바랍니다. Zulip은 Slack이나 Discord와 같은 다른 채팅 소프트웨어와는 조금 다르게 구성되어 있으므로, 게시하기 전에 소개를 검토해 주십시오. 여기에서 NequIP 커뮤니티 관심사 양식을 작성해 주세요.

또한 [email protected] 이메일로 연락할 수도 있습니다.