pymatgen

Use o pymatgen para trabalho explícito e com preservação de proveniência com composições, moléculas, estruturas periódicas, entradas computadas, simetria, diagramas de fase, estruturas eletrônicas e arquivos de código de estrutura eletrônica. Trate cada análise, conversão, atribuição de simetria, transformação e resultado de banco de dados como dependentes de método e parâmetros.

A licença MIT frontmatter cobre esta habilidade. pymatgen e pymatgen-core são MIT; mp-api declara BSD-3-Clause-LBNL. Os dados do Materials Project são geralmente CC BY 4.0, enquanto os dados contribuídos permanecem de propriedade de seus contribuidores. Verifique os termos exatos do artefato e dos dados antes da redistribuição.

Snapshot verificado (2026-09-30)

• pymatgen==2026.9.24 é a versão mais recente do wrapper estável (enviado em 2026-09-23). Os metadados do pacote exigem Python 3.11+ e dependem diretamente de pymatgen-core>=2026.9.23.
• pymatgen-core==2026.9.23 é a versão mais recente do núcleo estável (2026-09-23). Agora contém objetos centrais, operações de simetria/rede e a camada de E/S, tudo sob o namespace existente pymatgen.*.
• mp-api==0.46.5 é o cliente mais recente do Materials Project estável (2026-08-18), requer Python 3.11+ e depende de pymatgen>2024.2.20.
• O site atual da API é construído a partir da documentação principal de 2026.9.23. Fixar ambas as distribuições impede que pymatgen==2026.9.24 seja resolvido silenciosamente para um núcleo futuro diferente.
• Pymatgen usa versões baseadas em data. PyPI renderiza a data com pontos; não infira compatibilidade de versão semântica dos números.

A suíte CLI local e os exemplos sintéticos foram executados neste snapshot. Análises VASP/Q-Chem dependentes de arquivo e exemplos de API autenticados abaixo são ilustrativos: suas assinaturas e o código-fonte atual do SDK foram verificados, mas nenhum cálculo licenciado ou recuperação de serviço autenticado foi realizado.

Crie um lock de projeto para reprodutibilidade:

uv init --python 3.11
uv add "pymatgen==2026.9.24" "pymatgen-core==2026.9.23" "mp-api==0.46.5"
uv lock
uv sync --frozen

Para um ambiente revisado descartável:

uv venv --python 3.11 .venv-pymatgen
uv pip install --python .venv-pymatgen/bin/python \
  "pymatgen==2026.9.24" "pymatgen-core==2026.9.23" "mp-api==0.46.5"

Fixações diretas não congelam todas as rodas transitivas. Preserve uv.lock, plataforma, versão do Python, versões dos pacotes e hashes dos artefatos.

Fluxo de trabalho necessário

1. Declare se o objeto é um Molecule não periódico ou um Structure periódico; registre a rede e as condições de contorno periódicas.
2. Declare as unidades. Pymatgen usa comumente Å, graus, eV, eV/átomo, amu e g/cm³, mas o contrato documentado de cada API é autoritativo.
3. Declare o modo de coordenadas. As coordenadas Structure são fracionárias, a menos que coords_are_cartesian=True; as coordenadas Molecule são cartesianas.
4. Inspecione todos os avisos do parser. Para CIF, preserve avisos de ocupância, mesclagem de sítios, estequiometria e correção; não aceite correções silenciosamente.
5. Relate desordem/ocupâncias parciais e decoração de estado de oxidação. Nunca adivinhe estados de oxidação implicitamente.
6. Execute a validação antes da análise de simetria, vizinhos, transformação, conversão ou termodinâmica.
7. Varra as tolerâncias de simetria e relate symprec em Å e angle_tolerance em graus com cada atribuição.
8. Trate transformações como novos artefatos. Preserve a entrada, parâmetros, versões de software, avisos e checksums pai/filho.
9. Antes da conversão, identifique a perda de representação. Escreva apenas para um novo caminho e verifique por round-trip propriedades cientificamente relevantes.
10. Construa diagramas de fase apenas a partir de energias totais compatíveis e esquemas de correção. Uma casca computada é condicional ao conjunto de entradas fornecido.
11. Mantenha todo o acesso ao banco de dados desativado por padrão. Divulgue o endpoint, filtros, campos, limite de resultados, comportamento de cache, saída, licença e citação antes de uma etapa de execução explícita.
12. Preserve um manifesto de artefatos. Nunca use pickle ou carregue um grafo de objetos geral não confiável; use JSON validado por esquema e construtores explícitos.

Objetos centrais

Use as importações de conveniência públicas:

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"],

…