tkcrystalbase.py ライブラリ技術ドキュメント
ライブラリの機能や目的
tkcrystalbase.py は、結晶学的な計算と可視化の基礎を提供するPythonライブラリです。物理定数、結晶格子、原子サイトに関する情報を管理し、格子ベクトル、計量テンソル、単位格子の体積、逆格子空間の計算などの基本的な結晶学的操作をサポートします。また、結晶構造の3次元可視化のためのユーティリティ関数も含まれています。
主な機能は以下の通りです。
物理定数と変換係数: 科学計算に頻繁に使用される物理定数（プランク定数、光速、電子の電荷など）と単位変換係数を提供します。
結晶格子計算: 単位格子の格子定数から実空間および逆格子空間の格子ベクトル、計量テンソル、体積を計算します。
幾何学的計算: 結晶分数座標系における原子間の距離や結合角を計算します。
3D可視化ユーティリティ: 単位格子ボックスや原子サイトを3次元プロットに描画するための補助関数を提供します（別途
matplotlibなどのプロットライブラリが必要です）。
このライブラリは、材料科学、固体物理学、結晶化学などの分野で、基本的な結晶構造の解析やモデリングを行う際の基盤となるツールとして設計されています。
importする方法
このライブラリを他のPythonプログラムから利用するには、通常のPythonモジュールと同様に import ステートメントを使用します。
import tkcrystalbase
あるいは、特定の変数や関数のみをインポートすることも可能です。
from tkcrystalbase import pi, cal_lattice_vectors, sites
必要な非標準ライブラリとインストール方法
このライブラリは、数値計算のために numpy ライブラリに依存しています。
numpy: 高性能な数値計算を可能にするPythonライブラリ。配列オブジェクトや線形代数演算を提供します。
numpy は pip を使ってインストールできます。
pip install numpy
pprint はPythonの標準ライブラリの一部であるため、別途インストールする必要はありません。
importできる変数と関数
変数
以下は、tkcrystalbase.py で定義されている主要な変数です。
pi: 円周率 \(\pi\) の近似値（3.141592653589793）。pi2: \(2\pi\) の近似値（6.283185307179586）。torad: 角度を度からラジアンに変換するための係数（\( \pi/180 \approx 0.01745329251944 \)）。todeg: 角度をラジアンから度に変換するための係数（\( 180/\pi \approx 57.29577951472 \)）。basee: 自然対数の底 \(e\) の近似値（2.71828183）。h: プランク定数 \(h\) （\(6.6260755 \times 10^{-34}\) J s）。h_bar: 換算プランク定数 \(\hbar\) （\(1.05459 \times 10^{-34}\) J s）。hbar:h_barと同じ。c: 真空中の光速 \(c\) （\(2.99792458 \times 10^8\) m/s）。e: 素電荷 \(e\) （\(1.60218 \times 10^{-19}\) C）。me: 電子の静止質量 \(m_e\) （\(9.1093897 \times 10^{-31}\) kg）。mp: プロトンの静止質量 \(m_p\) （\(1.6726231 \times 10^{-27}\) kg）。mn: 中性子の静止質量 \(m_n\) （\(1.67495 \times 10^{-27}\) kg）。u0: 真空の透磁率 \(\mu_0\) （\(4.0 \pi \times 10^{-7}\) N s\(^2\) C\(^{-2}\)）。e0: 真空の誘電率 \(\epsilon_0\) （\(8.854418782 \times 10^{-12}\) C\(^2\) N\(^{-1}\) m\(^{-2}\)）。e2_4pie0: \( e^2 / (4\pi\epsilon_0) \) の値（\(2.30711 \times 10^{-28}\) N m\(^2\)）。a0: ボーア半径 \(a_0\) （\(5.29177 \times 10^{-11}\) m）。kB: ボルツマン定数 \(k_B\) （\(1.380658 \times 10^{-23}\) J K\(^{-1}\)）。NA: アボガドロ定数 \(N_A\) （\(6.0221367 \times 10^{23}\) mol\(^{-1}\)）。R: 気体定数 \(R\) （\(8.31451\) J K\(^{-1}\) mol\(^{-1}\)）。F: ファラデー定数 \(F\) （\(96485.3\) C mol\(^{-1}\)）。g: 標準重力加速度 \(g\) （\(9.81\) m/s\(^2\)）。lattice_parameters: 格子定数を表すリスト。[a, b, c, alpha, beta, gamma]の形式で、長さはオングストローム（Å）、角度は度で与えられます。デフォルトは面心立方晶NaClに設定されています。sites: 単位格子内の原子サイト情報を格納するリストのリスト。各内部リストは[原子名, サイトラベル, 原子番号, 原子質量, 電荷, 半径, 色, numpy.array([x, y, z])]の形式で、最後の要素は分数座標での位置です。デフォルトはNaCl構造の原子配置です。
関数
以下は、tkcrystalbase.py で定義されている主要な関数です。
reduce01(x)
指定された値を \([0, 1)\) の範囲に変換します。
動作: 入力
xの整数部分を切り捨て、小数部分を返します。これにより、周期的な境界条件を持つシステム（例えば、結晶の分数座標）で値が単位セル内にあることを保証するために使用できます。引数:
x(float): 変換したい数値。
戻り値:
(float): \(x - \lfloor x \rfloor\) の値。
round01(x)
値を \([0, 1)\) の範囲に丸め、特に1や0に近い値を補正します。
動作:
reduce01と似ていますが、浮動小数点数の誤差を考慮して、非常に1に近い値を1.0に、非常に0に近い値を0.0に補正します。それ以外の1.0を超える値や1.0未満の値はreduce01と同様に処理されます。引数:
x(float): 丸めたい数値。
戻り値:
(float): 丸められた数値。
round_parameter(x, tol)
指定された公差 tol に基づいて値を丸めます。
動作: 数値
xをtolの倍数に最も近い値に丸めます。これは、格子定数などの物理パラメータを特定の精度で扱う場合に有用です。引数:
x(float): 丸めたい数値。tol(float): 丸めの公差。
戻り値:
(float):
tolの倍数に丸められた数値。
cal_lattice_vectors(latt)
格子定数から実空間の格子ベクトルを計算します。
動作: 入力された格子定数
[a, b, c, alpha, beta, gamma]（長さはÅ、角度は度）から、直交座標系における3つの格子ベクトル \( \mathbf{a}_1, \mathbf{a}_2, \mathbf{a}_3 \) を計算します。通常、\( \mathbf{a}_1 \) は \(x\) 軸に沿い、\( \mathbf{a}_2 \) は \(xy\) 平面内にあるように配置されます。 ブロック数式: $\( \mathbf{a}_1 = (a, 0, 0) \\ \mathbf{a}_2 = (b \cos\gamma, b \sin\gamma, 0) \\ \mathbf{a}_3 = (c \cos\beta, c \frac{\cos\alpha - \cos\beta \cos\gamma}{\sin\gamma}, \sqrt{c^2 - a_{3x}^2 - a_{3y}^2}) \)$引数:
latt(list of float): 格子定数[a, b, c, alpha, beta, gamma]。
戻り値:
numpy.ndarray(shape=(3, 3)): 格子ベクトル \( \mathbf{a}_1, \mathbf{a}_2, \mathbf{a}_3 \) を行ベクトルとして含む行列。
cal_metrics(latt)
格子定数から実空間の格子ベクトルと計量テンソルを計算します。
動作:
cal_lattice_vectorsを使用して格子ベクトルを計算し、それらから計量テンソル \( g_{ij} \) を計算します。計量テンソルは、分数座標系における距離や角度の計算に必要です。 ブロック数式: $\( g_{ij} = \mathbf{a}_i \cdot \mathbf{a}_j \)$引数:
latt(list of float): 格子定数[a, b, c, alpha, beta, gamma]。
戻り値:
dict: 以下のキーを持つ辞書。'aij'(numpy.ndarray): 格子ベクトル行列。'gij'(numpy.ndarray): 計量テンソル行列。
cal_volume(aij)
格子ベクトルから単位格子の体積を計算します。
動作: 3つの格子ベクトル \( \mathbf{a}_1, \mathbf{a}_2, \mathbf{a}_3 \) から、単位格子の体積 \( V \) をスカラー三重積によって計算します。 ブロック数式: $\( V = |\mathbf{a}_1 \cdot (\mathbf{a}_2 \times \mathbf{a}_3)| \)$
引数:
aij(numpy.ndarray): 格子ベクトルを行ベクトルとして含む行列。
戻り値:
(float): 単位格子の体積。
cal_reciprocal_lattice_vectors(aij)
実空間格子ベクトルから逆格子ベクトルを計算します。
動作: 実空間の格子ベクトル \( \mathbf{a}_1, \mathbf{a}_2, \mathbf{a}_3 \) と単位格子の体積 \( V \) を用いて、逆格子ベクトル \( \mathbf{b}_1, \mathbf{b}_2, \mathbf{b}_3 \) を計算します。 ブロック数式: $\( \mathbf{b}_1 = \frac{\mathbf{a}_2 \times \mathbf{a}_3}{V} \\ \mathbf{b}_2 = \frac{\mathbf{a}_3 \times \mathbf{a}_1}{V} \\ \mathbf{b}_3 = \frac{\mathbf{a}_1 \times \mathbf{a}_2}{V} \)$
引数:
aij(numpy.ndarray): 実空間の格子ベクトルを行ベクトルとして含む行列。
戻り値:
listofnumpy.ndarray: 逆格子ベクトル \( [\mathbf{b}_1, \mathbf{b}_2, \mathbf{b}_3] \) のリスト。
cal_reciprocal_lattice_parameters(Raij)
逆格子ベクトルから逆格子定数を計算します。
動作: 逆格子ベクトル \( \mathbf{b}_1, \mathbf{b}_2, \mathbf{b}_3 \) の長さとそれらのなす角度を計算し、逆格子空間の格子定数
[Ra, Rb, Rc, Ralpha, Rbeta, Rgamma]を導出します。引数:
Raij(list ofnumpy.ndarray): 逆格子ベクトル \( [\mathbf{b}_1, \mathbf{b}_2, \mathbf{b}_3] \) のリスト。
戻り値:
listof float: 逆格子定数[Ra, Rb, Rc, Ralpha, Rbeta, Rgamma]。長さは Å\(^{-1}\)、角度は度。
fractional_to_cartesian(pos, aij)
結晶分数座標を直交座標に変換します。
動作: 結晶分数座標 \( (u, v, w) \) と格子ベクトル \( \mathbf{a}_1, \mathbf{a}_2, \mathbf{a}_3 \) を用いて、直交座標 \( (x, y, z) \) を計算します。 ブロック数式: $\( \mathbf{r} = u \mathbf{a}_1 + v \mathbf{a}_2 + w \mathbf{a}_3 \\ (x, y, z) = (u a_{1x} + v a_{2x} + w a_{3x}, u a_{1y} + v a_{2y} + w a_{3y}, u a_{1z} + v a_{2z} + w a_{3z}) \)$
引数:
pos(numpy.ndarrayor list of float): 原子サイトの分数座標 \( [u, v, w] \)。aij(numpy.ndarray): 格子ベクトルを行ベクトルとして含む行列。
戻り値:
(tuple of float): 直交座標 \( (x, y, z) \)。
distance2(pos0, pos1, gij)
分数座標で表された2点間の距離の2乗を計算します。
動作: 2つの分数座標 \( \mathbf{p}_0, \mathbf{p}_1 \) と計量テンソル \( g_{ij} \) を使用して、2点間の距離の2乗 \( d^2 \) を計算します。 ブロック数式: $\( d^2 = \sum_{i,j} g_{ij} \Delta p_i \Delta p_j = \Delta \mathbf{p}^T \mathbf{G} \Delta \mathbf{p} \)\( ここで \) \Delta \mathbf{p} = \mathbf{p}_1 - \mathbf{p}_0 $ です。
引数:
pos0(numpy.ndarrayor list of float): 1点目の分数座標 \( [u_0, v_0, w_0] \)。pos1(numpy.ndarrayor list of float): 2点目の分数座標 \( [u_1, v_1, w_1] \)。gij(numpy.ndarray): 計量テンソル行列。
戻り値:
(float): 2点間の距離の2乗。
distance(pos0, pos1, gij)
分数座標で表された2点間の距離を計算します。
動作:
distance2関数を呼び出して距離の2乗を計算し、その平方根を取ることで2点間の距離を計算します。引数:
pos0(numpy.ndarrayor list of float): 1点目の分数座標 \( [u_0, v_0, w_0] \)。pos1(numpy.ndarrayor list of float): 2点目の分数座標 \( [u_1, v_1, w_1] \)。gij(numpy.ndarray): 計量テンソル行列。
戻り値:
(float): 2点間の距離。
angle(pos0, pos1, pos2, gij)
分数座標で表された3点 \( \mathbf{p}_1 - \mathbf{p}_0 - \mathbf{p}_2 \) がなす角度を計算します。
動作: \( \mathbf{p}_0 \) を頂点とし、\( \mathbf{p}_1 \) と \( \mathbf{p}_2 \) へ向かう2つのベクトル間の角度を計算します。計量テンソルを使用して、分数座標におけるベクトルの内積と長さを計算します。 ブロック数式: $\( \cos\theta = \frac{(\mathbf{p}_1 - \mathbf{p}_0) \cdot (\mathbf{p}_2 - \mathbf{p}_0)}{|\mathbf{p}_1 - \mathbf{p}_0| \, |\mathbf{p}_2 - \mathbf{p}_0|} \)$
引数:
pos0(numpy.ndarrayor list of float): 角度の頂点となる分数座標。pos1(numpy.ndarrayor list of float): 1つ目の腕の端点の分数座標。pos2(numpy.ndarrayor list of float): 2つ目の腕の端点の分数座標。gij(numpy.ndarray): 計量テンソル行列。
戻り値:
(float): 3点がなす角度（度）。
configure_axis_structure(ax, xrange, yrange, zrange, fontsize = 12, legend_fontsize = 12)
Matplotlibの3Dプロット軸の表示設定を調整します。
動作: 3Dプロットの軸の外観をカスタマイズします。軸の目盛り、ラベル、グリッド、枠線の表示を制御し、見栄えの良い結晶構造図を作成するのに役立ちます。具体的には、軸の線、ティック、ラベルを非表示にし、軸の範囲とアスペクト比を設定します。
引数:
ax: Matplotlibの3D軸オブジェクト（例:fig.add_subplot(111, projection='3d')で作成）。xrange(tuple): \(x\) 軸の表示範囲(xmin, xmax)。yrange(tuple): \(y\) 軸の表示範囲(ymin, ymax)。zrange(tuple): \(z\) 軸の表示範囲(zmin, zmax)。fontsize(int, optional): 軸ラベルのフォントサイズ。デフォルトは12。legend_fontsize(int, optional): 凡例のフォントサイズ（この関数内では未使用ですが引数として定義されています）。デフォルトは12。
戻り値:
なし。軸オブジェクト
axを直接変更します。
draw_box(ax, aij, nrange, color = 'black')
Matplotlibの3Dプロットに単位格子ボックスを描画します。
動作: 格子ベクトル
aijに基づいて、単位格子を表す箱の辺を3Dプロットに描画します。引数:
ax: Matplotlibの3D軸オブジェクト。aij(numpy.ndarray): 格子ベクトルを行ベクトルとして含む行列。nrange(list): 描画するセルの範囲（この関数内では未使用ですが引数として定義されています）。color(str, optional): 描画する箱の線の色。デフォルトは'black'。
戻り値:
なし。軸オブジェクト
axを直接変更します。
draw_unitcell(ax, sites, aij, nrange, color = 'black', facecolor = 'black', edgecolor = 'white', alpha = 0.7, kr = 1.0)
Matplotlibの3Dプロットに単位格子と原子サイトを描画します。
動作:
draw_boxを呼び出して単位格子ボックスを描画し、sitesリストの情報に基づいて単位格子内の原子サイトを球状のマーカーとしてプロットします。nrangeで指定された範囲内の周期的なセルにわたって原子を配置します。引数:
ax: Matplotlibの3D軸オブジェクト。sites(list of lists or None): 原子サイト情報のリスト。Noneの場合、原子は描画されません。aij(numpy.ndarray): 格子ベクトルを行ベクトルとして含む行列。nrange(list of tuples): 各軸[x_min, x_max], [y_min, y_max], [z_min, z_max]の描画範囲。例えば[[0,1], [0,1], [0,1]]は1つの単位セル。color(str, optional): 単位格子ボックスの線の色。デフォルトは'black'。facecolor(str, optional): 原子マーカーの塗りつぶし色。デフォルトは'black'。edgecolor(str, optional): 原子マーカーの縁の色。デフォルトは'white'。alpha(float, optional): 原子マーカーの透明度。デフォルトは0.7。kr(float, optional): 原子マーカーのサイズスケーリング係数。デフォルトは1.0。
戻り値:
なし。軸オブジェクト
axを直接変更します。
main scriptとして実行したときの動作
tkcrystalbase.py が直接Pythonインタプリタで実行された場合（python tkcrystalbase.py コマンドなど）、if __name__ == '__main__': ブロック内の main() 関数が実行されます。
main() 関数は、設定されている lattice_parameters を使用して、以下の計算結果を標準出力に出力します。
格子定数:
lattice_parametersの内容。格子ベクトル:
cal_lattice_vectors関数によって計算された実空間の3つの格子ベクトル \( \mathbf{a}_x, \mathbf{a}_y, \mathbf{a}_z \) を直交座標で表示します。計量テンソル:
cal_metrics関数によって計算された計量テンソル \( g_{ij} \) を表示します。単位格子の体積:
cal_volume関数によって計算された単位格子の体積。逆格子定数:
cal_reciprocal_lattice_parameters関数によって計算された逆格子空間の格子定数。逆格子ベクトル:
cal_reciprocal_lattice_vectors関数によって計算された逆格子空間の3つのベクトル \( \mathbf{b}_x, \mathbf{b}_y, \mathbf{b}_z \) を表示します。逆格子計量テンソル: 逆格子定数から計算された逆格子空間の計量テンソル \( g^*_{ij} \) を表示します。
逆格子単位格子の体積: 逆格子ベクトルから計算された逆格子単位格子の体積。
距離計算の例:
np.array([0,0,0])とnp.array([1,1,1])の間の距離を計算して表示します。角度計算の例:
np.array([0,0,0])を頂点とし、np.array([1,1,1])とnp.array([1,0,0])がなす角度。np.array([0,0,0])を頂点とし、np.array([1,0,0])とnp.array([0,1,0])がなす角度。 これらを計算して表示します。
これらの出力は、ライブラリの基本的な計算機能が正しく動作することを確認するための簡単なテストケースとして機能します。実行後、プログラムは終了します。