Guia completo do Bruma

1. Visão geral

O Bruma lê as saídas do CASTEP [1] e produz, para qualquer material e qualquer átomo:

• a estrutura de bandas, a DOS e a PDOS, com spin up e down;
• as bandas projetadas por orbital;
• a análise da estrutura local de defeitos (vacância, substitucional ou intersticial) e da distorção que eles causam;
• a termodinâmica de formação e de dessorção de hidrogênio;
• a densidade de carga total e polarizada, em 3D, 2D e em perfis;
• a comparação lado a lado entre vários cálculos.

Há duas formas de uso, que fazem a mesma análise:

Princípio central: a energia de Fermi nunca é recalculada. O valor usado é exatamente o que o CASTEP escreveu no .bands, para cada spin; o programa só escolhe o que subtrair do eixo de energia.

Formas de usar o Bruma

O nome vem de bruma, névoa: a nuvem eletrônica que o programa mostra. As letras também são as iniciais do autor, Bruno Macedo. A mesma análise está disponível de quatro formas:

Todas as formas têm uma parte Sobre, com nome, versão, autor, links e como citar. Na linha de comando, use bruma --sobre.

2. Preparar o cálculo no CASTEP

Palavras-chave do .param que geram tudo o que a ferramenta usa:

TASK                    : SPECTRAL           ! ou GeometryOptimization, SinglePoint
SPECTRAL_TASK           : BANDSTRUCTURE      ! DOS para uma malha densa
SPIN_POLARIZED          : TRUE
PDOS_CALCULATE_WEIGHTS  : TRUE               ! gera o .pdos_bin (PDOS e bandas projetadas)
POPN_CALCULATE          : TRUE               ! Mulliken e ligações no .castep
WRITE_FORMATTED_DENSITY : TRUE               ! gera o .den_fmt (densidade de carga e de spin)

O caminho de bandas vai no .cell, em %BLOCK SPECTRAL_KPOINT_PATH [5]. Para uma DOS quantitativa, rode um segundo cálculo com SPECTRAL_TASK : DOS e uma malha Monkhorst–Pack densa [3]; depois indique esse cálculo em DOS a partir de.

3. Abrir os arquivos

1. Abra a ferramenta e arraste os arquivos para a área tracejada, ou clique em Abrir arquivos.
2. Cada seedname é um cálculo. Você pode carregar vários de uma vez: o defeito, a estrutura pura, as referências elementares e outros dopantes.
3. Use × ao lado de um cálculo para removê-lo, ou Limpar dados para recomeçar.
4. O botão ☀/☾ troca o tema; a escolha vale também para o portfólio.

4. Bandas

A aba Bandas mostra spin up e down sobrepostos, lado a lado ou só um deles. Os rótulos dos pontos de alta simetria são detectados para redes cúbica, tetragonal, ortorrômbica e hexagonal, ou digitados em Rótulos dos pontos k (por exemplo G,X,M,G,Z,R,A,Z).

A referência de energia pode ser o E_F de cada spin, um E_F comum ou a energia absoluta.

5. DOS e PDOS

A DOS é a soma de gaussianas sobre as bandas e os k-pontos, com o alargamento σ escolhido. A PDOS pode ser separada em cinco níveis:

A aba Bandas + DOS põe os dois gráficos lado a lado, no mesmo eixo de energia.

6. Bandas projetadas

Nas bandas projetadas, o tamanho de cada ponto é proporcional ao peso do orbital naquela banda e naquele k-ponto. Elas usam as projeções escolhidas na seção Projeção, em painéis separados ou sobrepostos.

7. Análise eletrônica

A aba Análise reúne, para cada spin:

• E_F em Ha e em eV;
• VBM e CBM, definidos pela contagem de elétrons (banda N e N+1), e o gap direto ou indireto com os k-pontos;
• se E_F cai dentro de alguma banda;
• N(E_F) e a polarização de spin;
• o spin integrado;
• as ocupações integradas da PDOS e o centro da banda d;
• Mulliken por espécie e por átomo;
• as ligações do dopante.

8. Editor de gráfico

Logo abaixo de cada figura fica o painel Editar gráfico: título, legenda e cores:

• Título e eixos: título, tamanho, cor, rótulos dos eixos, fonte e fundo (branco para publicação ou cores do site).
• Legenda: posição, tamanho, título e moldura.
• Curvas: para cada curva, cor, nome na legenda, traço, espessura e visibilidade.
• Direto no gráfico: clique num nome da legenda para editá-lo. As edições valem em todas as abas.

9. Defeito e distorção

A aba Defeito e termodinâmica identifica o defeito de duas formas:

• Com a estrutura pura de referência: cada átomo é casado com o seu sítio, com condições periódicas, e o tipo (vacância, substitucional ou intersticial) é encontrado sozinho.
• Sem referência: o defeito é comparado com o "bulk" da própria supercélula, isto é, com os átomos longe dele.

São calculados:

• primeiros vizinhos: cada ligação X–H, por exemplo, contra a referência e contra Mg–H no bulk;
• ligações dos vizinhos (por exemplo H–Mg);
• índices de distorção do poliedro: Baur [9], ECoN [10], elongação quadrática ⟨λ⟩ e variância angular σ² [8], volume e ângulos;
• segunda camada;
• com a referência: o campo de deslocamentos e o raio de perturbação.

10. Termodinâmica

Os potenciais químicos μ_i são a energia por átomo das referências elementares, calculadas com os mesmos parâmetros: Mg hcp, Fe bcc e \(\mu_\mathrm{H}=\tfrac12E(\mathrm{H_2})\). Ao carregar os .castep dessas referências, eles entram sozinhos.

São calculados:

• a energia de formação do defeito [16][17];
• a entalpia de formação do hidreto por mol de H₂, e o efeito do defeito ΔΔH;
• a temperatura de dessorção por van ’t Hoff, com ΔS ≈ entropia padrão do H₂ gasoso [19];
• a energia de remoção de H;
• a capacidade gravimétrica.

As fórmulas estão na seção 18.

11. Gerar os cálculos de referência

Em Gerar os cálculos de referência a partir deste .cell, a ferramenta escreve .cell e .param com o mesmo funcional, corte, spin, tolerâncias e pseudopotenciais do seu cálculo:

As supercélulas usam exatamente a mesma malha k do defeito. As referências elementares usam a mesma densidade de pontos k.

12. Densidade de carga

Na aba Estrutura 3D e densidade, as grandezas disponíveis são ρ total, ρ↑, ρ↓, ρ↑ − ρ↓, |ρ↑ − ρ↓|, ζ = (ρ↑ − ρ↓)/ρ e Δρ.

• 3D: isosuperfície ajustável, com átomos, ligações e célula.
• 2D: cortes por um plano.
• Perfil: densidade ao longo de uma ligação, com o mínimo que aproxima o ponto crítico de ligação.
• Cargas e momentos por átomo: partição de Voronoi [12], comum ou radical [13], e esfera em torno do defeito.
• Para o VESTA [15]: exporte CHGCAR (formato VASP 5 com os elementos, ρ·V) ou XSF. O CHGCAR também serve para o programa bader [14].

13. Planos (h k l), galeria e célula

• Índices da célula base: a ferramenta detecta a multiplicidade da supercélula (por exemplo 3×3×3 do rutilo MgH₂), e os índices são os do material.
• Eixos naturais: os eixos do corte seguem direções da rede; no (110), horizontal [1̄10] e vertical [001].
• Seção inteira: o corte cobre toda a seção da supercélula, com o contorno da célula.
• Varredura: um controle desloca o plano ao longo da normal.
• Galeria: mostra (110), (1̄10), (001), (100), (010), (101), (011) e (111) lado a lado.
• Painel da célula: densidade, capacidade de H, coordenação, distâncias por par e espaçamentos d_hkl.

14. Contribuição do defeito: Δρ

Para ver só o efeito do defeito, escolha Grandeza → contribuição do defeito e, em Subtrair ρ(B), a densidade do material puro (ela é escolhida sozinha quando o nome contém "puro"). Há três formas, da mais simples à mais limpa:

1. ρ(defeito) − ρ(puro relaxado): inclui o efeito eletrônico e a relaxação. Aparecem dipolos em torno dos átomos que se moveram.
2. ρ(defeito) − ρ(puro na geometria do defeito), com o seed_dif_puro_fixo: mesma grade e mesmas posições. Mostra só a troca do hospedeiro pelo dopante.
3. ρ(defeito) − ρ(sem o dopante) − ρ(só o dopante), com B e C: a densidade de ligação do dopante, isto é, a redistribuição de carga ao formar as ligações.

Se as grades forem diferentes, a densidade subtraída é reamostrada na grade do defeito. A ferramenta mostra:

• os elétrons ganhos e perdidos e o saldo;
• ∫Δρ em esferas em volta do dopante;
• a transferência de carga por átomo (∫Δρ na célula de Voronoi de cada átomo).

Componentes e sentido. A diferença pode ser feita no total (Δρ), em cada spin (Δρ↑, Δρ↓) e na magnetização, Δ(ρ↑ − ρ↓). Em Sentido da diferença, escolha ρ(defeito) − ρ(puro) ou ρ(puro) − ρ(defeito). Em vermelho ficam os valores positivos e em azul os negativos. Use Limite da escala de cor ± para realçar a redistribuição fraca nos vizinhos.

3D em volta do defeito. Em Região 3D, uma caixa de ±3 a ±6 Å centrada no dopante mostra os lóbulos de Δρ com as ligações.

Comparação e VESTA. Na aba Comparação, a diferença de cada defeito contra a referência aparece em 3D, lado a lado, e em 2D no mesmo plano. O botão Exportar para o VESTA: todos os cálculos gera um .zip com uma pasta por estrutura. Cada pasta tem os CHGCARs de ρ, ρ↑, ρ↓, ρ↑ − ρ↓ e das quatro diferenças, com os elementos e as posições corretos, mais um guia com a faixa de valores e o passo a passo no VESTA.

Aba Diferença de densidade

Um relatório dedicado à redistribuição de carga causada pelo defeito, com:

• indicadores: ΔN, acúmulo, depleção e carga redistribuída ½∫|Δ|; raios de 50% e 90%; pontos de máximo acúmulo e depleção; dipolo da redistribuição (\(\mathbf p=\int(\mathbf r-\mathbf r_c)\,\Delta\rho\,dV\), em e·Å e Debye); variação do momento;
• ligações: ρ mínimo de cada ligação dopante–vizinho contra a mesma ligação do hospedeiro no puro;
• carga por átomo nas duas estruturas, com os átomos casados;
• trípticos ρ(puro) | ρ(defeito) | Δρ, em 2D e em 3D;
• perfil radial ⟨Δ⟩(r) com a carga acumulada \(\Delta Q(r)=\int_0^r\Delta\rho\,4\pi r'^2dr'\);
• médias planares ao longo de a, b e c;
• perfil ao longo da ligação.

Tudo é exportável para o Origin e o VESTA.

15. Comparação entre cálculos

Na aba Comparação, marque os cálculos e, se houver, a estrutura pura de referência. Você obtém:

• uma tabela com uma coluna por cálculo: energias, E_f, ΔH, ΔΔH, T_d, E_F, gaps, N(E_F), polarização, ocupação e momento d, Mulliken, Voronoi, ρ no ponto crítico, coordenação, ligações, ⟨λ⟩, σ², deslocamentos, ΔV/V, célula e força residual;
• gráficos: barras, DOS e PDOS sobrepostas, bandas lado a lado, ligações, deslocamentos, densidade (inclusive Δρ contra a referência) no mesmo plano e perfis.

16. Exportações

No Origin: arraste o .dat; a linha de nomes vira o Long Name de cada coluna. Nas bandas, a coluna 1 é o X; plote as demais como linhas.

17. Script Python

# tudo: bandas, DOS/PDOS, análise, defeito, densidade, estrutura
python3 bruma.py mgh2_Fe -e Mg,H,Fe

# defeito com referência e termodinâmica
python3 bruma.py mgh2_Fe --ref mgh2_puro --mu "Mg=@Mg_hcp,Fe=@Fe_bcc,H=@H_H2" --h-less mgh2_Fe_semH_perto

# gerar os cálculos de referência
python3 bruma.py mgh2_Fe --gerar-referencias

# densidade: galeria de planos, spin, CHGCAR para o VESTA
python3 bruma.py mgh2_Fe --planes todos --field spin --chgcar

# contribuição do defeito e transferência de carga por átomo
python3 bruma.py mgh2_Fe --field diff --subtract mgh2_Fe_dif_puro_fixo.den_fmt

# pacote para o VESTA: ρ, ρ↑, ρ↓, spin e as diferenças (puro − defeito)
python3 bruma.py mgh2_Fe --vesta --subtract mgh2_puro.den_fmt --diff-sign puro-defeito

Use python3 bruma.py -h para todas as opções.

18. Fórmulas

DOS, com pesos \(w_k\) e alargamento gaussiano \(\sigma\):

\[ g_s(E)=\sum_{k}w_k\sum_n \frac{1}{\sigma\sqrt{2\pi}}\exp\!\left[-\frac{(E-\varepsilon_{nks})^2}{2\sigma^2}\right],\qquad g^{\mathrm{PDOS}}_{s,\alpha}(E)=\sum_k w_k\sum_n p^{\alpha}_{nks}\,\delta_\sigma(E-\varepsilon_{nks}) \]

Gap, com \(N\) o número de elétrons por spin: \(E_g=\min_k\varepsilon_{N+1,k}-\max_k\varepsilon_{N,k}\). Polarização: \(P=\dfrac{N_\uparrow(E_F)-N_\downarrow(E_F)}{N_\uparrow(E_F)+N_\downarrow(E_F)}\).

Distorção do poliedro [9][10][8]:

\[ D=\frac1n\sum_i\frac{|d_i-\bar d|}{\bar d},\qquad \langle\lambda\rangle=\frac1n\sum_i\left(\frac{d_i}{l_0}\right)^2,\qquad \sigma^2=\frac{1}{m-1}\sum_j(\theta_j-\theta_0)^2,\qquad \mathrm{ECoN}=\sum_i e^{\,1-(d_i/d_\mathrm{av})^6} \]

Aqui \(l_0\) é a distância centro–vértice do poliedro regular de mesmo volume e \(\theta_0\) é 90° (octaedro) ou 109,47° (tetraedro).

Termodinâmica [16]:

\[ E_f=E_\mathrm{def}-E_\mathrm{pura}-\sum_i n_i\mu_i,\qquad \Delta H_f=\frac{E-\sum_i N_i\mu_i}{N_\mathrm{H}/2},\qquad T_d=\frac{\Delta H}{\Delta S},\qquad \mu_\mathrm{H}=\tfrac12E(\mathrm{H}_2) \]

No E_f, \(n_i>0\) indica átomos adicionados. O ΔH é por mol de H₂ e o ΔS padrão é 130,7 J/(mol·K).

Densidade: o CASTEP e o VASP gravam \(\rho V\). O Bruma usa \(\rho\) em e/ų, com \(\int\rho\,dV=N_e\), \(\zeta=(\rho_\uparrow-\rho_\downarrow)/\rho\) e \(\Delta\rho=\rho_A-\rho_B-\rho_C\). Na partição de Voronoi radical, cada ponto vai para o átomo que minimiza \(|\mathbf r-\mathbf R_a|^2-r_a^2\), com os raios covalentes de Cordero [11].

19. Cuidados e limitações

• DOS do caminho de bandas serve só para ilustrar; para números, use uma malha densa.
• Gap e bordas vêm só dos k-pontos do caminho.
• Componentes m e t_2g/e_g estão nos eixos cartesianos da célula.
• Energias de 0 K não têm energia de ponto zero; T_d é uma estimativa para comparar tendências.
• Mesmos parâmetros: compare só cálculos com o mesmo funcional, corte, pseudopotenciais e U.
• Cargas de Voronoi são estimativas; para números quantitativos, use Bader.
• Δρ com grades ou volumes diferentes é reamostrado. Grades idênticas, com o dif_puro_fixo, são o ideal.

20. Como citar

Se o Bruma ajudou no seu trabalho, cite o software e, quando fizer sentido, o TCC e a dissertação do autor. Cite também o CASTEP [1] e o VESTA [15], se usá-lo. Downloads: bruma.bib · CITATION.cff · tutorial em PDF · fonte LaTeX.

ABNT (NBR 6023)

BibTeX

@misc{macedo2026bruma,
  author       = {Macedo, Bruno Henrique Dourado},
  title        = {Bruma: análise de estrutura de bandas, {DOS}, {PDOS}, densidade de carga, defeitos e termodinâmica a partir de cálculos {CASTEP}},
  year         = {2026},
  version      = {1.0},
  howpublished = {\url{https://brunohdmacedo.tech/bruma/}},
  note         = {Código-fonte: \url{https://github.com/brunohdmacedo/bruma-dft}}
}

@misc{macedo2025tcc,
  author       = {Macedo, Bruno Henrique Dourado},
  title        = {Influência de defeitos substitucionais nas propriedades estruturais, eletrônicas, termodinâmicas e de armazenamento do hidreto {MgH$_2$}: uma abordagem \textit{ab initio}},
  year         = {2025},
  howpublished = {Trabalho de Conclusão de Curso (Bacharelado em Engenharia Física), UNILA},
  url          = {https://dspace.unila.edu.br/items/8db3836e-925d-422f-9cd2-6ff3f9f02080},
  note         = {Orientador: Rodrigo Santos da Lapa}
}

@misc{macedo2024dataset,
  author = {Macedo, Bruno Henrique Dourado and Zalewski, Willian},
  title  = {Dataset\_Machine\_Learning\_Exoplanets\_2024},
  year   = {2024},
  howpublished = {Mendeley Data, v3},
  doi    = {10.17632/wctcv34962.3}
}

@mastersthesis{macedo2027dissertacao,
  author  = {Macedo, Bruno Henrique Dourado},
  title   = {Influência de defeitos substitucionais no {MgH$_2$}: uma abordagem \textit{ab initio}},
  school  = {PPGFISA, Universidade Federal da Integração Latino-Americana (UNILA)},
  address = {Foz do Iguaçu, PR},
  year    = {2027},
  type    = {Dissertação (Mestrado em Física Aplicada)},
  note    = {Orientador: J. R. C. Salgado; coorientador: R. S. da Lapa. Bolsa CNPq}
}

O TCC, o artigo e a base de dados foram conferidos no DSpace UNILA, na RBIC e no Mendeley Data; o título da dissertação (em andamento) ainda deve ser conferido. No GitHub, o arquivo CITATION.cff faz aparecer o botão “Cite this repository”.

21. Referências

1. CLARK, S. J. et al. First principles methods using CASTEP. Z. Kristallogr., v. 220, p. 567–570, 2005. doi:10.1524/zkri.220.5.567.65075
2. PERDEW, J. P.; BURKE, K.; ERNZERHOF, M. Generalized gradient approximation made simple. Phys. Rev. Lett., v. 77, p. 3865, 1996. doi:10.1103/PhysRevLett.77.3865
3. MONKHORST, H. J.; PACK, J. D. Special points for Brillouin-zone integrations. Phys. Rev. B, v. 13, p. 5188, 1976. doi:10.1103/PhysRevB.13.5188
4. SAKINTUNA, B.; LAMARI-DARKRIM, F.; HIRSCHER, M. Metal hydride materials for solid hydrogen storage: a review. Int. J. Hydrogen Energy, v. 32, p. 1121–1140, 2007. doi:10.1016/j.ijhydene.2006.11.022
5. SETYAWAN, W.; CURTAROLO, S. High-throughput electronic band structure calculations. Comput. Mater. Sci., v. 49, p. 299–312, 2010. doi:10.1016/j.commatsci.2010.05.010
6. MULLIKEN, R. S. Electronic population analysis on LCAO–MO molecular wave functions. I. J. Chem. Phys., v. 23, p. 1833, 1955. doi:10.1063/1.1740588
7. SEGALL, M. D. et al. Population analysis of plane-wave electronic structure calculations of bulk materials. Phys. Rev. B, v. 54, p. 16317, 1996. doi:10.1103/PhysRevB.54.16317
8. ROBINSON, K.; GIBBS, G. V.; RIBBE, P. H. Quadratic elongation. Science, v. 172, p. 567–570, 1971. doi:10.1126/science.172.3983.567
9. BAUR, W. H. The geometry of polyhedral distortions. Acta Cryst. B, v. 30, p. 1195–1215, 1974. doi:10.1107/S0567740874004560
10. HOPPE, R. Effective coordination numbers (ECoN) and mean fictive ionic radii (MEFIR). Z. Kristallogr., v. 150, p. 23–52, 1979. doi:10.1524/zkri.1979.150.1-4.23
11. CORDERO, B. et al. Covalent radii revisited. Dalton Trans., p. 2832–2838, 2008. doi:10.1039/B801115J
12. VORONOI, G. Nouvelles applications des paramètres continus à la théorie des formes quadratiques. J. Reine Angew. Math., v. 134, p. 198–287, 1908. doi:10.1515/crll.1908.134.198
13. GELLATLY, B. J.; FINNEY, J. L. The radical alternative to the Voronoi polyhedron. J. Non-Cryst. Solids, v. 50, p. 313–329, 1982. doi:10.1016/0022-3093(82)90093-X
14. HENKELMAN, G.; ARNALDSSON, A.; JÓNSSON, H. A fast and robust algorithm for Bader decomposition of charge density. Comput. Mater. Sci., v. 36, p. 354–360, 2006. doi:10.1016/j.commatsci.2005.04.010
15. MOMMA, K.; IZUMI, F. VESTA 3 for three-dimensional visualization of crystal, volumetric and morphology data. J. Appl. Cryst., v. 44, p. 1272–1276, 2011. doi:10.1107/S0021889811038970
16. FREYSOLDT, C. et al. First-principles calculations for point defects in solids. Rev. Mod. Phys., v. 86, p. 253–305, 2014. doi:10.1103/RevModPhys.86.253
17. VAN DE WALLE, C. G.; NEUGEBAUER, J. First-principles calculations for defects and impurities. J. Appl. Phys., v. 95, p. 3851, 2004. doi:10.1063/1.1682673
18. GANOSE, A. M.; JACKSON, A. J.; SCANLON, D. O. sumo. J. Open Source Softw., v. 3, p. 717, 2018. doi:10.21105/joss.00717
19. CHASE, M. W. NIST-JANAF Thermochemical Tables. 4. ed. J. Phys. Chem. Ref. Data, Monograph 9, 1998.