0
# Electronic Structure Analysis
1
2
Band structure analysis, density of states processing, transport properties calculation via BoltzTraP, and COHP analysis for chemical bonding insights. These tools enable comprehensive analysis of electronic properties from DFT calculations and provide visualization and interpretation capabilities for materials science research.
3
4
## Capabilities
5
6
### Band Structure Analysis
7
8
Classes for representing, analyzing, and plotting electronic band structures from DFT calculations.
9
10
```python { .api }
11
class BandStructure:
12
"""
13
Generic band structure representation with k-points and eigenvalues.
14
15
Parameters:
16
- kpoints: List of Kpoint objects or k-point coordinates
17
- eigenvals: Dict of eigenvalues {Spin: array of eigenvalues}
18
- lattice: Lattice object for reciprocal space
19
- efermi: Fermi energy in eV
20
- labels_dict: Dict of k-point labels {string: kpoint}
21
- coords_are_cartesian: Whether k-point coords are Cartesian
22
- structure: Associated Structure object
23
- projections: Orbital projections data
24
"""
25
def __init__(self, kpoints, eigenvals, lattice, efermi, labels_dict=None,
26
coords_are_cartesian=False, structure=None, projections=None): ...
27
28
def get_band_gap(self):
29
"""
30
Get band gap information.
31
32
Returns:
33
dict: Band gap data with energy, direct/indirect, and k-points
34
"""
35
36
def get_cbm(self):
37
"""
38
Get conduction band minimum information.
39
40
Returns:
41
dict: CBM energy, k-point, and band index
42
"""
43
44
def get_vbm(self):
45
"""
46
Get valence band maximum information.
47
48
Returns:
49
dict: VBM energy, k-point, and band index
50
"""
51
52
def get_direct_band_gap_dict(self):
53
"""
54
Get direct band gaps at all k-points.
55
56
Returns:
57
dict: Direct band gaps by k-point
58
"""
59
60
def get_direct_band_gap(self):
61
"""
62
Get minimum direct band gap.
63
64
Returns:
65
float: Direct band gap energy in eV
66
"""
67
68
def is_metal(self, efermi_tol=1e-4):
69
"""
70
Check if material is metallic.
71
72
Parameters:
73
efermi_tol: Tolerance for Fermi energy crossing bands
74
75
Returns:
76
bool: True if metallic
77
"""
78
79
@property
80
def nb_bands(self):
81
"""Number of bands."""
82
83
@property
84
def bands(self):
85
"""Band eigenvalues as dict {Spin: array}."""
86
87
@property
88
def is_spin_polarized(self):
89
"""Whether calculation is spin-polarized."""
90
91
def get_projection_on_elements(self):
92
"""
93
Get orbital projections summed by element.
94
95
Returns:
96
dict: Projections by element
97
"""
98
99
def get_projections_on_elts_and_orbitals(self, el_orb_spec):
100
"""
101
Get projections on specific elements and orbitals.
102
103
Parameters:
104
el_orb_spec: Dict specifying elements and orbitals
105
106
Returns:
107
dict: Filtered projections
108
"""
109
```
110
111
```python { .api }
112
class BandStructureSymmLine:
113
"""
114
Band structure along high-symmetry lines with labels.
115
116
Inherits all BandStructure methods plus:
117
"""
118
119
def get_equivalent_kpoints(self, index, cartesian=False):
120
"""
121
Get equivalent k-points by symmetry.
122
123
Parameters:
124
index: K-point index
125
cartesian: Whether to return Cartesian coordinates
126
127
Returns:
128
list: Equivalent k-points
129
"""
130
131
def get_branch(self, index):
132
"""
133
Get branch containing k-point index.
134
135
Parameters:
136
index: K-point index
137
138
Returns:
139
list: Branch information
140
"""
141
142
@property
143
def branches(self):
144
"""List of k-point branches between high-symmetry points."""
145
146
def apply_scissor(self, new_band_gap):
147
"""
148
Apply scissor correction to band gap.
149
150
Parameters:
151
new_band_gap: Target band gap in eV
152
153
Returns:
154
BandStructureSymmLine: Corrected band structure
155
"""
156
```
157
158
### Density of States Analysis
159
160
Classes for analyzing and manipulating electronic density of states data.
161
162
```python { .api }
163
class Dos:
164
"""
165
Generic density of states spectrum.
166
167
Parameters:
168
- efermi: Fermi energy in eV
169
- energies: Array of energy values
170
- densities: Dict of DOS values {Spin: array}
171
"""
172
def __init__(self, efermi, energies, densities): ...
173
174
def get_interpolated_value(self, energy):
175
"""
176
Get interpolated DOS value at given energy.
177
178
Parameters:
179
energy: Energy in eV
180
181
Returns:
182
dict: DOS values by spin
183
"""
184
185
def get_interpolated_gap(self, tol=0.001, abs_tol=False, spin=None):
186
"""
187
Get interpolated band gap from DOS.
188
189
Parameters:
190
tol: Tolerance for zero DOS
191
abs_tol: Whether tolerance is absolute
192
spin: Specific spin channel
193
194
Returns:
195
tuple: (gap_energy, cbm_vbm_data)
196
"""
197
198
def get_cbm_vbm(self, tol=0.001, abs_tol=False, spin=None):
199
"""
200
Get CBM and VBM from DOS.
201
202
Returns:
203
tuple: (cbm_energy, vbm_energy)
204
"""
205
206
def get_gap(self, tol=0.001, spin=None):
207
"""
208
Get band gap from DOS.
209
210
Returns:
211
float: Band gap in eV
212
"""
213
214
@property
215
def energies(self):
216
"""Energy array."""
217
218
@property
219
def densities(self):
220
"""DOS densities by spin."""
221
222
@property
223
def efermi(self):
224
"""Fermi energy."""
225
```
226
227
```python { .api }
228
class CompleteDos:
229
"""
230
Complete DOS with atomic and orbital projections.
231
232
Parameters:
233
- structure: Associated Structure object
234
- total_dos: Total DOS object
235
- pdoss: Dict of projected DOS by site {site_index: {orbital: Dos}}
236
"""
237
def __init__(self, structure, total_dos, pdoss): ...
238
239
def get_element_dos(self):
240
"""
241
Get DOS projected by element.
242
243
Returns:
244
dict: DOS by element type
245
"""
246
247
def get_spd_dos(self):
248
"""
249
Get DOS projected by s, p, d orbitals.
250
251
Returns:
252
dict: DOS by orbital type (s, p, d)
253
"""
254
255
def get_element_spd_dos(self, el):
256
"""
257
Get element-specific orbital-projected DOS.
258
259
Parameters:
260
el: Element symbol or Element object
261
262
Returns:
263
dict: DOS by orbital for the element
264
"""
265
266
def get_site_dos(self, site):
267
"""
268
Get DOS for a specific site.
269
270
Parameters:
271
site: Site object or site index
272
273
Returns:
274
Dos: DOS for the site
275
"""
276
277
def get_site_orbital_dos(self, site, orbital):
278
"""
279
Get orbital-specific DOS for a site.
280
281
Parameters:
282
site: Site object or site index
283
orbital: Orbital (e.g., Orbital.s, Orbital.px)
284
285
Returns:
286
Dos: Orbital-projected DOS
287
"""
288
289
def get_site_spd_dos(self, site):
290
"""
291
Get s, p, d projected DOS for a site.
292
293
Parameters:
294
site: Site object or site index
295
296
Returns:
297
dict: DOS by orbital type for the site
298
"""
299
300
def get_site_t2g_eg_resolved_dos(self, site):
301
"""
302
Get t2g and eg resolved DOS for a site.
303
304
Parameters:
305
site: Site object or site index
306
307
Returns:
308
dict: DOS by t2g and eg orbitals
309
"""
310
311
@property
312
def structure(self):
313
"""Associated structure."""
314
315
@property
316
def pdos(self):
317
"""Projected DOS dictionary."""
318
```
319
320
### Orbital Analysis
321
322
Classes for representing electronic orbitals and magnetic moments.
323
324
```python { .api }
325
class Orbital:
326
"""
327
Electronic orbital enumeration.
328
329
Available orbitals:
330
- s
331
- py, pz, px
332
- dxy, dyz, dz2, dxz, dx2
333
- f_3, f_2, f_1, f0, f1, f2, f3
334
"""
335
336
@staticmethod
337
def orbital_type(self):
338
"""
339
Get orbital type (s, p, d, f).
340
341
Returns:
342
OrbitalType: Type of orbital
343
"""
344
345
class Spin:
346
"""
347
Spin enumeration (up = 1, down = -1).
348
"""
349
up = 1
350
down = -1
351
352
class Magmom:
353
"""
354
Magnetic moment representation with Cartesian components.
355
356
Parameters:
357
- moment: Magnetic moment (float for collinear, list for non-collinear)
358
- saxis: Spin axis for non-collinear magnetism
359
"""
360
def __init__(self, moment, saxis=(0, 0, 1)): ...
361
362
@property
363
def x(self): ...
364
@property
365
def y(self): ...
366
@property
367
def z(self): ...
368
369
def get_moment(self, saxis=(0, 0, 1)):
370
"""
371
Get magnetic moment along specified axis.
372
373
Parameters:
374
saxis: Spin axis direction
375
376
Returns:
377
float: Magnetic moment component
378
"""
379
380
def get_xyz_magmom_with_saxis(self, saxis):
381
"""
382
Get Cartesian magnetic moment components with spin axis.
383
384
Returns:
385
numpy.ndarray: [x, y, z] moment components
386
"""
387
388
@property
389
def global_moment(self):
390
"""Global magnetic moment magnitude."""
391
392
def get_consistent_set_and_saxis(self, magmoms, saxis=None):
393
"""
394
Get consistent set of magnetic moments and spin axis.
395
396
Parameters:
397
magmoms: List of magnetic moments
398
saxis: Preferred spin axis
399
400
Returns:
401
tuple: (consistent_magmoms, spin_axis)
402
"""
403
```
404
405
### Transport Properties (BoltzTraP)
406
407
Integration with BoltzTraP for calculating transport properties from band structures.
408
409
```python { .api }
410
class BztInterpolator:
411
"""
412
BoltzTraP2 interpolation interface for transport properties.
413
414
Parameters:
415
- kpoints: K-point mesh
416
- energies: Band eigenvalues
417
- curvature: Curvature data
418
- bandana: Band analysis data
419
- cband: Conduction band data
420
- eband: Energy band data
421
- proj: Projection data
422
- mommat: Momentum matrix elements
423
- magmom: Magnetic moments
424
"""
425
def __init__(self, kpoints=None, energies=None, curvature=None,
426
bandana=None, cband=None, eband=None, proj=None,
427
mommat=None, magmom=None): ...
428
429
@classmethod
430
def from_files(cls, fildos="DOS", filvol="DOSCAR", filband="EIGENVAL",
431
filproj="PROCAR", filkp="IBZKPT"):
432
"""
433
Create interpolator from files.
434
435
Parameters:
436
fildos, filvol, filband, filproj, filkp: File paths
437
438
Returns:
439
BztInterpolator: Configured interpolator
440
"""
441
442
@classmethod
443
def from_band_structure(cls, bs, nelect, lpfac=10, run_boltztrap=True,
444
dos_type="HISTO", energy_grid=None, lpfac_k=None,
445
curvature=True, save_bztInterp=True,
446
fname="bztInterp.json.gz", doping=None,
447
448
def get_average_eff_mass(self, output="eigs", doping_levels=False):
449
"""
450
Get average effective mass.
451
452
Parameters:
453
output: Output format ("eigs" or "tensors")
454
doping_levels: Whether to calculate for doping levels
455
456
Returns:
457
dict: Effective mass data
458
"""
459
460
def get_seebeck_eff_mass(self, output="eigs", temp_r=None, doping_levels=False):
461
"""
462
Get Seebeck effective mass.
463
464
Parameters:
465
output: Output format
466
temp_r: Temperature range
467
doping_levels: Whether to calculate for doping levels
468
469
Returns:
470
dict: Seebeck effective mass data
471
"""
472
473
def get_complexity_factor(self, output="eigs", temp_r=300, doping_levels=False,
474
k_B=8.617e-05):
475
"""
476
Get complexity factor for thermoelectric performance.
477
478
Returns:
479
dict: Complexity factor data
480
"""
481
482
def get_carrier_concentration(self):
483
"""
484
Get carrier concentration.
485
486
Returns:
487
dict: Carrier concentration by temperature and doping
488
"""
489
490
def get_conductivity(self, output="eigs", relaxation_time=1e-14, doping_levels=False):
491
"""
492
Get electrical conductivity.
493
494
Parameters:
495
output: Output format
496
relaxation_time: Electronic relaxation time in seconds
497
doping_levels: Whether to calculate for doping levels
498
499
Returns:
500
dict: Conductivity data
501
"""
502
503
def get_seebeck(self, output="eigs", doping_levels=False):
504
"""
505
Get Seebeck coefficient.
506
507
Returns:
508
dict: Seebeck coefficient data
509
"""
510
511
def get_thermal_conductivity(self, output="eigs", relaxation_time=1e-14,
512
beta_const_strain_tensor=None, doping_levels=False,
513
kl_coeff=1.0):
514
"""
515
Get thermal conductivity.
516
517
Parameters:
518
output: Output format
519
relaxation_time: Electronic relaxation time
520
beta_const_strain_tensor: Thermal expansion tensor
521
doping_levels: Whether to calculate for doping levels
522
kl_coeff: Lattice thermal conductivity coefficient
523
524
Returns:
525
dict: Thermal conductivity data
526
"""
527
528
def get_power_factor(self, output="eigs", relaxation_time=1e-14, doping_levels=False):
529
"""
530
Get thermoelectric power factor.
531
532
Returns:
533
dict: Power factor data
534
"""
535
536
def get_zt(self, output="eigs", relaxation_time=1e-14,
537
beta_const_strain_tensor=None, doping_levels=False, kl_coeff=1.0):
538
"""
539
Get thermoelectric figure of merit (ZT).
540
541
Returns:
542
dict: ZT data
543
"""
544
```
545
546
```python { .api }
547
class BztTransportProperties:
548
"""
549
Transport properties calculated by BoltzTraP.
550
551
Parameters:
552
- complete_dos: Complete DOS object
553
- nelect: Number of electrons
554
- temperature: Temperature array
555
- doping: Doping concentration array
556
- mu_r: Chemical potential array
557
- seebeck: Seebeck coefficient data
558
- sigma: Conductivity data
559
- kappa: Thermal conductivity data
560
- hall: Hall coefficient data
561
- structure: Associated structure
562
"""
563
def __init__(self, complete_dos, nelect, temperature=None, doping=None,
564
mu_r=None, seebeck=None, sigma=None, kappa=None,
565
hall=None, structure=None): ...
566
567
def check_acc_bzt_bands(self, args):
568
"""
569
Check accuracy of BoltzTraP band interpolation.
570
571
Returns:
572
dict: Accuracy metrics
573
"""
574
575
@property
576
def doping(self):
577
"""Doping concentration array."""
578
579
@property
580
def mu_doping(self):
581
"""Chemical potential vs doping."""
582
583
@property
584
def mu_r(self):
585
"""Reduced chemical potential array."""
586
587
@property
588
def seebeck_doping(self):
589
"""Seebeck coefficient vs doping."""
590
591
@property
592
def sigma_doping(self):
593
"""Conductivity vs doping."""
594
595
@property
596
def kappa_doping(self):
597
"""Thermal conductivity vs doping."""
598
599
@property
600
def hall_doping(self):
601
"""Hall coefficient vs doping."""
602
603
@property
604
def power_factor_doping(self):
605
"""Power factor vs doping."""
606
607
@property
608
def zt_doping(self):
609
"""ZT vs doping."""
610
611
@property
612
def average_eff_mass_doping(self):
613
"""Average effective mass vs doping."""
614
615
@property
616
def seebeck_eff_mass_doping(self):
617
"""Seebeck effective mass vs doping."""
618
```
619
620
### COHP Analysis
621
622
Crystal Orbital Hamilton Population analysis for chemical bonding insights.
623
624
```python { .api }
625
class Cohp:
626
"""
627
Crystal Orbital Hamilton Population data.
628
629
Parameters:
630
- efermi: Fermi energy
631
- energies: Energy array
632
- cohp: COHP values by spin {Spin: array}
633
- are_coops: Whether data represents COOP instead of COHP
634
- icohp: Integrated COHP values by spin
635
"""
636
def __init__(self, efermi, energies, cohp, are_coops=False, icohp=None): ...
637
638
def get_interpolated_value(self, energy, integrated=False):
639
"""
640
Get interpolated COHP value at given energy.
641
642
Parameters:
643
energy: Energy in eV
644
integrated: Whether to return integrated COHP
645
646
Returns:
647
dict: COHP values by spin
648
"""
649
650
def get_icohp(self, spin=None, integrated=True):
651
"""
652
Get integrated COHP up to Fermi level.
653
654
Parameters:
655
spin: Specific spin channel
656
integrated: Whether to return integrated values
657
658
Returns:
659
dict or float: Integrated COHP values
660
"""
661
662
@property
663
def energies(self):
664
"""Energy array."""
665
666
@property
667
def cohp(self):
668
"""COHP values by spin."""
669
670
@property
671
def icohp(self):
672
"""Integrated COHP values."""
673
```
674
675
```python { .api }
676
class CompleteCohp:
677
"""
678
Complete COHP analysis with bond-resolved data.
679
680
Parameters:
681
- structure: Associated structure
682
- avg_cohp: Average COHP
683
- cohp_dict: COHP data by bond label
684
- bonds: Bond information dictionary
685
- are_coops: Whether data represents COOP
686
- orb_res_cohp: Orbital-resolved COHP data
687
"""
688
def __init__(self, structure, avg_cohp, cohp_dict, bonds=None,
689
are_coops=False, orb_res_cohp=None): ...
690
691
def get_cohp_by_label(self, label, summed_spin_channels=False):
692
"""
693
Get COHP data for a specific bond label.
694
695
Parameters:
696
label: Bond label string
697
summed_spin_channels: Whether to sum spin channels
698
699
Returns:
700
Cohp: COHP object for the bond
701
"""
702
703
def get_orbital_resolved_cohp(self, label, orbitals, summed_spin_channels=False):
704
"""
705
Get orbital-resolved COHP for a bond.
706
707
Parameters:
708
label: Bond label
709
orbitals: Orbital specification
710
summed_spin_channels: Whether to sum spin channels
711
712
Returns:
713
Cohp: Orbital-resolved COHP
714
"""
715
716
def get_summed_cohp_by_label_list(self, label_list, divisor=1,
717
summed_spin_channels=False):
718
"""
719
Get summed COHP for multiple bond labels.
720
721
Parameters:
722
label_list: List of bond labels
723
divisor: Divisor for averaging
724
summed_spin_channels: Whether to sum spin channels
725
726
Returns:
727
Cohp: Summed COHP object
728
"""
729
730
def get_summed_cohp_by_label_and_orbital_list(self, label_list, orbital_list,
731
divisor=1, summed_spin_channels=False):
732
"""
733
Get summed orbital-resolved COHP.
734
735
Parameters:
736
label_list: List of bond labels
737
orbital_list: List of orbitals
738
divisor: Divisor for averaging
739
summed_spin_channels: Whether to sum spin channels
740
741
Returns:
742
Cohp: Summed orbital-resolved COHP
743
"""
744
745
@property
746
def bonds(self):
747
"""Bond information dictionary."""
748
749
@property
750
def all_cohps(self):
751
"""All COHP data by label."""
752
```
753
754
### Plotting and Visualization
755
756
Classes for plotting electronic structure data.
757
758
```python { .api }
759
class BSPlotter:
760
"""
761
Band structure plotting utility.
762
763
Parameters:
764
- bs: BandStructure object to plot
765
"""
766
def __init__(self, bs): ...
767
768
def get_plot(self, zero_to_efermi=True, ylim=None, smooth=False,
769
vbm_cbm_marker=False, smooth_tol=None, smooth_k=None,
770
bs_labels=None, plot_negative=None):
771
"""
772
Get matplotlib plot object for band structure.
773
774
Parameters:
775
zero_to_efermi: Whether to set Fermi level to zero
776
ylim: Y-axis limits
777
smooth: Whether to smooth bands
778
vbm_cbm_marker: Whether to mark VBM/CBM
779
smooth_tol: Smoothing tolerance
780
smooth_k: Smoothing parameter
781
bs_labels: Custom band labels
782
plot_negative: Whether to plot negative eigenvalues
783
784
Returns:
785
matplotlib.pyplot: Plot object
786
"""
787
788
def show(self, zero_to_efermi=True, ylim=None, smooth=False,
789
vbm_cbm_marker=False, smooth_tol=None, smooth_k=None):
790
"""
791
Show band structure plot.
792
"""
793
794
def save_plot(self, filename, img_format="eps", **kwargs):
795
"""
796
Save band structure plot to file.
797
798
Parameters:
799
filename: Output filename
800
img_format: Image format (eps, png, pdf, etc.)
801
"""
802
803
def get_ticks(self):
804
"""
805
Get k-point ticks for plotting.
806
807
Returns:
808
dict: K-point labels and positions
809
"""
810
```
811
812
```python { .api }
813
class DosPlotter:
814
"""
815
Density of states plotting utility.
816
817
Parameters:
818
- zero_at_efermi: Whether to set Fermi level to zero
819
- stack: Whether to stack DOS plots
820
"""
821
def __init__(self, zero_at_efermi=True, stack=False): ...
822
823
def add_dos(self, label, dos):
824
"""
825
Add DOS to plotter.
826
827
Parameters:
828
label: Label for the DOS
829
dos: Dos object
830
"""
831
832
def add_dos_dict(self, dos_dict, key_sort_func=None):
833
"""
834
Add dictionary of DOS objects.
835
836
Parameters:
837
dos_dict: Dictionary of {label: Dos}
838
key_sort_func: Function for sorting keys
839
"""
840
841
def get_plot(self, xlim=None, ylim=None, invert_axes=False,
842
beta_dashed=False, sigma=None):
843
"""
844
Get matplotlib plot for DOS.
845
846
Parameters:
847
xlim: X-axis limits
848
ylim: Y-axis limits
849
invert_axes: Whether to invert x and y axes
850
beta_dashed: Whether to use dashed lines for spin-down
851
sigma: Gaussian broadening parameter
852
853
Returns:
854
matplotlib.pyplot: Plot object
855
"""
856
857
def show(self, xlim=None, ylim=None, **kwargs):
858
"""Show DOS plot."""
859
860
def save_plot(self, filename, img_format="eps", xlim=None, ylim=None, **kwargs):
861
"""Save DOS plot to file."""
862
```
863
864
```python { .api }
865
class CohpPlotter:
866
"""
867
COHP plotting utility.
868
869
Parameters:
870
- zero_at_efermi: Whether to set Fermi level to zero
871
- are_coops: Whether data represents COOP
872
"""
873
def __init__(self, zero_at_efermi=True, are_coops=False): ...
874
875
def add_cohp(self, label, cohp):
876
"""
877
Add COHP to plotter.
878
879
Parameters:
880
label: Label for COHP
881
cohp: Cohp object
882
"""
883
884
def add_cohp_dict(self, cohp_dict, key_sort_func=None):
885
"""
886
Add dictionary of COHP objects.
887
888
Parameters:
889
cohp_dict: Dictionary of {label: Cohp}
890
key_sort_func: Function for sorting keys
891
"""
892
893
def get_plot(self, xlim=None, ylim=None, plot_negative=None,
894
integrated=False, invert_axes=False, sigma=None):
895
"""
896
Get matplotlib plot for COHP.
897
898
Parameters:
899
xlim: X-axis limits
900
ylim: Y-axis limits
901
plot_negative: Whether to plot negative COHP
902
integrated: Whether to plot integrated COHP
903
invert_axes: Whether to invert axes
904
sigma: Gaussian broadening
905
906
Returns:
907
matplotlib.pyplot: Plot object
908
"""
909
910
def show(self, xlim=None, ylim=None, **kwargs):
911
"""Show COHP plot."""
912
913
def save_plot(self, filename, img_format="eps", **kwargs):
914
"""Save COHP plot to file."""
915
```