tkboltztrap.py 技術ドキュメント
ライブラリの機能や目的
tkboltztrap.py ライブラリは、第一原理計算に基づく熱電輸送特性計算ソフトウェアである BoltzTraP の計算結果を解析・処理するためのツール群を提供します。具体的には、BoltzTraPが出力する様々なファイル（.outputtrans, .transdos, .trace, .condtens, .halltens など）を読み込み、そこから伝導率、ゼーベック係数、熱伝導率、ホール係数などの物理量を抽出・整形する機能を提供します。
さらに、このライブラリは、VASP（Vienna Ab initio Simulation Package）などの第一原理計算コードの出力ファイル（DOSCAR, EIGENVAL など）を読み込み、バンド構造情報（DOS、バンドエッジ、フェルミエネルギーなど）を解析する機能も備えています。これにより、BoltzTraP計算の入力準備や結果の物理的な解釈を支援し、熱電材料の特性評価ワークフローを効率化することを目的としています。
このライブラリは、主にtkBoltzTraPクラスを中心に構成されており、熱電輸送特性のデータ処理をオブジェクト指向的に行うことができます。
importする方法
このライブラリの主要なクラスである tkBoltzTraP を他のPythonプログラムからインポートするには、以下のいずれかの方法を使用します。
特定のクラスをインポートする場合:
from tkboltztrap import tkBoltzTraP
ライブラリ全体をインポートし、tkboltztrap. プレフィックスを付けてクラスにアクセスする場合:
import tkboltztrap
# クラスを使用する際は tkboltztrap.tkBoltzTraP() のように記述します
必要な非標準ライブラリとインストール方法
tkboltztrap.py が依存する非標準ライブラリは以下の通りです。
numpy: 数値計算を効率的に行うためのライブラリ。
tklib: このライブラリと同じプロジェクトで開発されたカスタムライブラリ。
tkobject,tkutils,tkre,tkfile,tkcrystal,tkprogvars,tkinifile,tksci,tktransportなどのモジュールが含まれています。
インストール方法:
numpy:
pipを使用してインストールできます。pip install numpy
tklib:
tklibはカスタムライブラリであるため、pipで直接インストールすることはできません。tkboltztrap.pyと同じディレクトリ、またはPythonのパス（PYTHONPATH）が通った場所にtklibディレクトリを配置する必要があります。通常、tklibはtkboltztrap.pyが含まれるプロジェクトのルートディレクトリに存在すると想定されます。
importできる変数と関数
tkboltztrap.py は、主に tkBoltzTraP という単一のクラスをエクスポートします。トップレベルで直接インポートできる変数や関数はありません。すべての機能は tkBoltzTraP クラスのインスタンスを通じて利用されます。
クラス: tkBoltzTraP
tkCrystalObject を継承しており、結晶構造に関する基本的な機能も利用できます。BoltzTraPの計算結果ファイルやVASPの出力ファイルを解析するためのメソッドを提供します。
メソッド
__init__(self, **args)動作:
tkBoltzTraPオブジェクトのコンストラクタです。作業ディレクトリ、結晶情報、VASPの入力/出力ファイル情報（INCAR, KPOINTS, OUTCAR, EIGENVALなど）を初期化します。引数:
**args: オブジェクトの属性を初期化するためのキーワード引数。例えばworkdir='path/to/dir'など。
戻り値: なし
__del__(self)動作: デストラクタです。現在の実装では何も行いません。
__str__(self)動作: オブジェクトのクラスパスを文字列として返します。
引数: なし
戻り値:
str- クラスのフルパス名。
get_path(self, filebody, dir=None)動作: 指定されたディレクトリ内に存在するファイル名の完全パスを生成します。
dirが指定されない場合、オブジェクトのworkdir属性を使用します。引数:
filebody(str): ファイルの基本名（拡張子を含む）。dir(str, オプション): ファイルが存在するディレクトリのパス。デフォルトはNone。
戻り値:
str- 生成された完全ファイルパス。
get_intranspath(self, filebody, dir=None)動作: BoltzTraPの入力ファイルである
.intransファイルの完全パスを生成します。引数:
filebody(str): ファイルの基本名。dir(str, オプション): ファイルが存在するディレクトリのパス。デフォルトはNone。
戻り値:
str-.intransファイルの完全パス。
get_outputtranspath(self, filebody, dir=None)動作: BoltzTraPの出力ファイルである
.outputtransファイルの完全パスを生成します。引数:
filebody(str): ファイルの基本名。dir(str, オプション): ファイルが存在するディレクトリのパス。デフォルトはNone。
戻り値:
str-.outputtransファイルの完全パス。
get_transdospath(self, filebody, dir=None)動作: BoltzTraPのDOSファイルである
.transdosファイルの完全パスを生成します。引数:
filebody(str): ファイルの基本名。dir(str, オプション): ファイルが存在するディレクトリのパス。デフォルトはNone。
戻り値:
str-.transdosファイルの完全パス。
get_tracepath(self, filebody, dir=None)動作: BoltzTraPのバンド補間ファイルである
.traceファイルの完全パスを生成します。引数:
filebody(str): ファイルの基本名。dir(str, オプション): ファイルが存在するディレクトリのパス。デフォルトはNone。
戻り値:
str-.traceファイルの完全パス。
get_condtenspath(self, filebody, dir=None)動作: BoltzTraPの伝導率テンソルファイルである
.condtensファイルの完全パスを生成します。引数:
filebody(str): ファイルの基本名。dir(str, オプション): ファイルが存在するディレクトリのパス。デフォルトはNone。
戻り値:
str-.condtensファイルの完全パス。
get_halltenspath(self, filebody, dir=None)動作: BoltzTraPのホールテンソルファイルである
.halltensファイルの完全パスを生成します。引数:
filebody(str): ファイルの基本名。dir(str, オプション): ファイルが存在するディレクトリのパス。デフォルトはNone。
戻り値:
str-.halltensファイルの完全パス。
get_labels(self, latex_style=0)動作: BoltzTraPの出力ファイル（例:
.condtens）のデータ列に対応するラベルのリストを返します。LaTeX形式での表記も選択可能です。引数:
latex_style(int, オプション): 1を指定するとLaTeX形式のラベルを返します。デフォルトは0。
戻り値:
list- ラベルの文字列リスト。例:EF,T,N,sigmaxx,Sxx,kxxなど。
get_Tlist(self, data_list)動作: BoltzTraPの出力データリストから、ユニークな温度値のリストを抽出します。
引数:
data_list(list): BoltzTraPから読み込んだ生データのリスト（通常、read_btoutputの戻り値の一部）。
戻り値:
tuple- (ユニークな温度値の数, ユニークな温度値のリスト)。
get_EFlist(self, data_list)動作: BoltzTraPの出力データリストから、ユニークなフェルミエネルギー値のリストを抽出します。
引数:
data_list(list): BoltzTraPから読み込んだ生データのリスト。
戻り値:
tuple- (ユニークなフェルミエネルギー値の数, ユニークなフェルミエネルギー値のリスト)。
get_halltens_labels(self, latex_style=0)動作: BoltzTraPのホールテンソル出力のデータ列に対応するラベルのリストを返します。
引数:
latex_style(int, オプション): 現在のところ、この引数は使用されていません（常に非LaTeX形式のラベルを返します）。
戻り値:
list- ホールテンソル成分のラベルリスト。例:EF,T,N,RHxxxなど。
get_condtens_labels(self, latex_style=0)動作: BoltzTraPの伝導率テンソル、ゼーベック係数、熱伝導率の出力データ列に対応するラベルのリストを返します。LaTeX形式での表記も選択可能です。
引数:
latex_style(int, オプション): 1を指定するとLaTeX形式のラベルを返します。デフォルトは0。
戻り値:
list- 伝導率、ゼーベック係数、熱伝導率成分のラベルリスト。例:EF,T,N,sigmaxx,Sxx,kxxなど。
extract_data(self, labels, T_list, data_list, Vcell, mode)動作:
read_btoutputによって読み込まれた生データから、指定されたモード（'all','sigma','S','kappa','RH','dos'）に基づいて特定のデータを抽出し、整形します。キャリア濃度を単位体積あたりに変換します。引数:
labels(list): データ列のラベルリスト。T_list(list): ユニークな温度値のリスト。data_list(list):read_btoutputから得られた生データ。Vcell(float): 単位セルの体積（Å\(^3\)）。キャリア濃度を \(/cm^3\) に変換するために使用されます。mode(str): 抽出するデータの種類を指定します。'all','sigma','S','kappa','RH','dos'のいずれか。
戻り値:
tuple-(EF, T_list_copy, Ncm3, data, plabels)EF(numpy.ndarray): フェルミエネルギーの配列。T_list_copy(list): 温度のリスト。Ncm3(numpy.ndarray): キャリア濃度（\(cm^{-3}\)）。data(numpy.ndarray): 抽出された物理量データ（伝導率、ゼーベック係数など）。plabels(list): 抽出されたデータのラベルリスト。
read_btoutput(self, infile, E0=0.0, normalize_E=True, unit='/cm3', EFmin=None, EFmax=None, print_level=1, usage=None, exit_by_error=True)動作: BoltzTraPの汎用的な出力ファイル（
.condtens,.halltens,.traceなど）を読み込み、ヘッダーとデータのリストを返します。フェルミエネルギーの正規化や範囲指定が可能です。引数:
infile(str): 読み込むファイルパス。E0(float, オプション): フェルミエネルギーの基準値（Ry単位）。正規化 (normalize_E=True) の際に差し引かれます。デフォルトは0.0。normalize_E(bool, オプション): フェルミエネルギーをE0で正規化するかどうか。デフォルトはTrue。unit(str, オプション): 現在のところ、この引数は直接使用されていません。EFmin(float, オプション): 読み込むフェルミエネルギーの最小値（eV）。EFmax(float, オプション): 読み込むフェルミエネルギーの最大値（eV）。print_level(int, オプション): デバッグ出力のレベル。デフォルトは1。usage(any, オプション): エラー発生時に表示する使用方法メッセージ。exit_by_error(bool, オプション): ファイル読み込みエラー時にプログラムを終了するかどうか。デフォルトはTrue。
戻り値:
tuple-(header, data_list)header(list): ファイルのヘッダー行を分割したリスト。data_list(list): 各列のデータを格納したリストのリスト。
read_intrans(self, infile, exit_by_error=True)動作: BoltzTraPの入力ファイルである
.intransファイルを読み込み、その設定を辞書形式で返します。引数:
infile(str): 読み込む.intransファイルパス。exit_by_error(bool, オプション): ファイル読み込みエラー時にプログラムを終了するかどうか。デフォルトはTrue。
戻り値:
dict-.intransファイルの設定情報。キーはinterface,iskip,idebug,setgap,shiftgap,CALC,run_mode,EF_range,Tmax,Tstep,Erange_bands,LastLineなど。
read_outputtrans(self, infile, exit_by_error=True)動作: BoltzTraPの出力ファイルである
.outputtransファイルを読み込み、主要なサマリー情報を辞書形式で返します。引数:
infile(str): 読み込む.outputtransファイルパス。exit_by_error(bool, オプション): ファイル読み込みエラー時にプログラムを終了するかどうか。デフォルトはTrue。
戻り値:
dict-.outputtransファイルから抽出された情報。キーはcase,Bandstyle,Set_fermi,FermiE,Run_type,Calc_type,nkpts,Eg,EVBM,ECBM,EF,KXMAX,KYMAX,KZMAX,GMAXなど。
read_transdos(self, infile, Vcell, SpinPolarized=False, E0=None, normalize_E=True, unit='/cm3', Emin=None, Emax=None, print_level=1, usage=None, exit_by_error=True)動作: BoltzTraPのDOSファイルである
.transdosファイルを読み込み、エネルギー、DOS、キャリア濃度を返します。DOSとキャリア濃度は単位体積あたりに変換できます。引数:
infile(str): 読み込む.transdosファイルパス。Vcell(float): 単位セルの体積（Å\(^3\)）。DOSやキャリア濃度を \(/cm^3\) に変換するために使用されます。SpinPolarized(bool, オプション): スピン偏極計算であるかどうか。デフォルトはFalse。E0(float, オプション): フェルミエネルギーの基準値（eV）。正規化 (normalize_E=True) の際に差し引かれます。デフォルトはNone。normalize_E(bool, オプション): エネルギーをE0で正規化するかどうか。デフォルトはTrue。unit(str, オプション): DOSの単位を指定します。'/cm3'の場合、\(/cm^3\) 単位に変換されます。unit_N(str, オプション): キャリア濃度の単位を指定します。'/cm3'の場合、\(/cm^3\) 単位に変換されます。Emin(float, オプション): 読み込むエネルギーの最小値（eV）。Emax(float, オプション): 読み込むエネルギーの最大値（eV）。print_level(int, オプション): デバッグ出力のレベル。デフォルトは1。usage(any, オプション): エラー発生時に表示する使用方法メッセージ。exit_by_error(bool, オプション): ファイル読み込みエラー時にプログラムを終了するかどうか。デフォルトはTrue。
戻り値:
dict- 読み込まれた情報。キーはEstart,Eend,Estep,nE,xE(エネルギー),dos(DOS),yNcm3(キャリア濃度) など。
read_trace(self, infile, Vcell, E0=None, normalize_E=True, unit='/cm3', EFmin=None, EFmax=None, print_level=1, usage=None, exit_by_error=True)動作: BoltzTraPの
.traceファイルを読み込み、DOSに関するデータを抽出して返します。read_btoutputとextract_dataを内部で呼び出します。引数:
read_btoutputおよびread_transdosと同様。戻り値:
dict- 読み込まれた情報。キーはheader,data_list,labels,ncolumns,ndata,nT,T_list,nEF,EF_list,xEF,xT,yNcm3,dos,dos_labelなど。
read_condtens(self, infile, Vcell, E0=None, normalize_E=True, unit='/cm3', EFmin=None, EFmax=None, print_level=1, usage=None, exit_by_error=True)動作: BoltzTraPの
.condtensファイルを読み込み、伝導率、ゼーベック係数、熱伝導率に関するデータを抽出して返します。read_btoutputとextract_dataを内部で呼び出します。引数:
read_btoutputと同様。戻り値:
dict- 読み込まれた情報。キーはheader,data_list,labels,ncolumns,ndata,nT,T_list,nEF,EF_list,xEF,xT,yNcm3,sigma(伝導率),sigma_label,S(ゼーベック係数),S_label,kappa(熱伝導率),kappa_labelなど。
read_halltens(self, infile, Vcell, E0=None, normalize_E=True, unit='/cm3', EFmin=None, EFmax=None, print_level=1, usage=None, exit_by_error=True)動作: BoltzTraPの
.halltensファイルを読み込み、ホールテンソルに関するデータを抽出して返します。read_btoutputとextract_dataを内部で呼び出します。引数:
read_btoutputと同様。戻り値:
dict- 読み込まれた情報。キーはheader,data_list,labels,ncolumns,ndata,nT,T_list,nEF,EF_list,xEF,xT,yNcm3,RH(ホールテンソル),RH_labelなど。
getdir(self, path)動作: 与えられたパスがディレクトリであればそのパスを、ファイルであればそのファイルが存在するディレクトリのパスを返します。
引数:
path(str): ファイルまたはディレクトリのパス。
戻り値:
str- ディレクトリのパス。
get_INCAR(self, CAR_dir)動作: 指定されたディレクトリ内の
INCARファイルのパスを生成します。引数:
CAR_dir(str): VASPの入力ファイルが格納されているディレクトリのパス。
戻り値:
str-INCARファイルの完全パス。
find_band_edges_from_dos(self, E, DOS, EF0=0.0, DOSth=1.0e18)動作: DOS（状態密度）データから価電子帯上端（VBM）と伝導帯下端（CBM）を推定します。フェルミエネルギー
EF0を基準として、指定されたDOSスレッショルドDOSthを超える最小/最大のエネルギーをバンドエッジと見なします。引数:
E(listornumpy.ndarray): エネルギーのリストまたは配列（eV）。DOS(listornumpy.ndarray): 状態密度のリストまたは配列。EF0(float, オプション): フェルミエネルギーの基準値（eV）。デフォルトは0.0。DOSth(float, オプション): バンドエッジを決定するためのDOSのスレッショルド値。デフォルトは \(1.0 \times 10^{18}\)。
戻り値:
tuple-(EV, EC)EV(float): 価電子帯上端（VBM）のエネルギー（eV）。EC(float): 伝導帯下端（CBM）のエネルギー（eV）。
find_band_edges_from_eigenval(self, EF0=0.0, eigenvalinf=None, ISPIN=None)動作: VASPのEIGENVALファイルから読み込んだバンドエネルギー情報に基づいて、価電子帯上端（VBM）と伝導帯下端（CBM）を推定します。
引数:
EF0(float, オプション): フェルミエネルギーの基準値（eV）。デフォルトは0.0。eigenvalinf(dict, オプション):read_eigenvalメソッドによって読み込まれたEIGENVALの情報辞書。デフォルトはオブジェクトのeigenvalinf属性。ISPIN(int, オプション): スピン偏極計算かどうか（1: 非スピン偏極, 2: スピン偏極）。デフォルトはオブジェクトのoutcarinf["ISPIN"]またはincarinf["ISPIN"]。
戻り値:
dict- バンドエッジに関する情報。キーはEV(VBM),EC(CBM),Eg(バンドギャップ \(EC - EV\)),EF0,EHOMO,ELUMOなど。
read_doscar(self, DOSCAR_path, cry=None, IsSpinPolarized=None, IsNonCollinear=None, EF=None, unit='')動作: VASPの
DOSCARファイルを読み込み、総状態密度（Total DOS）とキャリア濃度（Total N）に関するデータを抽出します。スピン偏極計算に対応し、DOSとキャリア濃度を単位体積あたりに変換するオプションも提供します。引数:
DOSCAR_path(str):DOSCARファイルのパス。cry(tkCrystal, オプション): 結晶オブジェクト。単位セルの体積計算に使用されます。デフォルトはオブジェクトのcrystal属性。IsSpinPolarized(bool, オプション): スピン偏極計算であるかどうか。デフォルトはオブジェクトのoutcarinf["ISPIN"]。IsNonCollinear(bool, オプション): 非共線計算であるかどうか。デフォルトはオブジェクトのcry.outcarinf["LCOLLINEAR"]。EF(float, オプション): フェルミエネルギーの基準値（eV）。読み込んだエネルギーをEFで正規化するために使用されます。デフォルトはオブジェクトのoutcarinf["EF"]。unit(str, オプション): DOSおよびキャリア濃度の単位を指定します。'/cm3'の場合、\(/cm^3\) 単位に変換されます。
戻り値:
dict- 読み込まれた情報。キーはnE,E(エネルギー),TotalDOS(総DOS),TotalDOSup(スピンアップDOS),TotalDOSdn(スピンダウンDOS),Ne(総キャリア濃度),Neup(スピンアップキャリア濃度),Nedn(スピンダウンキャリア濃度) など。
read_files(self, file, file_types, exit_by_error=False, print_level=0, terminate=None)動作: VASP関連の複数のファイル（
INCAR,POSCAR,POTCAR,CONTCAR,OUTCAR,EIGENVAL,DOSCAR）をまとめて読み込むための汎用的なメソッドです。引数:
file(str): 基準となるファイルパス（例: いずれかのVASPファイルのパス）。このパスからディレクトリが特定されます。file_types(list): 読み込みたいファイルの種類を文字列で指定したリスト（例:['INCAR', 'OUTCAR']）。exit_by_error(bool, オプション): ファイル読み込みエラー時にプログラムを終了するかどうか。デフォルトはFalse。print_level(int, オプション): デバッグ出力のレベル。デフォルトは0。terminate(callable, オプション): エラー時に呼び出される終了関数。デフォルトはtklib.tkutils.terminate。
戻り値:
dict- 読み込まれた各ファイルの情報が格納された辞書。キーは指定されたファイルタイプ（例:INCAR,OUTCARなど）。
main scriptとして実行したときの動作
tkboltztrap.py ライブラリは、Pythonの慣例である if __name__ == '__main__': ブロックを含んでいません。
したがって、このライブラリは、直接スクリプトとして実行された場合の特別な動作は定義されていません。通常は、他のPythonプログラムから tkBoltzTraP クラスをインポートして利用することを想定しています。