tkpymatgen プログラム仕様

Pymatgenライブラリをラップし、構造解析や描画機能を提供するモジュールです。

このモジュールは、結晶構造データの読み込み、解析、視覚化のためのユーティリティクラスと関数を含みます。 VASPの出力ファイルからの構造情報の抽出や、Matplotlibを用いた構造描画をサポートします。

関連リンク: tkpymatgen.py ライブラリ技術ドキュメント

tklib.tkcrystal.tkpymatgen.is_valid_vasprun(path)

指定されたパスのvasprun.xmlファイルが有効なXML形式であるかをチェックします。

ファイルをXMLとしてパースできるかどうかに基づいて真偽値を返します。

パラメータ:

path (str) -- vasprun.xmlファイルのパス。

戻り値:

ファイルが有効なXMLであればTrue、そうでなければFalse。

戻り値の型:

bool

tklib.tkcrystal.tkpymatgen.matrix_to_str(m)

3x3行列を行列の各行をベクトル文字列に変換して返します。

パラメータ:

m (list of list or numpy.ndarray) -- 変換する3x3行列。

戻り値:

各行のベクトル文字列(x, y, z)のタプル。

戻り値の型:

tuple of str

class tklib.tkcrystal.tkpymatgen.tkPymatgen(**args)

ベースクラス: tkObject

Pymatgenの機能を用いて結晶構造の解析や操作を行うためのラッパークラスです。

構造データの読み込み、対称性の解析、情報の抽出、および描画機能を提供します。

calculate_all_distances(structure, max_distance=2.75)

構造内のすべての原子ペア間の距離を計算し、指定された最大距離以下のペアをリストアップします。

パラメータ:

• structure (pymatgen.core.structure.Structure) -- 距離を計算するPymatgenのStructureオブジェクト。

• max_distance (float) -- 距離を記録する最大値（Å）。

戻り値:

[原子Iのインデックス, 原子Jのインデックス, 距離]のリスト。

戻り値の型:

list of list

chemical_formula(structure=None)

構造から化学式と簡約化された化学式を取得します。

パラメータ:

structure (pymatgen.core.structure.Structure or None) -- 情報を抽出するPymatgenのStructureオブジェクト。Noneの場合、内部の構造が使用されます。

戻り値:

(化学式, 簡約化された化学式)のタプル。構造がNoneの場合は(None, None)。

戻り値の型:

tuple of (str or None, str or None)

configure_axis_structure(ax, xrange, yrange, zrange, fontsize=12, legend_fontsize=12)

3Dプロットの軸を構造描画用に設定します。

軸ラベル、目盛り、背景、ボックスアスペクト比などを調整します。

パラメータ:

• ax (matplotlib.axes._subplots.Axes3DSubplot) -- Matplotlibの3D軸オブジェクト。

• xrange (list of float) -- x軸の範囲 [xmin, xmax]。

• yrange (list of float) -- y軸の範囲 [ymin, ymax]。

• zrange (list of float) -- z軸の範囲 [zmin, zmax]。

• fontsize (int) -- 軸ラベルと目盛りのフォントサイズ。

• legend_fontsize (int) -- 凡例のフォントサイズ (ただしこの関数では直接使用されません)。

draw_atoms(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._subplots.Axes3DSubplot) -- Matplotlibの3D軸オブジェクト。

• structure (pymatgen.core.structure.Structure) -- 描画するPymatgenのStructureオブジェクト。

• draw_range (list of list of float) -- [[xmin, xmax], [ymin, ymax], [zmin, zmax]]形式の描画範囲。

• kr (float) -- 原子半径をスケーリングするための係数。

• atom_alpha (float) -- 原子の透明度（0.0-1.0）。

• vector_r (float) -- 速度ベクトル線の太さ。

• vector_length (float) -- 速度ベクトルの最大描画長さ。

• arrow_length_ratio (float) -- 速度ベクトルの矢印部分の長さ比率。

戻り値:

描画された原子のみを含む新しいStructureオブジェクトと、描画情報を含む辞書。

戻り値の型:

tuple of (pymatgen.core.structure.Structure, dict)

draw_atoms2(structure, draw_range, kr=400.0)

(未定義変数を含むため機能しない可能性あり) 指定された描画範囲内の原子をプロットし、新しいStructureオブジェクトとラベル辞書を返します。

各原子は原子名と原子番号に基づいて色とサイズ（半径）が決定されます。

パラメータ:

• structure (pymatgen.core.structure.Structure) -- 描画するPymatgenのStructureオブジェクト。

• draw_range (list of list of float) -- [[xmin, xmax], [ymin, ymax], [zmin, zmax]]形式の描画範囲。

• kr (float) -- 原子半径をスケーリングするための係数。

戻り値:

描画された原子のみを含む新しいStructureオブジェクトと、原子名をキーとするラベル辞書。

戻り値の型:

tuple of (pymatgen.core.structure.Structure, dict)

draw_bonds(ax, structure, distances, bond_r, color='gray')

指定された3D軸上に原子間の結合を描画します。

`distances`リストに基づいて結合を描画します。

パラメータ:

• ax (matplotlib.axes._subplots.Axes3DSubplot) -- Matplotlibの3D軸オブジェクト。

• structure (pymatgen.core.structure.Structure) -- 結合を描画するPymatgenのStructureオブジェクト。

• distances (list of list) -- 結合する原子ペアとその距離のリスト。[[i, j, d], ...]の形式。

• bond_r (float) -- 結合線の太さ。

• color (str) -- 結合線の色。

戻り値:

描画された結合線オブジェクトのリスト。

戻り値の型:

list of matplotlib.lines.Line2D

draw_box(axis, structure, origin, ax, ay, az, color='black', linewidth=1.0)

3D軸上に単位セル（または指定された範囲）のボックスを描画します。

パラメータ:

• axis (matplotlib.axes._subplots.Axes3DSubplot) -- Matplotlibの3D軸オブジェクト。

• structure (pymatgen.core.structure.Structure) -- 基になるPymatgenのStructureオブジェクト。

• origin (list or numpy.ndarray) -- ボックスの開始点となる原点座標。

• ax (list or numpy.ndarray) -- x方向のベクトル。

• ay (list or numpy.ndarray) -- y方向のベクトル。

• az (list or numpy.ndarray) -- z方向のベクトル。

• color (str) -- ボックスの線の色。

• linewidth (float) -- ボックスの線の太さ。

draw_structure(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 (module or object) -- 描画に使用するmatplotlib.pyplotオブジェクト、またはそれをラップするtkpltオブジェクト。

• ax (matplotlib.axes._subplots.Axes3DSubplot) -- 描画するMatplotlibの3D軸オブジェクト。

• structure (pymatgen.core.structure.Structure) -- 描画するPymatgenのStructureオブジェクト。

• draw_range (list of list of float) -- x,y,z方向の描画範囲の相対座標 [[xmin_rel, xmax_rel], [ymin_rel, ymax_rel], [zmin_rel, zmax_rel]]。

• max_distance (float) -- 結合とみなす原子間の最大距離（Å）。

• kr (float) -- 原子半径をスケーリングするための係数。

• atom_alpha (float) -- 原子の透明度（0.0-1.0）。

• bond_r (float) -- 結合線の太さ。

• vector_r (float) -- 速度ベクトル線の太さ。

• vector_length (float) -- 速度ベクトルの最大描画長さ。

• arrow_length_ratio (float) -- 速度ベクトルの矢印部分の長さ比率。

• displacement (float) -- アニメーションにおける原子の変位スケール因子。

• sleep (float) -- アニメーションのフレーム間隔（秒）。

• time_step (float) -- アニメーションの仮想的な時間ステップ。

• nstep (int) -- アニメーションの総ステップ数。

• animation (bool) -- Trueの場合、原子の動きをアニメーション表示します。

• stop_callback (callable or None) -- アニメーションを停止させる条件をチェックするコールバック関数。Trueを返すとアニメーションが停止します。

• fontsize (int) -- 軸ラベルなどのフォントサイズ。

• legend_fontsize (int) -- 凡例のフォントサイズ。

elements(structure=None)

指定された構造に含まれる元素のリストと、それぞれの原子量、原子番号、数を取得します。

パラメータ:

structure (pymatgen.core.structure.Structure or None) -- 情報を抽出するPymatgenのStructureオブジェクト。Noneの場合、内部の構造が使用されます。

戻り値:

各元素の原子名、原子量、原子番号、数を含む辞書のリスト。構造がNoneの場合はNone。

戻り値の型:

list of dict or None

get_asymmetric_sites(structure)

指定された構造の非対称サイトのリストを取得します。

結晶学的に等価なサイトのグループから、代表となるサイトのみを抽出します。

パラメータ:

structure (pymatgen.core.structure.Structure) -- 非対称サイトを取得するPymatgenのStructureオブジェクト。

戻り値:

非対称Siteオブジェクトのリスト。

戻り値の型:

list of pymatgen.core.sites.Site

get_atom_color(atom_name, Z)

指定された原子名と原子番号に基づいて原子の描画色を決定します。

既知の原子（O, S, Se, Bi）には特定の色を割り当て、それ以外の原子には原子番号に基づく擬似ランダムな色を生成します。

パラメータ:

• atom_name (str) -- 原子名（例: "O", "Fe"）。

• Z (int) -- 原子番号。

戻り値:

原子の色を表す文字列（例: "red"）またはRGBタプル。

戻り値の型:

str or tuple of float

get_atom_inf(atom_name, charge=None, ncoordination=None)

指定された原子名から原子の基本情報（質量、原子番号、電荷、イオン半径、電子構造）を辞書形式で取得します。

パラメータ:

• atom_name (str) -- 原子名（例: "O", "Fe"）。

• charge (int or None) -- イオンの電荷。Noneの場合、一般的な酸化状態の最初のものが使用されます。

• ncoordination (int or None) -- 配位数。Noneの場合、配位数を考慮しないイオン半径が取得されます。

戻り値:

原子情報を含む辞書。

戻り値の型:

dict

get_composition_inf(composition)

PymatgenのCompositionオブジェクトから詳細な情報を辞書形式で取得します。

組成、原子数、種数、分子量などを含みます。

パラメータ:

composition (pymatgen.core.Composition) -- 情報を取得するPymatgenのCompositionオブジェクト。

戻り値:

Compositionオブジェクトの詳細情報を含む辞書。

戻り値の型:

dict

get_ionic_radius(atom_name, charge=None, ncoordination=None)

指定された原子名、電荷、配位数に基づいてイオン半径を取得します。

PymatgenのElementオブジェクトからイオン半径のデータにアクセスします。 電荷が指定されない場合、一般的な酸化状態の最初のものが使用されます。 配位数が指定されない場合、指定された電荷に最も適合する半径が返されます。

パラメータ:

• atom_name (str) -- 原子名（例: "O", "Fe"）。

• charge (int or None) -- イオンの電荷。Noneの場合、一般的な酸化状態が使用されます。

• ncoordination (int or None) -- 配位数。Noneの場合、配位数を考慮しない半径が返されます。

戻り値:

原子名、電荷、配位数に対応するイオン半径。見つからない場合は1.0またはNone。

戻り値の型:

float or None

get_site_inf(site)

指定されたサイトから基本的な情報を辞書形式で取得します。

組成、種、座標などを含みます。

パラメータ:

site (pymatgen.core.sites.Site) -- 情報を取得するPymatgenのSiteオブジェクト。

戻り値:

サイトの基本的な情報を含む辞書。

戻り値の型:

dict

get_site_occ_inf(site)

指定されたサイトの占有情報（Composition情報）を辞書形式で取得します。

サイトの文字列表現、化学式、重さ、組成などを返します。

パラメータ:

site (pymatgen.core.sites.Site) -- 情報を取得するPymatgenのSiteオブジェクト。

戻り値:

サイトの占有情報を含む辞書。

戻り値の型:

dict

get_sites(structure)

指定された構造のすべてのサイトのリストを取得します。

パラメータ:

structure (pymatgen.core.structure.Structure) -- サイトを取得するPymatgenのStructureオブジェクト。

戻り値:

Structureに含まれるすべてのSiteオブジェクトのリスト。

戻り値の型:

list of pymatgen.core.sites.Site

get_spacegroup()

現在のStructureオブジェクトの空間群情報（シンボルと番号）を取得します。

戻り値:

(空間群シンボル, 空間群番号)のタプル。

戻り値の型:

tuple of (str, int)

get_species_and_occu(structure)

指定された構造のサイトに存在する元素とその占有率のリストを取得します。

パラメータ:

structure (pymatgen.core.structure.Structure) -- 情報を取得するPymatgenのStructureオブジェクト。

戻り値:

元素と占有率のリスト。

戻り値の型:

list

get_structure(structure=None)

現在のインスタンスに設定されているStructureオブジェクトを取得します。

もしsymmetrized_structureが設定されていればそれを優先し、そうでなければstructureを返します。 引数にstructureが指定された場合はそれをそのまま返します。

パラメータ:

structure (pymatgen.core.structure.Structure or None) -- 使用するPymatgenのStructureオブジェクト。指定しない場合はインスタンスの属性が使用されます。

戻り値:

PymatgenのStructureオブジェクト。見つからない場合はNone。

戻り値の型:

pymatgen.core.structure.Structure or None

get_structure_inf()

現在のStructureオブジェクトから様々な情報を辞書形式で取得します。

格子パラメータ、体積、距離行列、組成、原子座標など、Structureオブジェクトの基本的な情報を集約します。

戻り値:

構造の様々な情報を含む辞書。

戻り値の型:

dict

get_symmetrized_structure(symprec=0.001)

現在のStructureオブジェクトから対称化された構造を取得します。

SpacegroupAnalyzerを用いて対称性解析を行い、対称化されたStructureオブジェクトを返します。

パラメータ:

symprec (float) -- 対称性操作を決定するための許容誤差。

戻り値:

対称化されたPymatgenのSymmetrizedStructureオブジェクト。

戻り値の型:

pymatgen.symmetry.structure.SymmetrizedStructure

get_symmetry_inf(symprec=0.001)

現在のStructureオブジェクトの対称性に関する詳細情報を辞書形式で取得します。

空間群データセット、シンボル、番号、Hall記号、対称操作、点群情報などを含みます。

パラメータ:

symprec (float) -- 対称性操作を決定するための許容誤差。

戻り値:

対称性に関する詳細情報を含む辞書。

戻り値の型:

dict

get_xyz_range(structure, draw_range)

描画範囲の相対座標を絶対座標に変換します。

`draw_range`がNoneの場合、単位セルの範囲を使用します。

パラメータ:

• structure (pymatgen.core.structure.Structure) -- 基になるPymatgenのStructureオブジェクト。

• draw_range (list of list of float) -- x,y,z方向の描画範囲の相対座標 [[xmin_rel, xmax_rel], [ymin_rel, ymax_rel], [zmin_rel, zmax_rel]]。

戻り値:

x, y, z軸の絶対座標範囲のタプル。

戻り値の型:

tuple of list of float

print_methods(obj)

指定されたオブジェクトのメンバ関数（メソッド）を標準出力に表示します。

パラメータ:

obj (object) -- メンバ関数を出力するオブジェクト。

print_variables(obj)

指定されたオブジェクトのメンバ変数を標準出力に表示します。

パラメータ:

obj (object) -- メンバ変数を出力するオブジェクト。

read(path, primitive=False)

指定されたファイルパスから結晶構造を読み込み、Structureオブジェクトとして設定します。

パラメータ:

• path (str) -- 読み込む構造ファイルのパス。

• primitive (bool) -- Trueの場合、読み込まれた構造をプリミティブセルに変換します。

戻り値:

読み込まれたPymatgenのStructureオブジェクト。

戻り値の型:

pymatgen.core.structure.Structure

structure2inf(structure=None)

構造から格子情報とサイト情報を抽出しますが、この関数は途中で処理が終了し、辞書を返しません。

パラメータ:

structure (pymatgen.core.structure.Structure or None) -- 情報を抽出するPymatgenのStructureオブジェクト。Noneの場合、内部の構造が使用されます。

structure2inf_flat(structure=None, symprec=0.0001, coordinate='fc', site_name='as')

構造からフラットな形式で情報を抽出し、辞書として返します。

空間群情報、格子定数、化学式、原子数、組成式、各原子の座標（分数または実空間）などを含みます。 原子の座標は、サイトIDまたは原子名と連番でアクセスできるように格納されます。

パラメータ:

• structure (pymatgen.core.structure.Structure or None) -- 情報を抽出するPymatgenのStructureオブジェクト。Noneの場合、内部の構造が使用されます。

• symprec (float) -- 対称性解析に使用する許容誤差。

• coordinate (str) -- 出力する座標の形式。"f"で分数座標、"c"で実空間座標。両方含める場合は"fc"のように指定します。

• site_name (str) -- サイト名の命名規則。"s"でサイトIDベース、"a"で原子名ベース。両方含める場合は"as"のように指定します。

戻り値:

構造のフラットな情報を含む辞書。

戻り値の型:

dict

symmetrize(structure, prec=0.001)

指定された構造の対称性解析を行い、空間群情報と対称化された構造を取得します。

結果はインスタンスの属性に保存されます。

パラメータ:

• structure (pymatgen.core.structure.Structure) -- 対称性解析を行うPymatgenのStructureオブジェクト。

• prec (float) -- 対称性操作を決定するための許容誤差。

戻り値:

(空間群番号, 空間群シンボル, 対称化されたStructureオブジェクト)のタプル。

戻り値の型:

tuple of (int, str, pymatgen.symmetry.structure.SymmetrizedStructure)

to(path, structure=None, symprec=0.001, print_level=0)

構造情報を指定されたファイルパスに保存します。

現在はCIF形式での symmetrized_structure の保存をサポートしています。

パラメータ:

• path (str) -- 構造を保存するファイルのパス。

• structure (pymatgen.core.structure.Structure or None) -- 保存するPymatgenのStructureオブジェクト。Noneの場合、内部の構造が使用されます。

• symprec (float) -- 対称性解析に使用する許容誤差。symmetrized_structureのCifWriterに渡されます。

• print_level (int) -- 詳細な出力レベル。0より大きい場合、保存情報を表示します。

戻り値:

保存が成功した場合True、Structureオブジェクトが見つからない場合はNone。

戻り値の型:

bool or None

class tklib.tkcrystal.tkpymatgen.tkPymatgenVASP(**args)

ベースクラス: tkObject

VASPの出力ファイル（vasprun.xml, POSCAR）を扱うためのPymatgenラッパーを提供します。

このクラスは、VASP計算の結果から構造情報やその他のデータを読み込み、管理することを目的としています。

read_structure(infile, vasprun=None)

指定されたファイルから結晶構造を読み込み、PymatgenのStructureオブジェクトとして設定します。

vasprun.xmlファイルまたはPOSCARファイルからの読み込みをサポートします。 vasprun.xmlを読み込んだ場合、最終構造を取得します。

パラメータ:

• infile (str) -- 読み込む構造ファイルのパス（例: 'vasprun.xml'または'POSCAR'）。

• vasprun (pymatgen.io.vasp.outputs.Vasprun or None) -- 既存のVasprunオブジェクト。指定された場合、そのfinal_structureを使用します。 Noneの場合、infileが'vasprun.xml'であれば新たにVasprunを読み込みます。

戻り値:

読み込みに成功した場合、(PoscarオブジェクトまたはVasprunオブジェクト, Structureオブジェクト)のタプルを返します。 失敗した場合は(False, False)を返します。

戻り値の型:

tuple of (pymatgen.io.vasp.inputs.Poscar or pymatgen.io.vasp.outputs.Vasprun or bool, pymatgen.core.structure.Structure or bool)

read_vasprun(infile='vasprun.xml', validate=False)

指定されたファイルからVASPのvasprun.xmlデータを読み込みます。

ファイルが'.xml'拡張子を持つ場合、PymatgenのVasprunオブジェクトとして読み込みます。 必要に応じてXMLの妥当性検証を行うこともできます。

パラメータ:

• infile (str) -- 読み込むvasprun.xmlファイルのパス。デフォルトは'vasprun.xml'です。

• validate (bool) -- XMLファイルの妥当性を検証するかどうかを示すフラグ。Trueの場合、無効なXMLは読み込みません。

戻り値:

読み込みに成功した場合、Vasprunオブジェクトを返します。それ以外の場合はNoneを返します。

戻り値の型:

pymatgen.io.vasp.outputs.Vasprun or None

tklib.tkcrystal.tkpymatgen.to_str(v)

与えられた数値vを分数または記号の文字列に変換します。

特定の浮動小数点値を'1/2', '-1/2'などの分数表現や'+', '-'記号に変換します。 0.0はNoneに、正の値は先頭の'+'が削除された文字列になります。

パラメータ:

v (float) -- 変換する浮動小数点数。

戻り値:

変換された文字列、またはNone。

戻り値の型:

str or None

tklib.tkcrystal.tkpymatgen.vector_to_str(v)

3要素のベクトルをx, y, z成分を含む文字列に変換します。

to_str関数を使用して各成分を変換し、非Noneの成分を結合して文字列を生成します。 先頭の'+'記号は削除されます。

パラメータ:

v (list or tuple or numpy.ndarray) -- 変換する3要素のベクトル。

戻り値:

変換されたベクトル文字列。

戻り値の型:

str