tkbandstructure.py の技術ドキュメント

このドキュメントは、Pythonライブラリ tkbandstructure.py の機能、使用方法、および内部構造を詳細に説明します。

ライブラリの機能や目的

tkbandstructure.py は、計算化学や物性物理学の分野で得られる電子バンド構造を視覚的に表現するためのPythonライブラリです。特に、Matplotlibと連携してバンド構造図を簡単にプロットすることを目的としています。

主な機能は以下の通りです。

バンド構造のプロット: k点パスに沿った電子のエネルギーバンドを Matplotlib の Axes オブジェクト上に描画します。
スピン分極のサポート: スピンアップとスピンダウンのバンドを個別に、または占有数に応じて異なる色でプロットする機能を提供します。
重要なエネルギー準位の表示: 価電子帯上限 ($E_V$)、伝導帯下端 ($E_C$)、フェルミ準位 ($E_F$)、HOMO ($E_{HOMO}$)、LUMO ($E_{LUMO}$) などの重要なエネルギー準位を破線でプロットできます。
k点経路の視覚化: 高対称点などのk点境界を垂直線で示し、対応するk点名を軸ラベルとして表示します。
占有数に応じた色分け: バンドの占有数に基づいて、プロットされるマーカーの色を濃淡で表現する機能を提供します。これにより、バンドの占有状態を一目で把握できます。

このライブラリは、計算結果の解析やプレゼンテーション資料の作成において、クリアで情報 rich なバンド構造図を迅速に生成することで、研究者の作業を支援します。

importする方法

tkbandstructure.py を他のPythonプログラムから利用するには、標準的な import 文を使用します。

ライブラリ全体を tkbandstructure という名前でインポートする場合：

import tkbandstructure

この方法でインポートした場合、plot_band 関数は tkbandstructure.plot_band(...) のように呼び出します。

あるいは、plot_band 関数だけを直接インポートすることも可能です：

from tkbandstructure import plot_band

この方法でインポートした場合、plot_band 関数は plot_band(...) のように直接呼び出せます。

必要な非標準ライブラリとインストール方法

tkbandstructure.py は以下の非標準ライブラリに依存しています。

NumPy: 数値計算を効率的に行うためのライブラリです。特に、配列操作や数学関数に利用されます。
tklib: このライブラリの作者が開発したユーティリティライブラリです。tkObject, tkutils, tkre モジュールから様々な補助関数やクラスをインポートしています。
Matplotlib: バンド構造のプロットを行うために不可欠です。plot_band 関数は Matplotlib の pyplot モジュールと Axes オブジェクトを引数として受け取ります。

これらのライブラリは pip コマンドを使用してインストールできます。

NumPy のインストール:
```
pip install numpy
```
Matplotlib のインストール:
```
pip install matplotlib
```
tklib のインストール: tklib はpypiに公開されている標準的なライブラリではない可能性があります。もし公開されている場合は以下のコマンドでインストールします。公開されていない場合は、ソースコードを入手し、Pythonのパスが通っている場所に配置するか、現在のプロジェクトディレクトリにコピーして使用する必要があります。
```
# もしtklibがpipでインストール可能な場合
pip install tklib
```
tklib のモジュール tkobject, tkutils, tkre が利用可能な状態になっている必要があります。

importできる変数と関数

tkbandstructure.py ライブラリから外部に公開されている主な要素は以下の関数です。変数として明示的にエクスポートされているものはありません。

関数

`plot_band`

バンド構造（エネルギーバンド図）をMatplotlibの Axes オブジェクト上にプロットします。フェルミ準位やHOMO/LUMO準位、k点経路の高対称点などを表示し、占有数に応じた色の濃淡表現もサポートします。

動作:

この関数は、与えられたk点経路上のエネルギー値 (yEup, yEdn) を Matplotlib の Axes オブジェクト (axis) にプロットします。指定された場合、価電子帯上限 ($E_V$)、伝導帯下端 ($E_C$)、フェルミ準位 ($E_F$)、HOMO ($E_{HOMO}$)、LUMO ($E_{LUMO}$) などの重要なエネルギー準位を水平の破線で描画します。また、ktotallist と ktotal_namelist を使用して、k点経路の高対称点を縦線とX軸のラベルとして表示します。

occups または occdns が提供された場合、バンドの占有数 (ne) に応じてマーカーの色を動的に変更します。nmax で定義された最大占有数に基づいて、0から15までのインデックスが計算され、16進数の文字リスト (convchar) を用いて色コードが生成されます。これにより、占有数の多いバンドは濃い色、少ないバンドは薄い色で表現されます。

引数:

plt: Matplotlibの pyplot モジュール、または setp メソッドを持つオブジェクト。主にX軸の目盛りとラベルを設定するために使用されます。
axis: バンド構造が描画される Matplotlib の Axes オブジェクト。
ISPIN: スピンの情報を区別するかどうかを示す整数。1 の場合、スピン非分極（スピンアップバンドのみ表示）、2 の場合、スピン分極（スピンアップとスピンダウンバンドの両方表示）と解釈されます。
xk: k点サンプリング経路の蓄積距離（最初のk点からの距離の合計）のリスト。X軸の値として使用されます。
yEup: スピンアップ（またはスピン非分極）バンドのエネルギー値のリスト。各要素は特定のk点における複数のバンドエネルギーを含むリスト（例: [[E1_k1, E2_k1], [E1_k2, E2_k2], ...]）であるか、単一の次元のリスト（例: [E_k1, E_k2, ...]）も可能です。
yEdn: スピンダウンバンドのエネルギー値のリスト。ISPIN が 2 の場合にのみ使用されます。構造は yEup と同じです。
Erange: バンド構造図のY軸の表示範囲を指定する2要素のリスト [E_min, E_max]。
occups: スピンアップ（またはスピン非分極）バンドの各エネルギー準位の占有数を示すリスト。yEup と同じ構造を持ちます。None の場合、占有数による色分けは行われず、color 引数で指定された色が使用されます。
occdns: スピンダウンバンドの占有数を示すリスト。ISPIN が 2 で occups が None でない場合にのみ使用されます。構造は yEdn と同じです。
ktotallist: k点経路上の高対称点（やその他の重要な点）における蓄積距離のリスト。これらの位置に垂直な罫線が引かれます。
ktotal_namelist: ktotallist に対応するk点名称のリスト。X軸の目盛りラベルとして使用されます。
nmax: 占有数による色分けを行う際の、占有数の最大値。占有数は $0$ から nmax の範囲で正規化されます。
EV: 価電子帯上限 ($E_V$) のエネルギー値。指定された場合、水平な破線でプロットされます。
EC: 伝導帯下端 ($E_C$) のエネルギー値。指定された場合、水平な破線でプロットされます。
EF: フェルミ準位 ($E_F$) のエネルギー値。指定された場合、水平な破線でプロットされます。
EHOMO: HOMO (Highest Occupied Molecular Orbital) のエネルギー値。指定された場合、水平な破線でプロットされます。
ELUMO: LUMO (Lowest Unoccupied Molecular Orbital) のエネルギー値。指定された場合、水平な破線でプロットされます。
EVlabel: $E_V$ を示す破線の凡例テキスト。デフォルトは '$E_V$'。
EClabel: $E_C$ を示す破線の凡例テキスト。デフォルトは '$E_C$'。
EFlabel: $E_F$ を示す破線の凡例テキスト。デフォルトは '$E_F$'。
EHOMOlabel: $E_{HOMO}$ を示す破線の凡例テキスト。デフォルトは '$E_{HOMO}$'。
ELUMOlabel: $E_{LUMO}$ を示す破線の凡例テキスト。デフォルトは '$E_{LUMO}$'。
marker: バンドプロットに使用するMatplotlibマーカーのスタイル。デフォルトは 'o'。
linestyle: バンドプロットに使用するMatplotlibラインスタイル。デフォルトは '' (線なし)。
color: バンドプロットの基本色。occups が None の場合に適用されます。デフォルトは 'black'。
linewidth: バンドプロットの線の太さ。デフォルトは 0.3。
markersize: バンドプロットのマーカーサイズ。デフォルトは 2.0。
markeredgewidth: バンドプロットのマーカーエッジの太さ。デフォルトは 0.5。
legendloc: 凡例の位置。Matplotlibの legend 関数の loc 引数と同じ。デフォルトは 'best'。
fontsize: 軸ラベルのフォントサイズ。デフォルトは 16。
labelsize: 軸目盛りのラベルサイズ。デフォルトは 12。
legend_fontsize: 凡例のフォントサイズ。デフォルトは 12。

戻り値:

なし。axis オブジェクトに直接プロットを描画します。

main scriptとして実行したときの動作

tkbandstructure.py はライブラリとして機能するように設計されており、if __name__ == "__main__": ブロックを含んでいません。したがって、このスクリプトを直接実行しても、何も特別な動作は行われません。通常は、他のPythonスクリプトから import して plot_band 関数を呼び出す形で利用されます。