tkpymatgen.py ライブラリ技術ドキュメント
ライブラリの機能や目的
tkpymatgen.py は、物質科学における結晶構造の解析と可視化を目的としたPythonライブラリです。主に pymatgen ライブラリの機能に基づき、結晶構造データの読み込み、対称性解析、組成情報の抽出、そして3Dグラフィカルな構造描画（アニメーション機能を含む）を提供します。VASP (Vienna Ab initio Simulation Package) の出力ファイル (vasprun.xml, POSCAR) の処理にも対応しており、計算結果の解析や表現を支援します。
このライブラリは以下の主要な機能を提供します。
構造データの読み込み: CIFファイルやVASPファイル (
vasprun.xml,POSCAR) から結晶構造を読み込み、pymatgen.core.structure.Structureオブジェクトとして管理します。対称性解析:
pymatgen.symmetry.analyzer.SpacegroupAnalyzerを用いて、空間群情報、対称操作、サイト等価性などの構造対称性を解析します。組成情報の抽出: 結晶の化学式、組成、原子数、密度、分子量などの情報を取得します。
3D構造描画:
matplotlibを利用して結晶構造の3D描画を行います。原子はサイズと色で区別され、結合や単位胞の描画、さらに原子の変位ベクトルを表現するアニメーション機能も備えています。情報抽出: サイト情報、組成情報、原子の半径や電子構造など、詳細な物質科学的プロパティを抽出する機能を提供します。
tklib の tkObject を継承しているため、TkinterなどのGUIフレームワークと連携しやすいように設計されている可能性がありますが、提供されたコードからはGUIインターフェースそのものは直接含まれていません。物質研究者が計算結果を素早く視覚化し、構造的な特徴を理解するためのツールとして機能します。
importする方法
tkpymatgen.py ライブラリは、Pythonプログラム内で以下のようにインポートして使用できます。
ライブラリ全体をインポートする場合:
import tkpymatgen
特定のクラスや関数を直接インポートする場合:
from tkpymatgen import tkPymatgen, tkPymatgenVASP
from tkpymatgen import to_str, vector_to_str
必要な非標準ライブラリとインストール方法
tkpymatgen.py を実行するには、以下の非標準ライブラリが必要です。
numpy: 数値計算に使用されます。
matplotlib: 結晶構造の描画に使用されます。
pymatgen: 物質科学のデータ構造とアルゴリズムの基盤となります。
tabulate: 表形式のデータを出力する際に使用されます。
tklib:
tkObjectを継承するために使用されますが、このライブラリは標準的なPyPIパッケージではない可能性があります。
以下の pip コマンドで、上記のほとんどのライブラリをインストールできます。
pip install numpy matplotlib pymatgen tabulate
tklib については、一般的な pip インストール方法が提供されていません。これは開発環境固有のカスタムライブラリであるか、他の方法でプロジェクトに組み込まれることを想定している可能性があります。もし ModuleNotFoundError が発生した場合は、tklib の入手方法について、このライブラリが属するプロジェクトのドキュメントを参照するか、開発者に問い合わせる必要があります。
また、to_str 関数内で re モジュールが使用されていますが、コードの冒頭で import re が明示的に行われていません。このため、to_str 関数を呼び出す際に NameError: name 're' is not defined が発生する可能性があります。この問題を解決するには、ライブラリのコードに import re を追加する必要があります。
importできる変数と関数
tkpymatgen.py ライブラリからインポートできる主要な関数とクラス、およびそのメソッドを以下に示します。
関数
to_str(v)動作: 浮動小数点数
vを、特定の分数または記号（+,-）を表す文字列に変換します。例えば、0.5は'1/2'、1.0は'+'、-1.0は'-'に変換されます。それ以外の値は、精度1.0e-6以内で比較可能な既知の分数に変換され、そうでなければそのままの文字列として返されます。注意: コードにはreモジュールのインポートがありませんが、実装内でre.subを使用しているため、この関数を呼び出す前にimport reが必要です。引数:
v(float): 変換対象の浮動小数点数。
戻り値:
(str または None): 変換された文字列。
0.0の場合はNoneを返します。
vector_to_str(v)動作: 3要素の数値ベクトルを、座標軸を表す文字 (
x,y,z) と結合した文字列に変換します。例えば[0.5, 1.0, 0.0]は'1/2x+y'のようになります。各要素の数値はto_str関数で処理されます。引数:
v(list or tuple): 3要素の数値ベクトル。
戻り値:
(str): 変換された文字列。
matrix_to_str(m)動作: 3x3行列を、各行を
vector_to_strで処理した3つの文字列のタプルとして返します。引数:
m(list of lists or numpy.ndarray): 3x3の数値行列。
戻り値:
(tuple of str): 各行を表す3つの文字列。
is_valid_vasprun(path)動作: 指定されたパスのファイルが有効なXML形式であるかどうかをチェックします。これは
vasprun.xmlファイルのバリデーションに利用されます。引数:
path(str): チェック対象のファイルパス。
戻り値:
(bool): ファイルが有効なXMLであれば
True、そうでなければFalse。
クラス
class tkPymatgenVASP(tkObject)
VASPの出力ファイルを読み込むためのユーティリティクラス。
__init__(self, **args)動作: インスタンスを初期化します。
poscar,vasprun,structure属性をNoneに設定します。引数:
**args: 可変長のキーワード引数（現在は使用されていません）。
__del__(self)動作: デストラクタ。現在は何も行いません。
read_vasprun(self, infile = 'vasprun.xml', validate = False)動作:
vasprun.xmlファイルを読み込み、pymatgen.io.vasp.outputs.Vasprunオブジェクトを生成します。ファイル拡張子が.xmlであることを確認し、必要に応じてXMLの妥当性をチェックします。引数:
infile(str, optional): 読み込むvasprun.xmlファイルのパス。デフォルトは'vasprun.xml'。validate(bool, optional): XMLの妥当性をチェックするかどうか。デフォルトはFalse。
戻り値:
(Vasprun object or None): 読み込みに成功した場合、
Vasprunオブジェクト。失敗した場合はNone。
read_structure(self, infile, vasprun = None)動作: 結晶構造ファイルを読み込み、
pymatgen.core.structure.Structureオブジェクトを生成します。vasprun.xmlが指定された場合は、そこから最終構造を抽出します。それ以外の場合はPOSCARファイルからの読み込みを試みます。引数:
infile(str): 読み込む構造ファイル（vasprun.xmlまたはPOSCARなど）のパス。vasprun(Vasprun object, optional): 既に読み込まれたVasprunオブジェクトがあれば指定します。デフォルトはNone。
戻り値:
(tuple):
(poscar_object_or_vasprun_object, structure_object)のタプル。読み込みに失敗した場合は(False, False)。
class tkPymatgen(tkObject)
結晶構造の解析、対称性、情報の抽出、描画などを扱う中心クラス。
__init__(self, **args)動作: インスタンスを初期化します。
structure,space_group_analyzer,symmetrized_structure,iSPG,SPG_name属性をNoneに設定します。引数:
**args: 可変長のキーワード引数（現在は使用されていません）。
__del__(self)動作: デストラクタ。現在は何も行いません。
__str__(self, structure = None) -> str動作: 構造オブジェクトの概要を整形された文字列で返します。化学式、格子定数、角度、電荷、対称化されたサイト情報などが含まれます。
引数:
structure(Structure object, optional): 表示対象の構造オブジェクト。指定しない場合はインスタンスのself.structureを使用します。
戻り値:
(str): 構造の概要を示す文字列。
print_variables(self, obj)動作: 指定されたオブジェクトのメンバー変数を標準出力に表示します。
引数:
obj(object): メンバー変数を表示するオブジェクト。
print_methods(self, obj)動作: 指定されたオブジェクトのメンバー関数（メソッド）を標準出力に表示します。
引数:
obj(object): メンバー関数を表示するオブジェクト。
read(self, path, primitive = False)動作: 指定されたパスから結晶構造ファイルを読み込み、
pymatgen.core.structure.Structureオブジェクトを生成します。読み込んだ構造はself.structureに格納されます。引数:
path(str): 読み込む構造ファイルのパス。primitive(bool, optional): 原始セルとして読み込むかどうか。デフォルトはFalse。
戻り値:
(Structure object): 読み込まれた
Structureオブジェクト。
get_structure(self, structure = None)動作: 現在のインスタンスから最も適切な構造オブジェクト（対称化された構造または元の構造）を取得します。
引数:
structure(Structure object, optional): 構造オブジェクトが直接渡された場合はそれを返します。
戻り値:
(Structure object or None): 取得された
Structureオブジェクト、またはNone。
to(self, path, structure = None, symprec = 1.0e-3, print_level = 0)動作: 対称化された構造を指定されたパスにCIF形式で保存します。
引数:
path(str): 保存先のファイルパス。structure(Structure object, optional): 保存する構造オブジェクト。指定しない場合はインスタンスの構造を使用します。symprec(float, optional): 対称性許容誤差。CifWriterに渡されます。デフォルトは1.0e-3。print_level(int, optional): ログ出力レベル。0の場合は出力なし、1の場合は保存情報を出力します。デフォルトは0。
戻り値:
(bool or None): 保存に成功した場合は
True、失敗した場合はNone。
get_structure_inf(self)動作: インスタンスに格納されている構造に関する詳細な情報を辞書形式で返します。格子定数、格子ベクトル、体積、組成、サイト座標などが含まれます。
引数: なし。
戻り値:
(dict): 構造情報を含む辞書。
structure2inf(self, structure = None)動作: 構造オブジェクトから格子情報とサイト情報を抽出し、辞書形式で返します。各サイトについて、原子名、分数座標、直交座標が含まれます。
引数:
structure(Structure object, optional): 情報抽出対象の構造。指定しない場合はインスタンスの構造を使用します。
戻り値:
(dict): 格子とサイト情報を含む辞書。
structure2inf_flat(self, structure = None, symprec = 1.0e-4, coordinate = "fc", site_name = "as")動作: 構造オブジェクトから、よりフラットな形式（キーと値のペアがトップレベルに展開される形式）で情報を抽出し、辞書として返します。空間群情報、格子定数、化学式、原子数、各原子サイトの座標などが含まれます。
引数:
structure(Structure object, optional): 情報抽出対象の構造。symprec(float, optional): 対称性解析の許容誤差。デフォルトは1.0e-4。coordinate(str, optional): 座標の種類を指定します。'f'で分数座標、'c'で直交座標を含めます。デフォルトは'fc'(両方)。site_name(str, optional): サイト名の命名規則を指定します。's'でサイト番号による命名、'a'で原子名と連番による命名を含めます。デフォルトは'as'(両方)。
戻り値:
(dict): フラットな構造情報を含む辞書。
chemical_formula(self, structure = None)動作: 構造の化学式と還元化学式（reduced formula）を返します。
引数:
structure(Structure object, optional): 対象の構造。
戻り値:
(tuple):
(formula_string, reduced_formula_string)のタプル。構造がNoneの場合は(None, None)。
get_site_inf(self, site)動作: 単一のサイトオブジェクトから、組成、種、座標などの情報を辞書形式で返します。
引数:
site(Site object): 情報抽出対象のサイト。
戻り値:
(dict): サイト情報を含む辞書。
get_sites(self, structure)動作: 構造内のすべてのサイトオブジェクトのリストを返します。
引数:
structure(Structure object): 対象の構造。
戻り値:
(list of Site objects): サイトのリスト。
get_asymmetric_sites(self, structure)動作: 構造内の非対称なサイト（等価サイトグループの代表サイト）のリストを返します。
引数:
structure(Structure object): 対象の構造。
戻り値:
(list of Site objects): 非対称なサイトのリスト。
get_site_occ_inf(self, site)動作: サイトの占有率（occupation）に関する情報を辞書形式で返します。化学式、重量、元素組成などが含まれます。
引数:
site(Site object): 情報抽出対象のサイト。
戻り値:
(dict): サイトの占有率情報を含む辞書。
get_species_and_occu(self, structure)動作: 構造内の各サイトの元素種と占有率のリストを返します。
引数:
structure(Structure object): 対象の構造。
戻り値:
(list of tuples):
(species, occupation_dict)のタプルのリスト。
get_composition_inf(self, composition)動作:
pymatgen.core.Compositionオブジェクトから、単位胞の組成、原子数、種類数、重量などの詳細情報を辞書形式で返します。引数:
composition(Composition object): 情報抽出対象の組成オブジェクト。
戻り値:
(dict): 組成情報を含む辞書。
get_ionic_radius(self, atom_name, charge = None, ncoordination = None)動作: 指定された原子名、電荷、配位数に基づいて、その原子のイオン半径を返します。電荷や配位数が指定されない場合、デフォルトの共通酸化状態が使用されます。
引数:
atom_name(str): 原子名（例:'O','Fe'）。charge(int or float, optional): イオンの電荷。デフォルトはNone（共通酸化状態を使用）。ncoordination(int, optional): 配位数。デフォルトはNone。
戻り値:
(float): イオン半径。
get_atom_inf(self, atom_name, charge = None, ncoordination = None)動作: 指定された原子名に関する詳細情報（原子量、原子番号、電荷、イオン半径、電子構造）を辞書形式で返します。
引数:
atom_name(str): 原子名。charge(int or float, optional): イオンの電荷。ncoordination(int, optional): 配位数。
戻り値:
(dict): 原子情報を含む辞書。
elements(self, structure = None)動作: 構造を構成する元素のリストとそれぞれの原子量、原子番号、数を返します。
引数:
structure(Structure object, optional): 対象の構造。
戻り値:
(list of dict): 各元素の情報（原子名、M、Z、数）を含む辞書のリスト。
get_atom_color(self, atom_name, Z)動作: 指定された原子名と原子番号
Zに基づいて、描画用の色（R, G, Bのタプルまたは事前定義された文字列）を決定して返します。引数:
atom_name(str): 原子名。Z(int): 原子番号。
戻り値:
(str or tuple): 色を表す文字列（例:
'red') またはRGBのタプル。
draw_box(self, axis, structure, origin, ax, ay, az, color = 'black', linewidth = 1.0)動作: 3D軸上に単位胞の箱を描画します。
引数:
axis(matplotlib.axes.Axes): 描画対象の3D軸オブジェクト。structure(Structure object): 構造オブジェクト（格子情報取得用）。origin(list): 単位胞の原点座標[x, y, z]。ax,ay,az(list): 格子ベクトルa,b,cの直交座標成分。color(str, optional): 箱の線の色。デフォルトは'black'。linewidth(float, optional): 箱の線の太さ。デフォルトは1.0。
calculate_all_distances(self, structure, max_distance = 2.75)動作: 構造内のすべての原子ペア間の距離を計算し、指定された最大距離以下のペアをリストとして返します。
引数:
structure(Structure object): 距離計算対象の構造。max_distance(float, optional): 考慮する最大距離。この距離以下のペアのみが返されます。デフォルトは2.75。
戻り値:
(list of list):
[atom_idx_i, atom_idx_j, distance]の形式のリスト。
draw_atoms(self, ax, structure, draw_range, kr = 400.0, atom_alpha = 0.5, vector_r = 3.0, vector_length = 3.0, arrow_length_ratio = 0.3)動作: 3D軸上に原子を描画します。原子はサイズと色で表現され、もし
velocityプロパティが設定されていれば、速度ベクトルも描画されます。引数:
ax(matplotlib.axes.Axes): 描画対象の3D軸オブジェクト。structure(Structure object): 描画対象の構造。draw_range(list of list): 描画範囲[[xmin, xmax], [ymin, ymax], [zmin, zmax]]。kr(float, optional): 原子半径のスケーリングファクター。デフォルトは400.0。atom_alpha(float, optional): 原子の透明度。デフォルトは0.5。vector_r(float, optional): ベクトル（速度など）の線の太さ。デフォルトは3.0。vector_length(float, optional): ベクトルの表示長さの基準。デフォルトは3.0。arrow_length_ratio(float, optional): 矢印の頭の長さ比率。デフォルトは0.3。
戻り値:
(tuple):
(structure_draw, draw_inf)のタプル。structure_drawは描画された原子のみを含む新しい構造オブジェクト、draw_infは描画データを含む辞書。
configure_axis_structure(self, ax, xrange, yrange, zrange, fontsize = 12, legend_fontsize = 12)動作: 3D軸の表示設定（ラベル、グリッド、目盛り、範囲、アスペクト比など）を構成します。
引数:
ax(matplotlib.axes.Axes): 設定対象の3D軸オブジェクト。xrange,yrange,zrange(list): それぞれの軸の表示範囲[min, max]。fontsize(int, optional): 軸ラベルのフォントサイズ。デフォルトは12。legend_fontsize(int, optional): 凡例のフォントサイズ。デフォルトは12。
get_xyz_range(self, structure, draw_range)動作: 単位胞の相対座標で指定された描画範囲を、構造の格子定数に基づいて絶対直交座標の範囲に変換します。
引数:
structure(Structure object): 構造オブジェクト。draw_range(list of list): 相対的な描画範囲[[x_rel_min, x_rel_max], [y_rel_min, y_rel_max], [z_rel_min, z_rel_max]]。Noneが含まれる場合は単位胞の[0, 1]を使用。
戻り値:
(tuple):
(xrange, yrange, zrange)のタプル。各範囲は[absolute_min, absolute_max]の形式。
draw_bonds(self, ax, structure, distances, bond_r, color = 'gray')動作: 計算された原子間距離に基づいて、3D軸上に原子間の結合を描画します。
引数:
ax(matplotlib.axes.Axes): 描画対象の3D軸オブジェクト。structure(Structure object): 描画対象の構造。distances(list of list):calculate_all_distancesから返される形式の距離情報。bond_r(float): 結合の線の太さ。color(str, optional): 結合の線の色。デフォルトは'gray'。
戻り値:
(list of Line3D objects): 描画された結合のリスト。
draw_structure(self, tkplt, ax, structure, draw_range = [[0.0, 1.0], [0.0, 1.0], [0.0, 1.0]], max_distance = 2.75, kr = 200.0, atom_alpha = 0.5, bond_r = 5.0, vector_r = 3.0, vector_length = 3.0, arrow_length_ratio = 0.3, displacement = 1.0, sleep = 0.01, time_step = 0.1, nstep = 100, animation = False, stop_callback = None, fontsize = 16, legend_fontsize = 16)動作: 結晶構造の完全な3D描画を行います。単位胞のボックス、原子、結合を描画し、オプションでアニメーションも実行します。
tkplt引数は、matplotlib.pyplotを直接使用するか、tklib経由で描画を制御するかを切り替えるために使用されます。引数:
tkplt(module or None):matplotlib.pyplotモジュール、またはtklibのpltオブジェクト、またはNone。Noneの場合はmatplotlib.pyplotが直接使用されます。ax(matplotlib.axes.Axes): 描画対象の3D軸オブジェクト。structure(Structure object): 描画対象の結晶構造。draw_range(list of list, optional): 描画する単位胞の範囲。デフォルトは[[0.0, 1.0], [0.0, 1.0], [0.0, 1.0]]。max_distance(float, optional): 結合を描画する最大原子間距離。デフォルトは2.75。kr(float, optional): 原子サイズのスケーリングファクター。デフォルトは200.0。atom_alpha(float, optional): 原子の透明度。デフォルトは0.5。bond_r(float, optional): 結合の線の太さ。デフォルトは5.0。vector_r(float, optional): 速度ベクトルの線の太さ。デフォルトは3.0。vector_length(float, optional): 速度ベクトルの描画長さの基準。デフォルトは3.0。arrow_length_ratio(float, optional): 速度ベクトル矢印の頭の長さ比率。デフォルトは0.3。displacement(float, optional): アニメーションにおける変位のスケーリングファクター。デフォルトは1.0。sleep(float, optional): アニメーションのフレーム間の一時停止時間 (秒)。デフォルトは0.01。time_step(float, optional): アニメーションの時間ステップ。デフォルトは0.1。nstep(int, optional): アニメーションのステップ数。デフォルトは100。animation(bool, optional): アニメーションを実行するかどうか。デフォルトはFalse。stop_callback(callable, optional): アニメーションを停止するためのコールバック関数。Trueを返すとアニメーションが停止します。デフォルトはNone。fontsize(int, optional): 軸ラベルなどのフォントサイズ。デフォルトは16。legend_fontsize(int, optional): 凡例のフォントサイズ。デフォルトは16。
戻り値:
なし。
symmetrize(self, structure, prec = 1.0e-3)動作: 指定された構造の対称性解析を行い、空間群番号、空間群記号、対称化された構造を取得します。これらの情報はインスタンスの属性に格納されます。
引数:
structure(Structure object): 対称性解析対象の構造。prec(float, optional): 対称性検出の許容誤差。デフォルトは1.0e-3。
戻り値:
(tuple):
(iSPG_number, SPG_name_symbol, symmetrized_structure_object)のタプル。
get_symmetrized_structure(self, symprec = 1.0e-3)動作: 現在の構造から対称化された構造を取得します。
引数:
symprec(float, optional): 対称性検出の許容誤差。デフォルトは1.0e-3。
戻り値:
(SymmetrizedStructure object): 対称化された構造オブジェクト。
get_spacegroup(self)動作: 現在の構造の空間群情報（記号と番号）を返します。
引数: なし。
戻り値:
(tuple):
(space_group_symbol, space_group_number)のタプル。
get_symmetry_inf(self, symprec = 1.0e-3)動作: 構造の対称性に関する詳細な情報を辞書形式で返します。データセット、空間群情報、ラウエ群、ハル記号、対称操作、点群情報などが含まれます。
引数:
symprec(float, optional): 対称性検出の許容誤差。デフォルトは1.0e-3。
戻り値:
(dict): 対称性情報を含む辞書。
main scriptとして実行したときの動作
提供された tkpymatgen.py のソースコードには、if __name__ == "__main__": ブロックが含まれていません。したがって、このライブラリファイルを python tkpymatgen.py のように直接実行しても、特定の動作は定義されていません。
このライブラリは、他のPythonプログラムからインポートされ、その機能（結晶構造の解析、可視化など）が利用されることを想定して設計されています。