pymatgen

O que pymatgen faz?

Use pymatgen para trabalhar explicitamente com proveniência e preservação de dados em composições, moléculas, estruturas periódicas, entradas computacionais (entries), 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 dependente do método e dos 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 propriedade de seus contribuidores. Verifique os termos exatos do artefato e dos dados antes de redistribuir.

Snapshot verificado (2026-07-23)

• pymatgen==2026.5.4 é o lançamento estável mais recente do pacote wrapper (2026-05-04). Os metadados do pacote exigem Python 3.11+ e requerem diretamente pymatgen-core>=2026.4.16.
• pymatgen-core==2026.7.16 é o lançamento estável mais recente do pacote core (2026-07-16). Agora contém objetos core, operações de simetria/rede e a camada de E/S, tudo sob o namespace pymatgen.* existente.
• mp-api==0.46.4 é o cliente estável mais recente do Materials Project (2026-06-15), requer Python 3.11+ e depende de pymatgen>2024.2.20.
• O site atual da API é construído a partir da documentação core de 2026.7.16. Fixar ambas as distribuições evita que pymatgen==2026.5.4 resolva silenciosamente para um core futuro diferente.
• Pymatgen usa versões baseadas em data. PyPI renderiza a data com pontos; não infira compatibilidade semântica de versão a partir dos números.

Crie um lock de projeto para reprodutibilidade:

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

Para um ambiente descartável revisado:

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"

Pins diretos não congelam todas as wheels transitivas. Preserve uv.lock, plataforma, versão do Python, versões dos pacotes e hashes dos artefatos.

Fluxo de trabalho obrigatório

1. Indique se o objeto é uma Molecule não periódica ou uma Structure periódica; registre a rede e as condições de contorno periódicas.
2. Indique as unidades. Pymatgen geralmente usa Å, graus, eV, eV/átomo, u (amu) e g/cm³, mas o contrato documentado de cada API é a autoridade.
3. Indique o modo de coordenadas. As coordenadas de Structure são fracionárias a menos que coords_are_cartesian=True; as coordenadas de Molecule são cartesianas.
4. Inspecione cada aviso do parser. Para CIF, preserve avisos de ocupação, mesclagem de sítios, estequiometria e correção; não aceite correções silenciosamente.
5. Relate desordem/ocupações parciais e decoração de estado de oxidação. Nunca adivinhe estados de oxidação implicitamente.
6. Execute validação antes de análises de simetria, vizinhança, transformação, conversão ou termodinâmica.
7. Varie as tolerâncias de simetria e relate symprec em Å e angle_tolerance em graus a 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 em um novo caminho e verifique as propriedades cientificamente relevantes com um teste de ida e volta.
10. Construa diagramas de fase apenas a partir de energias totais e esquemas de correção compatíveis. Um hull computado é condicional ao conjunto de entradas fornecido.
11. Mantenha todo acesso ao banco de dados desligado por padrão. Divulgue 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 gráfico de objetos gerais não confiáveis; use JSON validado por esquema e construtores explícitos.

Objetos core

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

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 e Molecule são mutáveis; use IStructure/IMolecule ou uma cópia explícita quando a mutação comprometer a proveniência. Veja classes core.

Entrada segura de estrutura local

Prefira o validador integrado, que captura avisos CIF e Python e relata unidades, ocupação, desordem, estados de oxidação, periodicidade, modo de coordenadas e distâncias mínimas:

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

Para trabalho direto com CIF, use o método atual do parser e inspecione ambos os canais de aviso:

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]

Não analise arquivos não confiáveis em um processo privilegiado. Uma falha crítica de execução de código em CIF malicioso afetou o pymatgen até 2024.2.8 e foi corrigida em 2024.2.20; o lançamento fixado é mais novo, mas parsers ainda processam entradas controladas por atacante. Use isolamento e limites de CPU/RAM/disco/tempo.

Simetria

A atribuição de grupo espacial depende de tolerâncias e da qualidade da estrutura:

from pymatgen.symmetry.analyzer import SpacegroupAnalyzer

analyzer = SpacegroupAnalyzer(
    structure,
    symprec=0.01,          # Å
    angle_tolerance=5.0,   # graus
)
symbol = analyzer.get_space_group_symbol()
number = analyzer.get_space_group_number()

O pipeline do Materials Project normalmente usa symprec=0.1 Å, enquanto o padrão documentado do pymatgen é 0.01 Å; estes podem produzir atribuições diferentes. Gere um relatório de sensibilidade em vez de alterar a tolerância até que uma resposta preferida apareça:

python scripts/symmetry_sensitivity_report.py structure.cif \
  --symprec 0.001,0.01,0.1 --angle-tolerance 1,5

Veja módulos de análise.

Conversão e E/S de parser/writer

Planeje primeiro; o planejador não abre arquivos nem importa pymatgen:

python scripts/io_conversion_plan.py \
  --input input.cif --input-format cif \
  --output POSCAR.new --output-format poscar \
  --periodic --coordinate-mode direct

Em seguida, converta para um novo caminho com reconhecimento explícito de perda:

python scripts/structure_converter.py input.cif POSCAR.new \
  --output-format poscar --coordinate-mode direct --allow-lossy \
  --acknowledge-parser-warnings

CIF, POSCAR, XYZ e JSON não preservam as mesmas semânticas. Verifique rede, periodicidade, modo de coordenadas, ordenação de espécies, dinâmica seletiva, propriedades de sítio, estados de oxidação, rótulos e desordem após cada conversão. Veja formatos de E/S.

Transformações e proveniência

Transforme uma cópia e preserve o histórico:

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

Transformações de ordenação, dopagem, slab e magnéticas um-para-muitos podem expandir combinatorialmente ou invocar executáveis opcionais. Limite candidatos, sítios, tamanho da supercélula, tempo de execução e contagem de saída. Veja transformações e workflows.

Diagramas de fase locais

O gerador incluído é offline e aceita apenas um esquema JSON estrito com total de eV por entrada e proveniência:

{
  "schema_version": "1.0",
  "energy_unit": "eV",
  "energy_basis": "total_per_entry",
  "provenance": {
    "source": "cálculos locais revisados",
    "method": "um esquema de energia/correção compatível"
  },
  "entries": [
    {
      "entry_id": "local-Li",
      "composition": "Li",
      "energy_eV": -1.0,
      "provenance": {"source": "manifesto de cálculo sha256:..."}
    }
  ]
}

python scripts/phase_diagram_generator.py entries.json --analyze Li2O

Endpoints elementares e todas as fases concorrentes devem estar presentes. Não misture energias brutas de diferentes funcionais, pseudopotenciais, estados magnéticos ou convenções de correção. O status de hull computado não é estabilidade experimental.

Estruturas de bandas, DOS, VASP e Q-Chem

Analise apenas os dados necessários:

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

Autovalores projetados podem exigir memória extrema. Verifique convergência, caminho k, configurações de spin/SOC, convenções do nível de Fermi, smearing e base de projeção antes de interpretar gaps ou DOS. Um sucesso do parser não é um cálculo convergido.

As interfaces atuais do Q-Chem são pymatgen.io.qchem.inputs.QCInput e 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 escreve entradas e analisa saídas; não concede uma licença VASP ou Q-Chem ou estabelece validade do método. Arquivos POTCAR são licenciados pela VASP e não são distribuídos pelo pymatgen. Nunca os redistribua nem escaneie diretórios não relacionados em busca deles. Ferramentas opcionais como enumlib, Bader, packmol, ffmpeg e Zeo++ são executáveis nativos/externos: revise proveniência, licenças, argv, diretório de trabalho e limites de recursos antes de uma invocação explícita separada.

Materials Project: planeje antes da rede

Use apenas:

from mp_api.client import MPRester

O cliente lê MP_API_KEY quando construído. Forneça apenas essa variável de ambiente nomeada através do shell do usuário ou gerenciador de segredos. Não aceite a chave como argumento de CLI, percorra arquivos .env, despeje variáveis de ambiente ou imprima dados de exceção sem redação.

O planejamento dry-run é o padrão:

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

Apenas --execute permite uma consulta de resumo limitada e exige uma nova saída:

python scripts/mp_query.py \
  --material-id mp-149 \
  --fields formula_pretty,structure,origins,last_updated \
  --limit 1 --output mp-149.json --execute

O CLI define num_chunks=1, exige campos e filtros explícitos, limita resultados, não implementa um cache de resultados implícito e nunca sobrescreve a saída. MPRester também realiza solicitações de metadados de compatibilidade/heartbeat durante a inicialização; o plano divulga estas, desabilita o agente de usuário de detalhes da plataforma e o log de notificação de versão do banco de dados local, e registra a versão do banco de dados retornada. O fluxo de trabalho de resumo não solicita downloads de cache do conjunto de dados completo. mp-api 0.46.4 retenta HTTP 429/502/504 de acordo com sua própria política configurada e respeita Retry-After; não invente uma cota de serviço numérica ou adicione um loop de retentativa ilimitado.

Os valores core do Materials Project são dados computados, dependentes do método—não verdade experimental. PBE geralmente superestima parâmetros de rede e subestima sistematicamente gaps de banda; valores agregados podem mudar entre versões do banco de dados. Preserve tempo de recuperação, consulta, campos, origens de material/tarefa, versão do banco de dados quando disponível, versões do cliente, atribuição CC BY e as citações canônicas e específicas de propriedade. Veja API do Materials Project.

CLIs incluídos

Todos os CLIs têm --help sem dependências, importações científicas lentas, JSON limitado e nenhuma rede implícita:

• scripts/composition_structure_validator.py — verificações estritas de composição/estrutura; a adivinhação opcional de estado de oxidação é explícita e limitada.
• scripts/structure_analyzer.py — relatório limitado de rede, sítios, simetria, distância e CrystalNN opcional.
• scripts/symmetry_sensitivity_report.py — grupos espaciais em grade de tolerância.
• scripts/io_conversion_plan.py — plano de perda de representação sem dependências.
• scripts/structure_converter.py — conversão de um arquivo para um novo caminho.
• scripts/phase_diagram_generator.py — hull estrito de entrada computacional local.
• scripts/mp_query.py — plano de consulta MP dry-run e cliente limitado opcional.
• scripts/artifact_manifest.py — checksums, versões, fontes e proveniência.

Use:

python scripts/artifact_manifest.py \
  --artifact input.cif --artifact analysis.json \
  --workflow "local symmetry sensitivity" --output manifest.json

Referências

• Classes core
• Formatos de E/S, VASP e Q-Chem
• Análise, simetria, diagramas de fase, bandas e DOS
• Transformações e workflows
• API do Materials Project, proveniência, licença e limites

Fontes (verificadas em 2026-07-23)

• pymatgen 2026.5.4 no PyPI
• pymatgen-core 2026.7.16 no PyPI
• Documentação da API pymatgen
• Changelog do pymatgen
• mp-api 0.46.4 no PyPI