tkcrystal.py ライブラリドキュメント

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

tkcrystal.py は、結晶構造の管理と解析を目的としたPythonライブラリです。tkCrystal クラスを中心に、結晶構造に関する様々な情報（格子定数、空間群、原子サイト、密度、化学組成など）を取得・表示し、データを辞書形式に変換したり、3Dで可視化したりする機能を提供します。

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

結晶構造データの管理: 結晶構造データ（CIFファイルなどから読み込まれた情報）をオブジェクトとして保持し、各種プロパティにアクセスする。
詳細情報の表示: 単位セルのパラメータ、対称性、格子ベクトル、体積、化学組成、密度、原子サイト情報などを整形して標準出力に表示する。
データ変換: 結晶構造の詳細を標準的な辞書形式に変換し、他のプログラムやデータフォーマットとの連携を容易にする。
3D可視化: Matplotlibを使用して、単位格子とそこに配置された原子を3次元で描画し、視覚的に構造を確認できる。

このライブラリは、結晶学や材料科学の分野において、結晶構造データの処理、解析、および可視化を支援することを目指しています。

importする方法

tkcrystal.py ライブラリを利用するには、通常、tklib パッケージ内のモジュールとして以下の形式で tkCrystal クラスをインポートします。

from tklib.tkcrystal.tkcrystal import tkCrystal

これにより、tkCrystal クラスのインスタンスを作成して、結晶構造を操作できるようになります。

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

tkcrystal.py が依存している主な非標準ライブラリは以下の通りです。

numpy: 数値計算（特に配列操作や線形代数）
matplotlib: データのプロットおよび3D可視化

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

pip install numpy matplotlib

なお、tklib はこのライブラリ群が属するカスタムライブラリであり、別途環境に設定されている必要があります。

importできる変数と関数

tkcrystal.py モジュールは主に tkCrystal クラスを定義しており、このクラスを介して結晶構造データにアクセスし、操作します。モジュール自体が直接公開している変数や関数はありませんが、tkCrystal クラスのインスタンスが多くのメソッドを提供します。

クラス

`tkCrystal`

結晶構造データを管理し、解析・可視化するための中心的なクラスです。tklib.tkcrystal.tkcrystalobject.tkCrystalObject を継承しています。

コンストラクタ:

tkCrystal(**args)

動作: tkCrystal オブジェクトを初期化します。基底クラス tkCrystalObject のコンストラクタを呼び出し、引数 args を用いてオブジェクトのプロパティを更新します。
引数:
- **args: キーワード引数として、結晶構造のプロパティ（例: ファイルパス、結晶名など）を渡すことができます。
戻り値: なし。

デストラクタ:

__del__()

動作: オブジェクトが破棄される際に呼び出されます。基底クラスのデストラクタを呼び出します。
引数: なし。
戻り値: なし。

文字列表現:

__str__()

動作: オブジェクトのクラスパスを文字列として返します。
引数: なし。
戻り値: str - クラスの完全なパス（例: tklib.tkcrystal.tkcrystal.tkCrystal）。

初期化:

Initialize()

動作: オブジェクトの追加的な初期化処理を行います。現在の実装では特に処理は行われません。
引数: なし。
戻り値: なし。

結晶情報の表示:

print_inf(key=None)

動作: 結晶構造に関する詳細な情報を標準出力に整形して表示します。表示される情報には、結晶名、格子系、空間群、格子パラメータ、格子ベクトル、体積、化学組成、密度、原子サイトなどが含まれます。
引数:
- key: str または None。表示する情報のカテゴリを指定します。None の場合は全てのカテゴリが表示されます。指定可能なカテゴリには "header", "sample", "symmetry", "cell", "lattice", "reciprocal", "properties", "atomtypes", "asymsites", "allsites" などがあります。
戻り値: なし。

結晶情報の表示 (エイリアス):

PrintInf(key=None)

動作: print_inf メソッドと同じ動作をします。
引数:
- key: str または None。表示する情報のカテゴリを指定します。
戻り値: なし。

辞書形式への変換:

to_dict()

動作: 結晶構造の詳細な情報を辞書形式で返します。この辞書には、空間群、格子パラメータ、原子サイトの座標（分率およびデカルト）、原子の種類、電荷、占有率などが含まれます。
引数: なし。
戻り値: dict - 結晶構造の情報を格納した辞書。

単位格子ボックスの描画:

draw_box(ax, aij, nrange, linecolor='black')

動作: Matplotlibの3D軸オブジェクト ax 上に、指定された格子ベクトル aij に基づいて単位格子の枠（ボックス）を描画します。これは draw_unitcell メソッドの内部ヘルパー関数です。
引数:
- ax: matplotlib.axes.Axes オブジェクト (3D projection)。描画対象となる3D軸。
- aij: numpy.ndarray。単位格子の3つの格子ベクトルを格納した (3, 3) 形状の配列。
- nrange: リスト。描画範囲（現在の実装では直接使用されていないようです）。
- linecolor: str。単位格子の枠の色。デフォルトは 'black'。
戻り値: なし。

単位格子と原子の描画:

draw_unitcell(ax, nrange, kr=1000.0, linecolor='black', color='black', atomcolor=None)

動作: Matplotlibの3D軸オブジェクト ax 上に、単位格子と拡張された原子サイトを描画します。原子は種類に応じて色分けされ、球として表示されます。
引数:
- ax: matplotlib.axes.Axes オブジェクト (3D projection)。描画対象となる3D軸。
- nrange: リスト。描画範囲。
- kr: float。原子のサイズを調整するための係数。デフォルトは 1000.0。
- linecolor: str。単位格子の枠の色。デフォルトは 'black'。
- color: str。(現在の実装では使用されていません)
- atomcolor: list または None。原子種ごとの色を指定するリスト。None の場合、tklib.tkutils.colors が使用されます。
戻り値: なし。

結晶構造の3D表示:

draw(figsize=(10, 10), nrange=[[-0.1, 1.1], [-0.1, 1.1], [-0.1, 1.1]], rmin=0.1, kr=100.0)

動作: 結晶構造の3Dプロットを生成し、表示します。draw_unitcell を呼び出して、単位格子と原子サイトを描画します。プロットの軸範囲を調整し、plt.show() でグラフを表示します。
引数:
- figsize: tuple。生成される図のサイズ (幅, 高さ)。デフォルトは (10, 10)。
- nrange: list。描画する単位セルの相対的な範囲を指定するリスト。軸の表示範囲設定にも使用されます。デフォルトは [[-0.1, 1.1], [-0.1, 1.1], [-0.1, 1.1]]。
- rmin: float。同一原子サイトと判断する最小距離（アンケートローム単位）。現在の実装では使用されていません。デフォルトは 0.1。
- kr: float。原子サイズのスケーリング係数。デフォルトは 100.0。
戻り値: なし。

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

tkcrystal.py のソースコードには、if __name__ == "__main__": ブロックが存在しません。このため、このファイルをPythonのインタプリタで直接実行しても、特別なスクリプトとしての動作は定義されていません。通常は、他のPythonスクリプトから tkCrystal クラスをインポートして利用することを想定しています。

tkcrystal.py ライブラリ ドキュメント