pymatgen은(는) 무엇을 하나요?
조성, 분자, 주기적 구조, 계산된 엔트리, 대칭, 상 다이어그램, 전자 구조 및 전자 구조 코드 파일 작업에 pymatgen을 사용하세요. 모든 파싱, 변환, 대칭 할당, 변환 및 데이터베이스 결과는 메서드 및 매개변수 종속적으로 처리하십시오.
MIT 프론트매터 라이선스는 이 스킬을 다룹니다. pymatgen과 pymatgen-core는 MIT이며, mp-api는 BSD-3-Clause-LBNL을 선언합니다. Materials Project 데이터는 일반적으로 CC BY 4.0이며, 기여 데이터는 기여자가 소유권을 유지합니다. 재배포 전에 정확한 아티팩트 및 데이터 조건을 확인하세요.
확인된 스냅샷 (2026-07-23)
pymatgen==2026.5.4는 최신 안정적인 래퍼 릴리스입니다 (2026-05-04). 패키지 메타데이터는 Python 3.11+이 필요하며,pymatgen-core>=2026.4.16을 직접 요구합니다.pymatgen-core==2026.7.16은 최신 안정적인 코어 릴리스입니다 (2026-07-16). 이제 기존pymatgen.*네임스페이스 아래에 코어 객체, 대칭/격자 연산 및 I/O 계층이 포함되어 있습니다.mp-api==0.46.4는 최신 안정적인 Materials Project 클라이언트입니다 (2026-06-15). Python 3.11+이 필요하며pymatgen>2024.2.20에 의존합니다.- 현재 API 사이트는 2026.7.16 코어 문서를 기반으로 구축되었습니다. 두 배포판을 고정하면
pymatgen==2026.5.4가 다른 미래 코어로 자동 해석되는 것을 방지합니다. - Pymatgen은 날짜 기반 버전을 사용합니다. PyPI는 날짜를 점으로 표시하며, 숫자에서 시맨틱 버전 호환성을 유추하지 마십시오.
재현성을 위해 프로젝트 잠금 파일을 생성하십시오:
uv init --python 3.11
uv add "pymatgen==2026.5.4" "pymatgen-core==2026.7.16" "mp-api==0.46.4"
uv lock
uv sync --frozen
일회성 검토 환경의 경우:
uv venv --python 3.11 .venv-pymatgen
uv pip install --python .venv-pymatgen/bin/python \
"pymatgen==2026.5.4" "pymatgen-core==2026.7.16" "mp-api==0.46.4"
직접 고정해도 모든 전이적 휠이 고정되지는 않습니다. uv.lock, 플랫폼, Python 버전, 패키지 버전 및 아티팩트 해시를 보존하십시오.
필수 워크플로우
- 객체가 비주기적인
Molecule인지 주기적인Structure인지 명시하고, 격자 및 주기 경계 조건을 기록하십시오. - 단위를 명시하십시오. Pymatgen은 일반적으로 Å, 도, eV, eV/원자, amu 및 g/cm³을 사용하지만, 각 API의 문서화된 계약이 우선합니다.
- 좌표 모드를 명시하십시오.
Structure좌표는coords_are_cartesian=True가 아닌 이상 분수 좌표이며,Molecule좌표는 데카르트 좌표입니다. - 모든 파서 경고를 검사하십시오. CIF의 경우 점유율, 사이트 병합, 화학량론 및 보정 경고를 보존하십시오. 수정 사항을 자동으로 수락하지 마십시오.
- 무질서/부분 점유율 및 산화수 장식을 보고하십시오. 산화수를 암시적으로 추측하지 마십시오.
- 대칭, 이웃, 변환, 변환 또는 열역학 분석 전에 검증을 실행하십시오.
- 대칭 공차를 스캔하고 모든 할당 시
symprec(Å) 및angle_tolerance(도)를 보고하십시오. - 변환을 새로운 아티팩트로 취급하십시오. 입력, 매개변수, 소프트웨어 버전, 경고 및 부모/자식 체크섬을 보존하십시오.
- 변환 전에 표현 손실을 식별하십시오. 새 경로에만 쓰고 과학적으로 관련된 속성을 왕복 검사하십시오.
- 호환 가능한 총 에너지 및 보정 체계로만 상 다이어그램을 작성하십시오. 계산된 hull은 제공된 엔트리 세트에 따라 조건부입니다.
- 모든 데이터베이스 접근은 기본적으로 비활성화하십시오. 명시적 실행 단계 전에 엔드포인트, 필터, 필드, 결과 제한, 캐시 동작, 출력, 라이선스 및 인용을 공개하십시오.
- 아티팩트 매니페스트를 보존하십시오. pickle을 사용하거나 신뢰할 수 없는 일반 객체 그래프를 로드하지 마십시오. 스키마 검증된 JSON 및 명시적 생성자를 사용하십시오.
핵심 객체
공개 편의 임포트를 사용하십시오:
from pymatgen.core import Composition, Element, Lattice, Molecule, Structure
composition = Composition("LiFePO4", strict=True)
iron = Element("Fe")
lattice = Lattice.cubic(5.64) # Å
structure = Structure(
lattice,
["Na", "Cl"],
[[0, 0, 0], [0.5, 0.5, 0.5]],
coords_are_cartesian=False,
validate_proximity=True,
)
molecule = Molecule(
["O", "H", "H"],
[[0.0, 0.0, 0.0], [0.758, 0.0, 0.504], [-0.758, 0.0, 0.504]],
charge=0,
spin_multiplicity=1,
)
Structure 및 Molecule은 가변적입니다. 변형이 출처를 손상시키는 경우 IStructure/IMolecule 또는 명시적 복사본을 사용하십시오. 핵심 클래스를 참조하십시오.
안전한 로컬 구조 입력
CIF 및 Python 경고를 캡처하고 단위, 점유율, 무질서, 산화수, 주기성, 좌표 모드 및 최소 거리를 보고하는 번들 검증기를 선호하십시오:
python scripts/composition_structure_validator.py composition "Fe2O3"
python scripts/composition_structure_validator.py structure structure.cif
python scripts/structure_analyzer.py structure.cif --symmetry
직접 CIF 작업의 경우 현재 파서 메서드를 사용하고 두 경고 채널을 모두 검사하십시오:
import warnings
from pymatgen.io.cif import CifParser
with warnings.catch_warnings(record=True) as caught:
warnings.simplefilter("always")
parser = CifParser("input.cif", check_cif=True)
structures = parser.parse_structures(
primitive=False,
check_occu=True,
on_error="raise",
)
parser_messages = list(parser.warnings)
python_messages = [str(item.message) for item in caught]
신뢰할 수 없는 파일을 권한 있는 프로세스에서 파싱하지 마십시오. pymatgen은 2024.2.8까지 치명적인 악성 CIF 코드 실행 결함이 있었으며 2024.2.20에서 수정되었습니다. 고정된 릴리스는 최신이지만, 파서는 여전히 공격자 제어 입력을 처리합니다. 격리 및 CPU/RAM/디스크/시간 제한을 사용하십시오.
대칭
공간 그룹 할당은 공차 및 구조 품질에 따라 달라집니다:
from pymatgen.symmetry.analyzer import SpacegroupAnalyzer
analyzer = SpacegroupAnalyzer(
structure,
symprec=0.01, # Å
angle_tolerance=5.0, # 도
)
symbol = analyzer.get_space_group_symbol()
number = analyzer.get_space_group_number()
Materials Project 파이프라인은 일반적으로 symprec=0.1 Å을 사용하는 반면, pymatgen의 문서화된 기본값은 0.01 Å입니다. 이들은 다른 할당을 생성할 수 있습니다. 선호하는 답이 나올 때까지 공차를 변경하는 대신 민감도 보고서를 생성하십시오:
python scripts/symmetry_sensitivity_report.py structure.cif \
--symprec 0.001,0.01,0.1 --angle-tolerance 1,5
분석 모듈을 참조하십시오.
변환 및 파서/라이터 I/O
먼저 계획을 세우십시오. 계획자는 파일을 열거나 pymatgen을 임포트하지 않습니다:
python scripts/io_conversion_plan.py \
--input input.cif --input-format cif \
--output POSCAR.new --output-format poscar \
--periodic --coordinate-mode direct
그런 다음 명시적인 손실 인정과 함께 새 경로로 변환하십시오:
python scripts/structure_converter.py input.cif POSCAR.new \
--output-format poscar --coordinate-mode direct --allow-lossy \
--acknowledge-parser-warnings
CIF, POSCAR, XYZ 및 JSON은 동일한 의미를 보존하지 않습니다. 모든 변환 후 격자, 주기성, 좌표 모드, 종 순서, 선택적 역학, 사이트 속성, 산화수, 레이블 및 무질서를 확인하십시오. I/O 형식을 참조하십시오.
변환 및 출처
복사본을 변환하고 이력을 보존하십시오:
from pymatgen.alchemy.materials import TransformedStructure
from pymatgen.transformations.standard_transformations import (
SubstitutionTransformation,
SupercellTransformation,
)
tracked = TransformedStructure(structure.copy(), [])
tracked.append_transformation(SupercellTransformation([2, 2, 2]))
tracked.append_transformation(SubstitutionTransformation({"Na": "K"}))
derived = tracked.final_structure
history = tracked.history
일대다 순서화, 도핑, 슬래브 및 자기 변환은 조합적으로 확장되거나 선택적 실행 파일을 호출할 수 있습니다. 후보, 사이트, 슈퍼셀 크기, 런타임 및 출력 수를 제한하십시오. 변환 및 워크플로우를 참조하십시오.
국소 상 다이어그램
번들 생성기는 오프라인이며 엔트리당 총 eV와 출처가 포함된 엄격한 JSON 스키마만 허용합니다:
{
"schema_version": "1.0",
"energy_unit": "eV",
"energy_basis": "total_per_entry",
"provenance": {
"source": "검토된 로컬 계산",
"method": "하나의 호환 가능한 에너지/보정 체계"
},
"entries": [
{
"entry_id": "local-Li",
"composition": "Li",
"energy_eV": -1.0,
"provenance": {"source": "계산 매니페스트 sha256:..."}
}
]
}
python scripts/phase_diagram_generator.py entries.json --analyze Li2O
원소 엔드포인트와 모든 경쟁 상이 존재해야 합니다. 다른 기능, 슈도퍼텐셜, 자기 상태 또는 보정 규칙의 원시 에너지를 혼합하지 마십시오. 계산된 on-hull 상태는 실험적 안정성이 아닙니다.
밴드 구조, DOS, VASP 및 Q-Chem
필요한 데이터만 파싱하십시오:
from pymatgen.io.vasp import Vasprun
run = Vasprun(
"vasprun.xml",
parse_dos=True,
parse_eigen=True,
parse_projected_eigen=False,
parse_potcar_file=False,
)
band_structure = run.get_band_structure(line_mode=True)
band_gap = band_structure.get_band_gap()
complete_dos = run.complete_dos
투영된 고유값은 극도의 메모리를 필요로 할 수 있습니다. 갭 또는 DOS를 해석하기 전에 수렴, k-경로, 스핀/SOC 설정, 페르미 준위 규칙, 스미어링 및 투영 기저를 확인하십시오. 파서 성공이 수렴된 계산을 의미하지는 않습니다.
현재 Q-Chem 인터페이스는 pymatgen.io.qchem.inputs.QCInput 및 pymatgen.io.qchem.outputs.QCOutput입니다:
from pymatgen.io.qchem.inputs import QCInput
job = QCInput(
molecule,
rem={"job_type": "sp", "method": "wb97x-v", "basis": "def2-svpd"},
)
text = str(job)
Pymatgen은 입력을 쓰고 출력을 파싱합니다. VASP 또는 Q-Chem 라이선스를 부여하거나 방법 유효성을 설정하지 않습니다. POTCAR 파일은 VASP 라이선스가 있으며 pymatgen에 의해 배포되지 않습니다. 이를 재배포하거나 관련 없는 디렉토리를 스캔하지 마십시오. enumlib, Bader, packmol, ffmpeg 및 Zeo++와 같은 선택적 도구는 네이티브/외부 실행 파일입니다. 별도의 명시적 호출 전에 출처, 라이선스, argv, 작업 디렉토리 및 리소스 제한을 검토하십시오.
Materials Project: 네트워크 전 계획
다음만 사용하십시오:
from mp_api.client import MPRester
클라이언트는 구성 시 MP_API_KEY를 읽습니다. 사용자의 셸 또는 비밀 관리자를 통해 해당 이름의 환경 변수만 제공하십시오. 키를 CLI 인수로 허용하거나, .env 파일을 탐색하거나, 환경 변수를 덤프하거나, 수정 없이 예외 데이터를 출력하지 마십시오.
건식 실행 계획이 기본입니다:
python scripts/mp_query.py \
--chemsys Li-Fe-O \
--energy-above-hull 0 0.05 \
--fields formula_pretty,energy_above_hull,band_gap,origins \
--limit 25
--execute만 제한된 요약 쿼리를 허용하며 새 출력이 필요합니다:
python scripts/mp_query.py \
--material-id mp-149 \
--fields formula_pretty,structure,origins,last_updated \
--limit 1 --output mp-149.json --execute
CLI는 num_chunks=1을 설정하고, 명시적 필드 및 필터를 요구하며, 결과를 제한하고, 암시적 결과 캐시를 구현하지 않으며, 출력을 덮어쓰지 않습니다. MPRester 초기화는 또한 호환성/하트비트 메타데이터 요청을 수행합니다. 계획은 이를 공개하고, 플랫폼 세부 정보 사용자 에이전트 및 로컬 데이터베이스 버전 알림 로그를 비활성화하며, 반환된 데이터베이스 버전을 기록합니다. 요약 워크플로우는 전체 데이터셋 캐시 다운로드를 요청하지 않습니다. mp-api 0.46.4는 자체 구성된 정책에 따라 HTTP 429/502/504를 재시도하고 Retry-After를 존중합니다. 숫자 서비스 할당량을 임의로 만들거나 무제한 재시도 루프를 추가하지 마십시오.
Materials Project 핵심 값은 계산된, 방법 종속적인 데이터입니다—실험적 진실이 아닙니다. PBE는 일반적으로 격자 매개변수를 과대평가하고 밴드 갭을 체계적으로 과소평가합니다. 집계된 값은 데이터베이스 릴리스에 따라 변경될 수 있습니다. 검색 시간, 쿼리, 필드, 재료/작업 출처, 데이터베이스 릴리스(가능한 경우), 클라이언트 버전, CC BY 저작자 표시 및 표준 및 속성별 인용을 보존하십시오. Materials Project API를 참조하십시오.
번들 CLI
모든 CLI는 종속성 없는 --help, 느린 과학적 임포트, 제한된 JSON 및 암시적 네트워크 없음을 갖습니다:
scripts/composition_structure_validator.py— 엄격한 조성/구조 검사, 선택적 산화수 추측은 명시적이고 제한적입니다.scripts/structure_analyzer.py— 제한된 격자, 사이트, 대칭, 거리 및 선택적 CrystalNN 보고서.scripts/symmetry_sensitivity_report.py— 공차 그리드 공간 그룹.scripts/io_conversion_plan.py— 종속성 없는 표현 손실 계획.scripts/structure_converter.py— 새 경로로 단일 파일 변환.scripts/phase_diagram_generator.py— 엄격한 로컬 계산 엔트리 hull.scripts/mp_query.py— 건식 실행 MP 쿼리 계획 및 옵트인 제한된 클라이언트.scripts/artifact_manifest.py— 체크섬, 버전, 소스 및 출처.
사용:
python scripts/artifact_manifest.py \
--artifact input.cif --artifact analysis.json \
--workflow "local symmetry sensitivity" --output manifest.json
참조
- 핵심 클래스
- I/O 형식, VASP 및 Q-Chem
- 분석, 대칭, 상 다이어그램, 밴드 및 DOS
- 변환 및 워크플로우
- Materials Project API, 출처, 라이선스 및 제한