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

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

tkvesta.py は、結晶構造可視化ソフトウェアであるVESTAに関連するデータ、特に原子の特性情報をPythonプログラム内で簡単に利用できるように設計されたライブラリです。

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

VESTA形式の原子データ読み込み: VESTAの elements.ini ファイルから、原子番号、原子名、各種半径（原子半径、ファンデルワールス半径、イオン半径）、および表示色などの詳細な原子特性データを読み込みます。
データ構造化: 読み込んだ原子データを、Pythonの辞書形式で提供し、プログラムからのアクセスを容易にします。原子名をキーとして、対応する特性情報にアクセスできます。
tklib との連携: 内部的に tklib ライブラリのユーティリティ関数や設定パスを利用しており、VESTA関連のファイルパス解決や数値型変換をサポートします。

このライブラリは、VESTAの原子データを利用して物質科学系のシミュレーションやデータ解析を行う際に、原子ごとの詳細なパラメータを手動で管理する手間を省き、データの整合性を保ちながら効率的な開発を支援することを目的としています。

importする方法

tkvesta.py ライブラリは、以下の方法で他のPythonプログラムからインポートできます。

from tkvesta import tkVESTA

この方法でインポートすると、tkVESTA クラスを利用できるようになります。

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

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

tklib: このライブラリは、VESTAデータベースのパス解決 (tkprogvars.VESTADBDir) や、文字列から数値への安全な変換 (tkutils.pint, tkutils.pfloat) といったユーティリティ機能を提供します。

tklib は通常、pip を使用してインストールできます。以下のコマンドをターミナルで実行してください。

pip install tklib

importできる変数と関数

tkvesta.py からは、以下のクラスをインポートして利用できます。

クラス: `tkVESTA`

VESTAの原子データ (elements.ini ファイル) を管理するためのクラスです。インスタンス化する際に原子データを読み込み、atom_dict 属性を通じてデータにアクセスできるようにします。

`init(self, path=None, print_level=1)`

tkVESTA オブジェクトを初期化するコンストラクタです。指定されたパスから原子データを読み込み、インスタンス変数 self.atom_dict に格納します。

動作: tkVESTA インスタンスが生成されると、自動的に指定された path またはデフォルトの VESTA elements.ini パスから原子データを読み込みます。読み込まれたデータは、self.atom_dict 属性に辞書として格納されます。
引数:
- path (str, optional): 読み込む elements.ini ファイルのパス。デフォルトは None です。None の場合、tklib.tkprogvars.VESTADBDir に基づくデフォルトの elements.ini パス (VESTADBDir/elements.ini) が使用されます。
- print_level (int, optional): ログ出力のレベル。0 を設定するとログ出力が抑制され、1 以上ではファイル読み込みに関する情報が出力されます。デフォルトは 1 です。
戻り値: なし。

`read_VESTA_elements(self, path=None, print_level=1)`

VESTA形式の elements.ini ファイルから原子データを読み込み、それを辞書形式で返すメソッドです。

動作: 指定された path のファイルを読み込み、各行を解析して原子の特性情報（原子番号、原子名、各種半径、色）を抽出します。抽出されたデータは、原子名をキーとし、その特性情報を値とする辞書にまとめられます。ファイルが存在しない場合や読み込めない場合は None を返します。
引数:
- path (str, optional): 読み込む elements.ini ファイルのパス。デフォルトは None です。None の場合、tklib.tkprogvars.VESTADBDir に基づくデフォルトの elements.ini パス (VESTADBDir/elements.ini) が使用されます。
- print_level (int, optional): ログ出力のレベル。0 を設定するとログ出力が抑制され、1 以上ではファイル読み込みに関する情報が出力されます。デフォルトは 1 です。

戻り値:

dict または None:

ファイルが正常に読み込まれた場合、読み込まれた原子データを格納した辞書を返します。辞書の構造は以下の通りです。

{
    "原子名_symbol": {
        "Z": float,            # 原子番号
        "atom_name": str,      # 原子名 (例: "H", "He")
        "ratom": float,        # 原子半径
        "rvdw": float,         # ファンデルワールス半径
        "rion": float,         # イオン半径
        "color": [float, float, float] # 色情報 (RGB値のリスト)
    },
    "別の原子名_symbol": {
        # ...
    }
}

ファイルが見つからない、または読み込めない場合は None を返します。

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

tkvesta.py は、if __name__ == "__main__": ブロックを持たないため、このスクリプトを直接Pythonインタープリタで実行しても、特別な処理は行われません。通常、このライブラリは他のPythonプログラムから tkVESTA クラスをインポートして利用されることを想定しています。

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