kpleo/pyraimd

Pyramid이란 무엇인가?

Pyramid(Python 래핑 ab initio 분자 역학)은 제일 원리 양자 역학(DFT 등)과 빠른 기계 학습 포텐셜(MLIP)을 결합하여 분자 역학(MD) 시뮬레이션을 실행하는 Python 프레임워크입니다. 비용이 많이 드는 참조 계산(예: Quantum ESPRESSO)을 언제 호출하고 빠른 대리 모델(예: MACE)을 언제 사용할지 조정하며, 힘 오차 방법을 사용하여 정확도가 필요한 시점을 결정합니다.

핵심 아이디어

• 참조 엔진(예: QE, PySCF)은 정확한 에너지와 힘을 제공합니다.
• 대리 포텐셜(예: MACE)은 빠르지만 근사적입니다.
• Pyramid의 힘 오차 방법은 알려진 구조에서 멀어질수록 힘 오차가 어떻게 증가하는지 예측하고 에너지 영향(부호 있는 잔여 일)을 측정합니다. 이는 참조 계산을 언제 실행할지 안내합니다.

설치

• Python 3.12+가 필요합니다.
• 핵심 설치에는 NumPy와 ASE만 필요합니다(무거운 종속성 없음).
• 소스에서 설치: pip install . 또는 pip install -e '.[dev]'.
• 선택적 백엔드: pip install '.[pyscf]'(분자 참조), pip install '.[mace]'(MACE 대리).
• Python 임포트는 pyraimd2이고, CLI는 pyramid입니다.

주요 기능

• 적응형 MD: 참조 엔진을 언제 호출할지 실시간으로 결정합니다.
• 다중 시간 스텝(MTS): 실험적 고정 일정 방식으로, 외부 스텝마다 참조를 한 번 평가합니다.
• 검증 레이어: 세 가지 수준(구성 검사, 환경 검사, 백엔드 프로브)으로 실행 전에 문제를 발견합니다.
• 체크포인트/재개: 안전한 중지(Ctrl-C) 및 재개, 이벤트 로그 재생 및 ID 검사 포함.
• 비교 도구: pyramid compare로 완료된 두 실행을 오프라인 비교합니다.
• 플러그인: 엔트리 포인트를 통해 자체 ASE 계산기 또는 백엔드 패키지를 추가할 수 있습니다.
• 스크래치 관리: 솔버 스크래치 파일을 위한 선택적 통합 tmp 루트.
• 영구 밀도 유지: 밀도 생성의 읽기 전용 검사.

일반적인 워크플로우

1. 초기화: pyramid init --template harmonic --output my_run(또는 다른 템플릿).
2. 검증: pyramid validate run.toml(구성), --check-environment(사전 요구 사항), --probe-backends(계산).
3. 실행: pyramid run run.toml.
4. 검사/재개/내보내기: pyramid inspect, pyramid resume, pyramid export.

현재 범위

• 작업: 단일 지점, 완화(FIRE/BFGS), MD(NVE, NVT)로 참조 전용, 대리 전용 또는 적응형 모드.
• 동역학: FixAtoms가 있는 고정 셀 NVE 및 NVT(Langevin). 가변 셀 또는 기타 제약 조건은 없습니다.
• 백엔드: QE, PySCF, MACE, 해석적 조화, 그리고 일반 ASE 어댑터.
• 에너지 일관성: 힘은 보고된 에너지의 음의 기울기여야 합니다. 이종 조합이 검사됩니다.
• 예제: 오프라인 데모(조화, Lennard-Jones, QE+MACE 스켈레톤) 및 실제 재료 예제(Si, Al 슬래브).

문서

• 사용자 가이드: docs/user_guide.md
• 구성 참조: docs/configuration.md
• 아키텍처: docs/architecture.md
• API: docs/api.md

참고 사항

• README는 예제 매개변수가 데모용이며 정확도 권장 사항이 아님을 강조합니다.
• 온라인 모델 업데이트는 Python API를 통해서만 사용할 수 있으며 TOML 구성에서는 사용할 수 없습니다.
• 프로젝트 버전은 0.8.5입니다(README 기준).