draw_band_fs プログラム仕様
バンド構造、状態密度 (DOS)、フェルミエネルギー (EF)、有効質量 (m*)、およびフェルミ面を 様々な次元とモデルでシミュレートしプロットするスクリプト。
詳細説明: このスクリプトは、1次元から3次元までの単純な電子モデル（自由電子、タイトバインディング、 またはほぼ自由電子）に基づき、以下の機能を提供する。 - バンド構造の計算とプロット（1D直線パスまたは高対称点パスに沿って）。 - DOSの計算とプロット（ガウスブロードニングまたはヒストグラム）。 - 電子数 nelec からDOS積分を通じてフェルミエネルギー EF を決定する機能、
または EF を固定値として指定する機能。
1Dバンドプロットに重ねて有効質量 m*(k) を表示する機能。
1D、2D、3Dのフェルミ面をプロットする機能（3Dにはscikit-imageが必要）。
利用可能なモデル: - 'free': 自由電子モデル。 - 'tb': タイトバインディングモデル。 - 'nfe': ほぼ自由電子 (NFE) モデル（逆格子ベクトル間のカップリングVを考慮）。
関連リンク: draw_band_fs.py Technical Document
- crystal.draw_band_fs.build_energy_grid_for_fs(args, dim: int)
フェルミ面プロットのためにエネルギーグリッドを構築する
詳細説明: 指定された次元 dim において、ブリルアンゾーン全体を格子状にサンプリングし、 特定のバンドインデックス args.fs_band のエネルギー値を計算してグリッドを構築します。 モデル ('tb', 'free', 'nfe') に応じてエネルギー計算が実行されます。 このグリッドはフェルミ面の等値面または等高線プロットの基盤となります。
- パラメータ:
args (argparse.Namespace) -- コマンドライン引数オブジェクト (res, fs_band, modeなどに必要)。
dim (int) -- 空間次元 (1, 2, or 3)。
- 戻り値:
k_range_int (np.ndarray): 各軸のk点範囲 (内部単位)。
E (np.ndarray): 計算されたエネルギーグリッド。次元に応じた形状。
- 戻り値の型:
tuple[np.ndarray, np.ndarray]
- 例外:
ValueError -- dim が1, 2, 3以外の場合。
- crystal.draw_band_fs.build_g_vecs(dim: int) ndarray
dim 次元の最小セットのG: 0 と ±e_i を物理単位で返す
詳細説明: 指定された次元における逆格子ベクトルGの最小セットを構築します。 これは、0ベクトルと、各軸方向の単位ベクトル (±e_i) を含みます。 結果は物理単位 (2π/a) に正規化されます。
- パラメータ:
dim (int) -- 空間次元 (1, 2, or 3)。
- 戻り値:
Gベクトル群の配列。各行がGベクトル。
- 戻り値の型:
np.ndarray
- crystal.draw_band_fs.build_k_path(points, labels, res_per_segment=40)
高対称点(points)をつなぐパスを生成する
詳細説明: 複数の高対称点 (points) を連続して結び、バンド図プロット用のKパスを構築します。 各パスセグメントは res_per_segment で指定された数のK点に分割されます。 K点ベクトル、Kパスに沿った累積距離、高対称点の位置とラベルを返します。
- パラメータ:
- 戻り値:
k_vecs (np.ndarray): パス上の全K点ベクトルの配列。
x_dist (np.ndarray): パス上のK点に対応する累積距離の配列。
x_nodes (list[float]): 高対称点に対応する累積距離のリスト。
labels (list[str]): 高対称点ラベルのリスト。
- 戻り値の型:
- crystal.draw_band_fs.compute_dos(E_samples: ndarray, nE: int, sigma: float, E_range, scale_states: float)
DOS をガウスブロードニングで作る
詳細説明: 与えられたエネルギーサンプル E_samples から、ガウスブロードニング またはヒストグラム法を用いて状態密度 (DOS) を計算します。 sigma が0以下の場合はヒストグラムとして計算され、それ以外の場合は ガウス関数を用いて平滑化されたDOSが計算されます。 結果のDOSは scale_states に正規化され、DOSの積分が scale_states に ほぼ等しくなります。
- パラメータ:
- 戻り値:
エネルギーグリッドと対応するDOS値の配列。
- 戻り値の型:
tuple[np.ndarray, np.ndarray]
- crystal.draw_band_fs.determine_energy_range(E_samples: ndarray, E_range_user=None)
エネルギー軸レンジを決める
詳細説明: プロットやDOS/EF計算のためのエネルギー軸の最小値と最大値を決定します。 ユーザーが E_range_user を指定した場合はそれを採用し、 指定がない場合は、提供されたエネルギーサンプル E_samples の 最小値と最大値に5%のパディングを加えて自動的に決定します。
- crystal.draw_band_fs.dim_from_type(t: str) int
プロットタイプ文字列から空間次元を決定する
詳細説明: コマンドライン引数で与えられたプロットタイプ文字列に基づいて、 対応する空間次元（1, 2, または 3）を返します。 例: "1dband" -> 1, "2dfs" -> 2。
- パラメータ:
t (str) -- プロットタイプを示す文字列 ('1dband', '2dband', '3dband', '1dfs', '2dfs', '3dfs')。
- 戻り値:
対応する空間次元。
- 戻り値の型:
- 例外:
ValueError -- 未知のプロットタイプが指定された場合。
- crystal.draw_band_fs.ef_from_dos(nelec: float, E_grid: ndarray, dos: ndarray, warn: bool = True) float
DOS を積分して N(E)=∫DOS dE を作り、N(EF)=nelec となる EF を内挿で求める。
詳細説明: 計算された状態密度 (DOS) をエネルギー E_grid に沿って積分し、 累積状態数 N(E) を構築します。 次に、指定された電子数 nelec に対応するフェルミエネルギー (EF) を N(E) から線形内挿で求めます。 nelec がDOSの積分範囲外にある場合、EFは範囲の端にクランプされ、 warn がTrueの場合は警告メッセージが表示されます。
- crystal.draw_band_fs.effective_mass_1d(k_int: ndarray, E: ndarray) ndarray
1Dパス上で有効質量 m*(k) = 1 / (d^2E/d(ka)^2) を数値評価。
詳細説明: 1次元パスに沿ったバンドエネルギー E とk点 k_int を用いて、 電子の有効質量 m*(k) を数値的に計算します。 有効質量は運動量 ka に対するエネルギーの二階微分 d^2E/d(ka)^2 の逆数として定義されます。 二階微分は中心差分法を用いて近似されます。k点数が少ない場合はNaNを返します。
- パラメータ:
k_int (np.ndarray) -- 内部単位のk点配列。
E (np.ndarray) -- 各k点に対応するエネルギー配列。
- 戻り値:
計算された有効質量配列。計算できない点ではNaNが含まれます。
- 戻り値の型:
np.ndarray
- crystal.draw_band_fs.find_kf_crossings_1d(k_grid_int, energies_1d, EF, dim, args)
1D直線パスでのkF点（直線プロット用）
詳細説明: 1Dパスに沿ったバンドエネルギー energies_1d をフェルミエネルギー EF と比較し、 E(k) - EF = 0 となるkF点を二分法で探索します。 見つかったkF点は第1ブリルアンゾーンに還元され、args.kf_merge_tol で指定された 許容範囲内の近接するkF点はマージされます。
- パラメータ:
k_grid_int (np.ndarray) -- 1Dパスのk点グリッド (内部単位)。
energies_1d (np.ndarray) -- 各k点におけるバンドエネルギーの配列 (Nk, Nband)。
EF (float) -- フェルミエネルギー。
dim (int) -- 空間次元。バンドエネルギー計算のために使用されます。
args (argparse.Namespace) -- コマンドライン引数オブジェクト (kf_tol, kf_merge_tol, modeなどに必要)。
- 戻り値:
(バンドインデックス, kF点) のタプルのリスト。
- 戻り値の型:
- crystal.draw_band_fs.get_band_energies_at_k_dim(k_vec_int: ndarray, model: str, dim: int, args) ndarray
指定されたk点におけるバンドエネルギーを計算する
詳細説明: 内部単位で与えられたkベクトル k_vec_int に対し、指定された model と dim に基づいてバンドエネルギー（固有値）を計算します。 - 'tb': タイトバインディングモデル。 - 'free': 自由電子モデル。Gベクトルに対応する運動エネルギーを直接計算しソート。 - 'nfe': ほぼ自由電子モデル。Gベクトル間の周期ポテンシャル args.v を考慮した
ハミルトニアン行列を構築し、固有値を計算。
- パラメータ:
k_vec_int (np.ndarray) -- 内部単位 (2π/a normalized) のkベクトル (dim,)。
model (str) -- モデルの種類 ('tb', 'free', 'nfe')。
dim (int) -- 空間次元 (1, 2, or 3)。
args (argparse.Namespace) -- コマンドライン引数オブジェクト (特に 'nfe' モデルの args.v に必要)。
- 戻り値:
そのk点での固有エネルギーの配列 (Nband,)。
- 戻り値の型:
np.ndarray
- 例外:
ValueError -- 未知のモデルが指定された場合。
- crystal.draw_band_fs.main()
スクリプトのメインエントリポイント
詳細説明: コマンドライン引数をパースし、指定された type (バンド図、DOS、フェルミ面) に基づいて 適切な計算とプロットを実行します。 フェルミエネルギー (EF) は、電子数 nelec と計算されたDOSから決定されるか、 --ef_fixed オプションで固定値を指定することもできます。 各プロットタイプ (1dband, 2dband, 3dband, 1dfs, 2dfs, 3dfs) に応じて、 対応するプロット関数を呼び出します。
- crystal.draw_band_fs.nband_of_model(dim: int, mode: str) int
このtoyモデルでのバンド本数（スピンは含めない）
詳細説明: 指定されたモデルと空間次元に基づき、スピン縮退を含まないバンドの総数を返します。 - 'tb': タイトバインディングモデルは1バンド。 - 'free'/'nfe': 自由電子モデルおよびほぼ自由電子モデルは、0ベクトルと±e_iベクトル
によって決定される数のバンド（1 + 2 * dim）を持ちます。
- パラメータ:
- 戻り値:
モデルのバンド本数。
- 戻り値の型:
- 例外:
ValueError -- 未知のモデルが指定された場合。
- crystal.draw_band_fs.plot_1d_fermi_points(k_range_int: ndarray, E_line: ndarray, EF: float, args)
1次元のフェルミ点（kF）をプロットする
詳細説明: 1次元のバンドエネルギー E_line とフェルミエネルギー EF を用いて、 E(k) = EF となるkF点をプロットします。 kF点はバンドとフェルミ準位の交点として見つけられ、第1ブリルアンゾーンに還元されて表示されます。
- パラメータ:
k_range_int (np.ndarray) -- k点範囲の配列 (内部単位)。
E_line (np.ndarray) -- 各k点に対応するバンドエネルギーの配列。
EF (float) -- フェルミエネルギー。
args (argparse.Namespace) -- コマンドライン引数オブジェクト (modeなどに必要)。
- 戻り値:
なし。
- 戻り値の型:
None
- crystal.draw_band_fs.plot_2d_fermi_surface(E_grid_2d: ndarray, EF: float, args, k_range_int: ndarray)
2次元フェルミ面をコンタープロットとして表示する
詳細説明: 2次元のエネルギーグリッド E_grid_2d を用いて、フェルミエネルギー EF の 等高線を2Dのフェルミ面としてプロットします。 E <= EF の領域は占有領域として塗りつぶされ、 args.nx_view に基づいて複数ブリルアンゾーンにわたって表示されるため、 周期的な性質が視覚化されます。
- パラメータ:
E_grid_2d (np.ndarray) -- 2次元エネルギーグリッドの配列。
EF (float) -- フェルミエネルギー。
args (argparse.Namespace) -- コマンドライン引数オブジェクト (nx_view, modeなどに必要)。
k_range_int (np.ndarray) -- k点範囲の配列 (内部単位)。グリッドの軸生成に使用。
- 戻り値:
なし。
- 戻り値の型:
None
- crystal.draw_band_fs.plot_3d_fermi_surface(E_grid_3d: ndarray, EF: float, args, k_range_int: ndarray)
3次元フェルミ面を3Dサーフェスとしてプロットする
詳細説明: 3次元のエネルギーグリッド E_grid_3d を用いて、フェルミエネルギー EF の 等値面（フェルミ面）をMarching Cubesアルゴリズムで抽出し、3Dグラフィックとして表示します。 scikit-imageライブラリが必要です。面には光源を考慮したシェーディングが適用され、 args.fs_alpha で透明度を調整できます。
- パラメータ:
E_grid_3d (np.ndarray) -- 3次元エネルギーグリッドの配列。
EF (float) -- フェルミエネルギー。
args (argparse.Namespace) -- コマンドライン引数オブジェクト (mode, fs_alphaなどに必要)。
k_range_int (np.ndarray) -- k点範囲の配列 (内部単位)。グリッドの座標変換に使用。
- 戻り値:
なし。
- 戻り値の型:
None
- crystal.draw_band_fs.plot_band(args, dim: int, EF: float, E_samples: ndarray, E_range_plot, E_range_ef, Egrid_dos=None, dos=None)
1Dバンドプロット、またはkx方向に沿った直線カット用 (DOS/m*対応)
詳細説明: 1次元のバンド構造、または高次元モデルのkx方向に沿った直線カットのバンド構造をプロットします。 フェルミエネルギー (EF) を破線で表示し、必要に応じてkF点を縦点線で示します。 args.dos がTrueの場合、DOSプロットをバンドプロットの隣に表示します。 args.mstar がTrueの場合、有効質量 m*(k) をバンドプロットの右軸に重ねて表示します。
- パラメータ:
args (argparse.Namespace) -- コマンドライン引数オブジェクト。
dim (int) -- 空間次元 (1, 2, or 3)。
EF (float) -- フェルミエネルギー。
E_samples (np.ndarray or None) -- DOS計算に使用されたエネルギーサンプルの配列。DOSプロットがない場合はNoneでも可。
E_range_plot (tuple[float, float]) -- プロットのY軸（エネルギー）範囲 (Emin, Emax)。
E_range_ef (tuple[float, float] or None) -- DOS/EF計算に使用されたエネルギー範囲 (Emin, Emax)。DOSプロットがない場合はNoneでも可。
Egrid_dos (np.ndarray or None) -- DOSのエネルギーグリッドの配列。args.dos がFalseの場合はNone。
dos (np.ndarray or None) -- 対応するDOS値の配列。args.dos がFalseの場合はNone。
- 戻り値:
なし。
- 戻り値の型:
None
- crystal.draw_band_fs.plot_band_with_path(args, dim: int, EF: float, E_range_plot)
高対称点パスに沿ってバンド図を描画する (2D/3D兼用)
詳細説明: 2次元または3次元のバンド構造を高対称点パスに沿ってプロットします。 指定された次元に応じて、対応する標準的な高対称点（例: 2D正方格子のΓ-X-M-Γパス、 3D単純立方格子のΓ-X-M-Γ-R-Xパス）が定義され、そのパスに沿ってバンドエネルギーが計算されます。 フェルミエネルギー (EF) は破線で表示され、高対称点の位置は縦線とラベルで示されます。
- crystal.draw_band_fs.reduce_to_first_bz(k_int: float) float
k_int を第1BZ [-0.5, 0.5) に還元（周期1）
詳細説明: 内部単位で表現されたk値を、周期境界条件を適用して第1ブリルアンゾーン ([-0.5, 0.5) の範囲) にマッピングし直します。
- crystal.draw_band_fs.refine_root_bisection(func, a, b, tol=1e-10, max_iter=80)
関数 func の根を二分法で求める
詳細説明: 与えられた関数 func の、区間 [a, b] 内での根を二分法アルゴリズムで探索します。 func(a) と func(b) の符号が異なる場合にのみ根が存在すると仮定します。 指定された許容誤差 tol または最大反復回数 max_iter に達するまで探索を続けます。
- パラメータ:
- 戻り値:
根が見つかった場合はその値、func(a) と func(b) の符号が同じ場合はNone。
- 戻り値の型:
float or None
- crystal.draw_band_fs.sample_energies_in_bz(args, dim: int) ndarray
dim 次元 BZ を格子サンプルして、全バンドのEを1次元配列で返す（状態列）
詳細説明: 指定された次元 dim のブリルアンゾーン内を args.ef_res で指定された 解像度で均一にサンプリングし、各k点における全バンドのエネルギーを計算します。 結果として得られるエネルギー値は1次元配列にフラット化されます。 --mode tb の場合は特別な高速パスを使用します。
- パラメータ:
args (argparse.Namespace) -- コマンドライン引数オブジェクト (ef_res, modeなどに必要)。
dim (int) -- 空間次元 (1, 2, or 3)。
- 戻り値:
計算された全エネルギー値の1次元配列。
- 戻り値の型:
np.ndarray
- 例外:
ValueError -- dim が1, 2, 3以外の場合。
- crystal.draw_band_fs.tb_energy(k_phys: ndarray, dim: int) float
dim次元TB (t=1, onsite=0)
詳細説明: 指定された空間次元 dim におけるタイトバインディング (TB) モデルのエネルギーを計算します。 ホッピング積分 t=1、オンサイトエネルギーを0と仮定しています。 - 1D: -cos(k_x a) - 2D: -(cos(k_x a) + cos(k_y a)) - 3D: -(cos(k_x a) + cos(k_y a) + cos(k_z a)) ここで k_phys は k*a の物理単位です。
- パラメータ:
k_phys (np.ndarray) -- 物理単位のkベクトル。
dim (int) -- 空間次元 (1, 2, or 3)。
- 戻り値:
計算されたタイトバインディングエネルギー。
- 戻り値の型:
- 例外:
ValueError -- dim が1, 2, 3以外の場合。