tkcrystalobject.py Technical Documentation

ライブラリの機能や目的

tkcrystalobject.py ライブラリは、Pythonで結晶構造データをオブジェクト指向で管理、操作、計算するためのフレームワークです。 結晶構造に関する多様な情報（格子パラメータ、空間群、原子タイプ、原子サイト、化学組成など）を一元的に保持し、それらの情報を基に様々な結晶学的な計算や解析を実行することを目的としています。

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

  • 結晶構造の定義と管理: 格子パラメータ、格子ベクトル、空間群、原子タイプ、原子サイトなどの結晶学的要素を設定、取得、およびクリアします。

  • 原子サイトの操作: 非対称単位の原子サイトを、空間群の対称操作と並進操作によって単位胞全体に展開（拡張）します。これにより、完全な単位胞内の原子配置を生成します。

  • 化学組成と密度計算: 結晶の化学組成を分析し、組成式、単位胞の分子量、密度、原子密度などを計算します。

  • 距離と角度計算: 単位胞座標における原子間の距離や角度、最近接原子サイトを計算します。

  • 格子変換と計量テンソル: 格子パラメータと格子ベクトルの間の変換、および実空間と逆空間の計量テンソルを計算・管理します。

  • 回折計算関連: \(hkl\) 面間隔、回折角、構造因子、\(hkl\) の多重度などを計算します。

このライブラリは、結晶構造データの表現、解析、およびシミュレーションを行うアプリケーション開発において、基盤となる機能を提供することで、複雑な結晶学計算の簡素化と効率化に貢献します。

importする方法

tkcrystalobject.py ライブラリは、主に tkCrystalObject クラスを提供します。このクラスを他のPythonプログラムからインポートするには、以下のコードを使用します。

from tkcrystalobject import tkCrystalObject

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

このライブラリが動作するために必要な非標準ライブラリは以下の通りです。

  • numpy: 高度な数値計算（配列操作、線形代数、三角関数など）

  • tklib: このライブラリが依存するカスタムライブラリパッケージ（tkobject, tkre, tkutils, tksci, tkcrystal モジュールを含む）

これらのライブラリは、Pythonのパッケージマネージャー pip を使用してインストールできます。

pip install numpy tklib

注意: tklib は通常、tkcrystalobject.py と同じプロジェクトの一部として提供されるカスタムライブラリです。もし pip install tklib でインストールできない場合は、tklib パッケージのソースコードを tkcrystalobject.py と同じ階層、またはPythonのモジュール検索パス上に配置する必要があります。

importできる変数と関数

tkcrystalobject.py から直接インポートできる主要な要素は、tkCrystalObject クラスです。

クラス: tkCrystalObject

結晶構造全体を管理するためのルートパッケージです。格子パラメータ、空間群、原子タイプ、原子サイトなどの情報を持ち、それらに関する様々な操作や計算を提供します。

コンストラクタ: __init__(self, **args)

  • 動作: tkCrystalObject の新しいインスタンスを初期化します。内部で InitializeRoot() を呼び出して、すべての結晶学的プロパティをデフォルト値に設定します。

  • 引数:

    • **args: キーワード引数として、将来的な拡張のための任意の初期設定を受け入れますが、現在の実装では直接使用されていません。

  • 戻り値: なし

特殊メソッド: __del__(self)

  • 動作: オブジェクトが破棄されるときに呼び出されるデストラクタです。現在の実装では何もしません。

  • 引数: なし

  • 戻り値: なし

__str__(self)

  • 動作: オブジェクトの文字列表現を返します。現在の実装では、オブジェクトのクラスパス（例: tkcrystalobject.tkCrystalObject）を返します。

  • 引数: なし

  • 戻り値: str - オブジェクトのクラスパス。

初期化・クリア関連メソッド: InitializeRoot(self)

  • 動作: 結晶名、試料名、化学組成、格子パラメータ、計量テンソル、空間群、原子タイプリスト、原子サイトリストなど、すべての結晶学的プロパティを初期状態にリセットします。温度は25.0℃に設定されます。

  • 引数: なし

  • 戻り値: なし

ClearAtomSiteList(self)

  • 動作: 登録されているすべての原子サイト（非対称単位）のリストをクリアします。

  • 引数: なし

  • 戻り値: list - クリアされた空の原子サイトリスト。

ClearAtomTypeList(self)

  • 動作: 登録されているすべての原子タイプ（元素種や電荷状態）のリストをクリアします。

  • 引数: なし

  • 戻り値: list - クリアされた空の原子タイプリスト。

ClearSpaceGroup(self)

  • 動作: 空間群情報を初期化し、デフォルトで P1 (三斜晶系、空間群番号1) に設定します。

  • 引数: なし

  • 戻り値: tkSpaceGroup オブジェクト - 初期化された空間群オブジェクト。

命名・温度関連メソッド: SetSampleName(self, name = None, MakeFromPath = 0)

  • 動作: 試料名を設定します。MakeFromPath が 1 の場合、オブジェクトの path 属性からファイル名を抽出して試料名とします。

  • 引数:

    • name: str - 設定する試料名。None の場合、MakeFromPath の値に応じて動作が変わります。

    • MakeFromPath: int - 1 の場合、self.path からファイル名を取得して試料名を設定します。デフォルトは 0。

  • 戻り値: なし

SampleName(self, Create = 0)

  • 動作: 現在の試料名を取得します。試料名が設定されていない場合、Create が 1 であれば self.path からファイル名を抽出して返します。

  • 引数:

    • Create: int - 1 の場合、試料名が未設定であればファイルパスから生成を試みます。デフォルトは 0。

  • 戻り値: str - 試料名、または None。

SetCrystalName(self, name = None, MakeFromPath = 0)

  • 動作: 結晶名を設定します。MakeFromPath が 1 の場合、オブジェクトの path 属性からファイル名を抽出して結晶名とします。

  • 引数:

    • name: str - 設定する結晶名。None の場合、MakeFromPath の値に応じて動作が変わります。

    • MakeFromPath: int - 1 の場合、self.path からファイル名を取得して結晶名を設定します。デフォルトは 0。

  • 戻り値: なし

CrystalName(self, Create = 0)

  • 動作: 現在の結晶名を取得します。結晶名が設定されていない場合、Create が 1 であれば化学組成式、または self.path からファイル名を抽出して返します。

  • 引数:

    • Create: int - 1 の場合、結晶名が未設定であれば化学組成式またはファイルパスから生成を試みます。デフォルトは 0。

  • 戻り値: str - 結晶名、または None。

SetTemperature(self, T)

  • 動作: 結晶の温度を設定します。

  • 引数:

    • T: float - 温度の値。

  • 戻り値: なし

Temperature(self,)

  • 動作: 現在設定されている結晶の温度を取得します。

  • 引数: なし

  • 戻り値: float - 設定されている温度。

原子タイプ・原子サイトリスト関連メソッド: nAtomType(self)

  • 動作: 登録されている原子タイプの数を取得します。

  • 引数: なし

  • 戻り値: int - 原子タイプの数。

AtomTypeList(self)

  • 動作: 登録されている tkAtomType オブジェクトのリストを取得します。

  • 引数: なし

  • 戻り値: list - tkAtomType オブジェクトのリスト。

natom_site(self)

  • 動作: 非対称単位の原子サイトの数を取得します。

  • 引数: なし

  • 戻り値: int - 非対称単位の原子サイトの数。

nAtomSite(self)

  • 動作: natom_site() メソッドのエイリアスです。非対称単位の原子サイトの数を取得します。

  • 引数: なし

  • 戻り値: int - 非対称単位の原子サイトの数。

atom_site_list(self, mode = 0)

  • 動作: 原子サイトのリストを取得します。mode=0 で非対称単位のサイト、mode=1 で展開（拡張）された全サイトを返します。

  • 引数:

    • mode: int - 0 なら非対称単位の原子サイト、1 なら展開された原子サイトのリストを返します。デフォルトは 0。

  • 戻り値: list - tkAtomSite オブジェクトのリスト。

AtomSiteList(self, mode = 0)

  • 動作: atom_site_list() メソッドのエイリアスです。原子サイトのリストを取得します。

  • 引数:

    • mode: int - 0 なら非対称単位の原子サイト、1 なら展開された原子サイトのリストを返します。デフォルトは 0。

  • 戻り値: list - tkAtomSite オブジェクトのリスト。

nexpanded_atom_site(self)

  • 動作: 空間群の対称操作によって展開（拡張）された原子サイトの総数を取得します。

  • 引数: なし

  • 戻り値: int - 展開された原子サイトの総数。

nExpandedAtomSiteList(self)

  • 動作: nexpanded_atom_site() メソッドのエイリアスです。展開された原子サイトの総数を取得します。

  • 引数: なし

  • 戻り値: int - 展開された原子サイトの総数。

expanded_atom_site_list(self)

  • 動作: 空間群の対称操作によって展開（拡張）された tkAtomSite オブジェクトのリストを取得します。

  • 引数: なし

  • 戻り値: list - 展開された tkAtomSite オブジェクトのリスト。

ExpandedAtomSiteList(self)

  • 動作: expanded_atom_site_list() メソッドのエイリアスです。展開された原子サイトのリストを取得します。

  • 引数: なし

  • 戻り値: list - 展開された tkAtomSite オブジェクトのリスト。

化学組成関連メソッド: ChemicalComposition(self)

  • 動作: 単位胞の化学組成式（最小単位）を取得します。

  • 引数: なし

  • 戻り値: str - 化学組成式。

SetChemicalComposition(self, composition)

  • 動作: 単位胞の化学組成式を設定します。

  • 引数:

    • composition: str - 設定する化学組成式。

  • 戻り値: なし

SumChemicalComposition(self)

  • 動作: 単位胞内の全原子の総化学組成式を取得します。

  • 引数: なし

  • 戻り値: str - 総化学組成式。

get_atom_name_list(self, mode = 'all', NameOnly = True)

  • 動作: 原子名または原子タイプ名（記号）のリストを取得します。mode に応じて対象となる原子サイトの種類を選択できます。

  • 引数:

    • mode: str - all (展開された全サイト), asym (非対称単位サイト), type (原子タイプ) のいずれか。デフォルトは all。

    • NameOnly: bool - True の場合、原子のシンボルのみを返します（例: 'O'）。False の場合、完全な原子タイプ名（例: 'O1', 'O2'）を返します。デフォルトは True。

  • 戻り値: list - 原子名の文字列のリスト。

get_position_list(self, mode = 'all', IsReduce01 = False)

  • 動作: 原子サイトの座標リストを取得します。mode に応じて対象となる原子サイトの種類を選択できます。

  • 引数:

    • mode: str - all (展開された全サイト), asym (非対称単位サイト) のいずれか。デフォルトは all。

    • IsReduce01: bool - True の場合、座標を \([0, 1)\) の範囲に正規化します。デフォルトは False。

  • 戻り値: list - 各原子サイトの座標（[x, y, z] のリスト）のリスト。

SetSumChemicalComposition(self, composition)

  • 動作: 単位胞内の全原子の総化学組成式を設定します。

  • 引数:

    • composition: str - 設定する総化学組成式。

  • 戻り値: なし

FormulaUnit(self)

  • 動作: 単位胞あたりの化学式単位数 (\(Z\)) を取得します。

  • 引数: なし

  • 戻り値: int - 化学式単位数。

SetFormulaUnit(self, Z)

  • 動作: 単位胞あたりの化学式単位数 (\(Z\)) を設定します。

  • 引数:

    • Z: int - 設定する化学式単位数。

  • 戻り値: なし

IsAnionic(self, name)

  • 動作: 指定された原子名がアニオン的（例: O, S, F, Clなど）であるかどうかを判定します。

  • 引数:

    • name: str - 原子名。

  • 戻り値: int - アニオン的なら 1、そうでなければ 0。

IsCationic(self, name)

  • 動作: 指定された原子名がカチオン的であるかどうかを判定します（IsAnionic の逆）。

  • 引数:

    • name: str - 原子名。

  • 戻り値: int - カチオン的なら 1、そうでなければ 0。

AnalyzeChemicalComposition(self, sort = '')

  • 動作: 登録されている原子タイプと展開された原子サイトに基づいて、結晶の化学組成を分析し、単位胞の総化学組成式 (SumChemicalComposition) と最小単位の化学組成式 (ChemicalComposition) を計算して設定します。化学式単位数 (FormulaUnit) も計算されます。

  • 引数:

    • sort: str - 原子名のソート順を指定します。atom_name (アルファベット順), atomic_number (原子番号順), atomic_mass (原子質量順)。デフォルトは空文字列 (カチオン、アニオンの順)。

  • 戻り値: str - 計算された最小単位の化学組成式。

UnitcellWeight(self)

  • 動作: 単位胞の分子量を取得します。

  • 引数: なし

  • 戻り値: float - 単位胞の分子量、または 0.0 (未計算の場合)。

SetUnitcellWeight(self, MW)

  • 動作: 単位胞の分子量を設定します。

  • 引数:

    • MW: float - 設定する分子量。

  • 戻り値: なし

Density(self)

  • 動作: 結晶の密度を取得します。

  • 引数: なし

  • 戻り値: float - 密度、または 0.0 (未計算の場合)。

AtomDensity(self)

  • 動作: 単位胞内の原子密度（単位体積あたりの原子数）を計算し、取得します。

  • 引数: なし

  • 戻り値: float - 原子密度。

SetDensity(self, density)

  • 動作: 結晶の密度を設定します。

  • 引数:

    • density: float - 設定する密度。

  • 戻り値: なし

SetAtomDensity(self, density)

  • 動作: 結晶の原子密度を設定します。

  • 引数:

    • density: float - 設定する原子密度。

  • 戻り値: なし

CalculateDensity(self)

  • 動作: 登録されている原子サイトと原子タイプ、および単位胞の体積から、単位胞の分子量と結晶の密度を計算します。

  • 引数: なし

  • 戻り値: float - 計算された密度。

原子サイト検索関連メソッド: FindAtomType(self, atomtype)

  • 動作: 指定された原子タイプ名に合致する tkAtomType オブジェクトのリストにおけるインデックスを検索します。

  • 引数:

    • atomtype: str - 検索する原子タイプ名。

  • 戻り値: int - 見つかった原子タイプのインデックス (0以上)、見つからなければ -1。

FindAtomSite(self, atomname, mode = 0)

  • 動作: 指定された原子名に合致する tkAtomSite オブジェクトを検索します。mode=0 で非対称単位サイトから検索します。

  • 引数:

    • atomname: str - 検索する原子名。

    • mode: int - 現在は 0 のみサポートされ、非対称単位サイトから検索します。

  • 戻り値: tkAtomSite オブジェクト - 見つかった原子サイトオブジェクト、見つからなければ None。

FindiAtomType(self, atomname)

  • 動作: 指定された原子名（例: "O1" から "O" を抽出）に合致する tkAtomType オブジェクトのリストにおけるインデックスを検索します。SplitAtomName を使用して柔軟に検索します。

  • 引数:

    • atomname: str - 検索する原子名。

  • 戻り値: int - 見つかった原子タイプのインデックス (0以上)、見つからなければ -1。

find_nearest_site(self, pos0, irange = [1, 1, 1])

  • 動作: 指定された単位胞座標 pos0 に最も近い原子サイト（展開されたリストから）のインデックスを検索します。検索範囲は irange で指定されたセル並進の範囲で行われます。

  • 引数:

    • pos0: list or numpy.ndarray - 検索の基準となる単位胞座標 [x, y, z]。

    • irange: list - 検索する単位胞並進の範囲 [ix, iy, iz]。例: [1,1,1] は \(\pm 1\) セル範囲。デフォルトは [1, 1, 1]。

  • 戻り値: int - 最も近い原子サイトのインデックス、見つからなければ -1。

FindNearestSite(self, pos0, irange = [1, 1, 1])

  • 動作: find_nearest_site() メソッドのエイリアスです。指定された位置に最も近い原子サイトのインデックスを検索します。

  • 引数:

    • pos0: list or numpy.ndarray - 検索の基準となる単位胞座標 [x, y, z]。

    • irange: list - 検索する単位胞並進の範囲 [ix, iy, iz]。デフォルトは [1, 1, 1]。

  • 戻り値: int - 最も近い原子サイトのインデックス。

原子サイト展開・ブラーべ格子関連メソッド: BurstToP1(self)

  • 動作: 空間群を P1 (三斜晶系、空間群番号1) に設定し、その結果として現在の原子サイトリストを完全に展開された原子サイトリストに置き換えます。これにより、すべての原子サイトが非対称単位のサイトとして扱われ、全ての対称性が失われます。

  • 引数: なし

  • 戻り値: なし

GetBravaisLattice(self)

  • 動作: 現在設定されている空間群のブラーべ格子タイプ（例: 'P', 'F', 'I'など）を取得します。

  • 引数: なし

  • 戻り値: str - ブラーべ格子タイプ。

expand_coordinates(self, DoTranslation = 1)

  • 動作: 非対称単位の原子サイト (self.__AtomSiteList) を、現在の空間群の対称操作と、必要であれば並進操作 (DoTranslation = 1 の場合) を適用して、単位胞内のすべての等価な原子サイトに展開（拡張）します。この処理により、self.__ExpandedAtomSiteList が生成・更新され、各原子サイトの多重度も設定されます。また、密度と化学組成も再計算されます。

  • 引数:

    • DoTranslation: int - 1 の場合、並進操作も適用して座標を展開します。0 の場合、並進操作は無視されます。デフォルトは 1。

  • 戻り値: なし

ExpandCoordinates(self, DoTranslation = 1)

  • 動作: expand_coordinates() メソッドのエイリアスです。非対称単位の原子サイトを空間群対称操作と並進操作で単位胞全体に展開します。

  • 引数:

    • DoTranslation: int - 1 の場合、並進操作も適用して座標を展開します。デフォルトは 1。

  • 戻り値: なし

距離・角度計算関連メソッド: GetimaxByRmax(self, Rmax)

  • 動作: 指定された最大距離 Rmax をカバーするために必要な単位胞並進の最大インデックス [ix, iy, iz] を概算します。

  • 引数:

    • Rmax: float - 最大距離。

  • 戻り値: tuple - (ix_max, iy_max, iz_max) の形式で、各軸の最大並進インデックス。

GetReciprocalDistanceFromK(self, k0, k1)

  • 動作: 逆空間における2つの点 \(k_0 = [h_0, k_0, l_0]\) と \(k_1 = [h_1, k_1, l_1]\) 間の距離を計算します。これは逆空間の計量テンソル \(g^{ij}\) を用いて計算されます。

  • 引数:

    • k0: list or numpy.ndarray - 1点目の逆空間座標 [h, k, l]。

    • k1: list or numpy.ndarray - 2点目の逆空間座標 [h, k, l]。

  • 戻り値: float - \(k_0\) と \(k_1\) 間の逆空間距離。

distance(self, pos0, pos1, **kwargs)

  • 動作: 単位胞座標 pos0 = [x0, y0, z0] と pos1 = [x1, y1, z1] 間の実空間距離を計算します。実空間の計量テンソル \(g_{ij}\) を用いて計算されます。 $\(d = \sqrt{g_{00} \Delta x^2 + g_{11} \Delta y^2 + g_{22} \Delta z^2 + 2g_{01} \Delta x \Delta y + 2g_{02} \Delta x \Delta z + 2g_{12} \Delta y \Delta z}\)\( ここで \)\Delta x = x_1 - x_0\(, \)\Delta y = y_1 - y_0\(, \)\Delta z = z_1 - z_0$ です。

  • 引数:

    • pos0: list or numpy.ndarray - 1点目の単位胞座標 [x, y, z]。

    • pos1: list or numpy.ndarray - 2点目の単位胞座標 [x, y, z]。

    • **kwargs: その他のキーワード引数（現在の実装では使用されていません）。

  • 戻り値: float - \(pos0\) と \(pos1\) 間の実空間距離。

GetInterAtomicDistance(self, pos0, pos1, **kwargs)

  • 動作: distance() メソッドのエイリアスです。2つの単位胞座標間の実空間距離を計算します。

  • 引数:

    • pos0: list or numpy.ndarray - 1点目の単位胞座標 [x, y, z]。

    • pos1: list or numpy.ndarray - 2点目の単位胞座標 [x, y, z]。

    • **kwargs: その他のキーワード引数。

  • 戻り値: float - 実空間距離。

FindNearestEquivalentFractionCoordinate(self, x2, x)

  • 動作: 座標 \(x\) に最も近い、単位胞座標 \(x2\) の等価な小数座標（\(x2 \pm n\) の形式）を見つけます。

  • 引数:

    • x2: float - 基準となる小数座標。

    • x: float - 比較対象の小数座標。

  • 戻り値: float - \(x\) に最も近い \(x2\) の等価な小数座標。

get_nearest_interatomic_distance_with_offset(self, pos0, pos1, AllowZero = True, irange = [1, 1, 1], **kwargs)

  • 動作: 2つの単位胞座標 pos0 と pos1 間の最近接距離を計算します。この際、単位胞の並進を考慮し、最も近い等価位置を見つけます。結果として、距離と、そのときの並進オフセット [ix, iy, iz] を返します。

  • 引数:

    • pos0: list or numpy.ndarray - 1点目の単位胞座標 [x, y, z]。

    • pos1: list or numpy.ndarray - 2点目の単位胞座標 [x, y, z]。

    • AllowZero: bool - True の場合、距離がゼロの点も許容します。デフォルトは True。

    • irange: list - 検索する単位胞並進の範囲 [ix, iy, iz]。デフォルトは [1, 1, 1]。

    • **kwargs: その他のキーワード引数。

  • 戻り値: tuple - (r, x_offset, y_offset, z_offset) の形式で、最近接距離とそのときのx,y,z軸方向の単位胞オフセット。適切なオフセットが見つからなければ (None, None, None, None)。

GetNearestInterAtomicDistanceWithOffset(self, pos0, pos1, AllowZero = True, irange = [1, 1, 1], **kwargs)

  • 動作: get_nearest_interatomic_distance_with_offset() メソッドのエイリアスです。2つの単位胞座標間の最近接距離と並進オフセットを計算します。

  • 引数:

    • pos0: list or numpy.ndarray - 1点目の単位胞座標 [x, y, z]。

    • pos1: list or numpy.ndarray - 2点目の単位胞座標 [x, y, z]。

    • AllowZero: bool - True の場合、距離がゼロの点も許容します。デフォルトは True。

    • irange: list - 検索する単位胞並進の範囲 [ix, iy, iz]。デフォルトは [1, 1, 1]。

    • **kwargs: その他のキーワード引数。

  • 戻り値: tuple - (r, x_offset, y_offset, z_offset)。

get_nearest_interatomic_distance(self, pos0, pos1, AllowZero = True, irange = [1, 1, 1], **kwargs)

  • 動作: 2つの単位胞座標 pos0 と pos1 間の最近接距離を計算します。単位胞の並進を考慮し、最も近い等価位置を見つけます。

  • 引数:

    • pos0: list or numpy.ndarray - 1点目の単位胞座標 [x, y, z]。

    • pos1: list or numpy.ndarray - 2点目の単位胞座標 [x, y, z]。

    • AllowZero: bool - True の場合、距離がゼロの点も許容します。デフォルトは True。

    • irange: list - 検索する単位胞並進の範囲 [ix, iy, iz]。デフォルトは [1, 1, 1]。

    • **kwargs: その他のキーワード引数。

  • 戻り値: float - 最近接距離。

GetNearestInterAtomicDistance(self, pos0, pos1, AllowZero = True, irange = [1, 1, 1], **kwargs)

  • 動作: get_nearest_interatomic_distance() メソッドのエイリアスです。2つの単位胞座標間の最近接距離を計算します。

  • 引数:

    • pos0: list or numpy.ndarray - 1点目の単位胞座標 [x, y, z]。

    • pos1: list or numpy.ndarray - 2点目の単位胞座標 [x, y, z]。

    • AllowZero: bool - True の場合、距離がゼロの点も許容します。デフォルトは True。

    • irange: list - 検索する単位胞並進の範囲 [ix, iy, iz]。デフォルトは [1, 1, 1]。

    • **kwargs: その他のキーワード引数。

  • 戻り値: float - 最近接距離。

GetNearestInterAtomicDistances(self, pos0, pos1, CoordRMax = 10.0, AllowZero = True, irange = None)

  • 動作: 2つの単位胞座標 pos0 と pos1 間の指定された最大距離 CoordRMax 内にある全ての等価な原子間距離とそのときの単位胞オフセットをリストで取得します。

  • 引数:

    • pos0: list or numpy.ndarray - 1点目の単位胞座標 [x, y, z]。

    • pos1: list or numpy.ndarray - 2点目の単位胞座標 [x, y, z]。

    • CoordRMax: float - 検索する最大距離。デフォルトは 10.0。

    • AllowZero: bool - True の場合、距離がゼロの点も許容します。デフォルトは True。

    • irange: list - 検索する単位胞並進の範囲 [ix, iy, iz]。None の場合、CoordRMax から自動的に計算されます。

  • 戻り値: list - 辞書 {'piCell': [ix, iy, iz], 'r': distance} のリスト。

GetInterAtomicAngle(self, pos0, pos1, pos2)

  • 動作: 3つの単位胞座標 pos0, pos1, pos2 によって定義される角度（\(pos1-pos0-pos2\)）を計算します。

  • 引数:

    • pos0: list or numpy.ndarray - 角度の頂点となる単位胞座標 [x, y, z]。

    • pos1: list or numpy.ndarray - 1つ目の腕の端点となる単位胞座標 [x, y, z]。

    • pos2: list or numpy.ndarray - 2つ目の腕の端点となる単位胞座標 [x, y, z]。

  • 戻り値: float - 角度（度単位）。

原子タイプ・サイト追加/設定関連メソッド: AddAtomType(self, atomtype = None, charge = None)

  • 動作: 新しい原子タイプをリストに追加します。もし同じ名前の原子タイプが既に存在すれば、その既存のインデックスとオブジェクトを返します。

  • 引数:

    • atomtype: str - 原子タイプ名（例: 'O', 'Fe2+'）。SplitAtomName で解析されます。

    • charge: float - 原子に割り当てる電荷。atomtype から電荷を自動検出できない場合に手動で指定できます。デフォルトは None。

  • 戻り値: tuple - (index, tkAtomType_object) の形式で、追加または既存の原子タイプのインデックスとオブジェクト。

SetAtomSite(self, iatom, iatomtype = None, atomtype = None, label = None, atomname = None, m = None, ws = None, pos = [], force = None, occ = 1.0, hydrogen = None)

  • 動作: 既存の指定されたインデックス iatom の原子サイトのプロパティを設定または更新します。

  • 引数:

    • iatom: int - 設定対象の原子サイトのインデックス。

    • iatomtype: int - 原子タイプのインデックス。

    • atomtype: tkAtomType オブジェクト - 原子タイプオブジェクト。

    • label: str - 原子サイトのラベル。

    • atomname: str - 原子名。

    • m: 不明 - 現在のコードでは使用されていません。

    • ws: 不明 - 現在のコードでは使用されていません。

    • pos: list or numpy.ndarray - 単位胞座標 [x, y, z]。

    • force: list or numpy.ndarray - 力のベクトル [fx, fy, fz]。

    • occ: float - 占有率。デフォルトは 1.0。

    • hydrogen: 不明 - 現在のコードでは使用されていません。

  • 戻り値: なし

AddAtomSite(self, label = None, name = None, charge = None, m = None, ws = None, pos = None, occ = 1.0, force = None, velocity = None, hydrogen = None)

  • 動作: 新しい原子サイトを非対称単位リストに追加します。原子タイプがまだ存在しない場合は自動的に追加されます。

  • 引数:

    • label: str - 原子サイトのラベル。None の場合、原子タイプ名と連番で自動生成されます。

    • name: str - 原子名（例: 'O', 'Fe2+'）。

    • charge: float - 原子に割り当てる電荷。None の場合、name から自動検出されます。

    • m: 不明 - 現在のコードでは使用されていません。

    • ws: 不明 - 現在のコードでは使用されていません。

    • pos: list or numpy.ndarray - 単位胞座標 [x, y, z]。

    • occ: float - 占有率。デフォルトは 1.0。

    • force: list or numpy.ndarray - 力のベクトル [fx, fy, fz]。

    • velocity: list or numpy.ndarray - 速度のベクトル [vx, vy, vz]。

    • hydrogen: 不明 - 現在のコードでは使用されていません。

  • 戻り値: なし

空間群関連メソッド: DoSymmetryOperation(self, pos, i)

  • 動作: 空間群オブジェクトに問い合わせて、指定されたインデックス i の対称操作を単位胞座標 pos に適用し、変換された座標を返します。

  • 引数:

    • pos: list or numpy.ndarray - 単位胞座標 [x, y, z]。

    • i: int - 適用する対称操作のインデックス。

  • 戻り値: numpy.ndarray - 変換された単位胞座標 [x', y', z']。

nSymmetryOperation(self)

  • 動作: 現在設定されている空間群の対称操作の総数を取得します。

  • 引数: なし

  • 戻り値: int - 対称操作の数。

SymmetryOperation(self, i)

  • 動作: 指定されたインデックス i の対称操作の文字列表現（例: "x,y,z"）を取得します。

  • 引数:

    • i: int - 取得する対称操作のインデックス。

  • 戻り値: str - 対称操作の文字列。

AddSymmetry(self, sym)

  • 動作: 空間群オブジェクトに新しい対称操作を追加します。

  • 引数:

    • sym: str - 追加する対称操作の文字列（例: "x,y,z"）。

  • 戻り値: なし

SpaceGroup(self)

  • 動作: 現在の tkSpaceGroup オブジェクトを取得します。まだ初期化されていない場合は、ClearSpaceGroup() を呼び出して初期化します。

  • 引数: なし

  • 戻り値: tkSpaceGroup オブジェクト - 空間群オブジェクト。

格子系・パラメータ関連メソッド: LatticeAxis(self)

  • 動作: 現在の空間群によって決定される格子軸タイプ（例: 'cubic', 'hexagonal'など）を小文字で取得します。

  • 引数: なし

  • 戻り値: str - 格子軸タイプ名の小文字。

lattice_axis(self)

  • 動作: LatticeAxis() メソッドのエイリアスです。格子軸タイプを小文字で取得します。

  • 引数: なし

  • 戻り値: str - 格子軸タイプ名の小文字。

lattice_system(self)

  • 動作: 現在の空間群によって決定される格子系（例: 'cubic', 'monoclinic'など）を小文字で取得します。

  • 引数: なし

  • 戻り値: str - 格子系名の小文字。

LatticeSystem(self)

  • 動作: lattice_system() メソッドのエイリアスです。格子系を小文字で取得します。

  • 引数: なし

  • 戻り値: str - 格子系名の小文字。

SetLatticeSystem(self, latticesystem, SearchByLatticeParameter, tollat, tolangle)

  • 動作: 空間群オブジェクトの格子系を設定します。SearchByLatticeParameter が True の場合、格子パラメータに基づいて格子系を自動判定します。

  • 引数:

    • latticesystem: str - 設定する格子系名。

    • SearchByLatticeParameter: bool - True の場合、格子パラメータから格子系を推測します。

    • tollat: float - 格子パラメータの長さの許容誤差。

    • tolangle: float - 格子パラメータの角度の許容誤差。

  • 戻り値: なし

ReciprocalLatticeParameters(self, UseAtomicUnit = 0)

  • 動作: 逆格子パラメータ \(a^*, b^*, c^*, \alpha^*, \beta^*, \gamma^*\) を取得します。

  • 引数:

    • UseAtomicUnit: int - 1 の場合、原子単位で返します（\(a_0^{-1}\)）。デフォルトは 0。

  • 戻り値: list - 逆格子パラメータのリスト [a*, b*, c*, alpha*, beta*, gamma*]。

ReciprocalLatticeVectors(self, UseAtomicUnit = 0)

  • 動作: 逆格子ベクトル \(\mathbf{a}^*, \mathbf{b}^*, \mathbf{c}^*\) を取得します。

  • 引数:

    • UseAtomicUnit: int - 1 の場合、原子単位で返します（\(a_0^{-1}\)）。デフォルトは 0。

  • 戻り値: numpy.ndarray - 逆格子ベクトルを行ベクトルとする \(3 \times 3\) 行列。

回折計算関連メソッド: DiffractionAngle(self, wl, h, k, l)

  • 動作: 指定された波長 wl とミラー指数 \(hkl\) に対するブラッグ回折角 \(2\theta\) を計算します。面間隔 \(d_{hkl}\) と逆格子空間ベクトル \(s_B = 1/(2d_{hkl})\) も返します。

  • 引数:

    • wl: float - X線波長 (オングストローム単位)。

    • h, k, l: int - ミラー指数。

  • 戻り値: tuple - (dhkl, sB, Q2) の形式で、面間隔 (\(d_{hkl}\))、逆格子空間ベクトル (\(s_B\))、および回折角 \(2\theta\) (ラジアン単位)。回折が起こらない場合は None。

Fhkl(self, sB, h, k, l)

  • 動作: 指定された逆格子空間ベクトル \(s_B\) とミラー指数 \(hkl\) に対する結晶の構造因子 \(F_{hkl}\) を計算します。展開された原子サイトリストを使用します。 $\(F_{hkl} = \sum_j f_j(s_B) \exp(2\pi i (h x_j + k y_j + l z_j))\)\( ここで \)f_j(s_B)\( は \)j\( 番目の原子の原子散乱因子、\)x_j, y_j, z_j$ はその単位胞座標です。

  • 引数:

    • sB: float - 逆格子空間ベクトル \(s_B = 1/(2d_{hkl})\)。

    • h, k, l: int - ミラー指数。

  • 戻り値: complex - 構造因子 \(F_{hkl}\)。

体積・座標変換関連メソッド: SetVolume(self, vol)

  • 動作: 単位胞の体積を直接設定します。

  • 引数:

    • vol: float - 設定する体積。

  • 戻り値: なし

Volume(self, UseAtomicUnit = 0)

  • 動作: 単位胞の体積を取得します。

  • 引数:

    • UseAtomicUnit: int - 1 の場合、原子単位で返します（\(a_0^3\)）。デフォルトは 0。

  • 戻り値: float - 単位胞の体積。

ReciprocalVolume(self, UseAtomicUnit = 0)

  • 動作: 逆格子単位胞の体積を取得します。

  • 引数:

    • UseAtomicUnit: int - 1 の場合、原子単位で返します（\(a_0^{-3}\)）。デフォルトは 0。

  • 戻り値: float - 逆格子単位胞の体積。

CalculateVolume(self)

  • 動作: 現在設定されている格子パラメータ \(a,b,c,\alpha,\beta,\gamma\) から単位胞の体積を計算し、設定します。 $\(\text{Volume} = abc \sqrt{1 - \cos^2\alpha - \cos^2\beta - \cos^2\gamma + 2 \cos\alpha \cos\beta \cos\gamma}\)$

  • 引数: なし

  • 戻り値: float - 計算された単位胞の体積。

CalculateReciprocalVolume(self)

  • 動作: 現在設定されている逆格子パラメータから逆格子単位胞の体積を計算し、設定します。

  • 引数: なし

  • 戻り値: float - 計算された逆格子単位胞の体積。

fractional2cartesian(self, x, y, z)

  • 動作: 単位胞座標 [x, y, z] をデカルト座標 [xc, yc, zc] に変換します。変換には格子ベクトル \(a_{ij}\) が使用されます。

  • 引数:

    • x, y, z: float - 単位胞座標。

  • 戻り値: list - デカルト座標 [xc, yc, zc]。

FractionalToCartesian(self, x, y, z)

  • 動作: fractional2cartesian() メソッドのエイリアスです。単位胞座標をデカルト座標に変換します。

  • 引数:

    • x, y, z: float - 単位胞座標。

  • 戻り値: list - デカルト座標 [xc, yc, zc]。

CartesianToFractional(self, xc, yc, zc)

  • 動作: デカルト座標 [xc, yc, zc] を単位胞座標 [x, y, z] に変換します。

  • 引数:

    • xc, yc, zc: float - デカルト座標。

  • 戻り値: numpy.ndarray - 単位胞座標 [x, y, z]。

CalculateHKLInterplanarSpacing(self, h, k, l)

  • 動作: ミラー指数 \(hkl\) を持つ結晶面間の面間隔 \(d_{hkl}\) を計算します。逆格子計量テンソル \(g^{ij}\) を用います。 $\(d_{hkl} = \frac{1}{\sqrt{g^{00}h^2 + g^{11}k^2 + g^{22}l^2 + 2g^{01}hk + 2g^{12}kl + 2g^{02}lh}}\)$

  • 引数:

    • h, k, l: int - ミラー指数。

  • 戻り値: float - 面間隔（オングストローム単位）、または None (計算不能な場合)。

空間群・対称化関連メソッド: SetSpaceGroup(self, name = None, number = None, set = 1)

  • 動作: 空間群オブジェクトの空間群を設定します。名前、番号、またはその両方を使用して設定できます。

  • 引数:

    • name: str - 空間群の名称（例: "P 1"）。

    • number: int - 空間群番号。

    • set: int - 空間群のセット番号（特定の空間群には複数の設定がある場合があります）。デフォルトは 1。

  • 戻り値: なし

GetSpaceGroupInf(self)

  • 動作: 現在設定されている空間群の名称、番号、およびセット番号を取得します。

  • 引数: なし

  • 戻り値: tuple - (name, number, set) の形式で空間群情報。

GetLatticeRange(self, Rmax)

  • 動作: 指定された最大距離 Rmax を考慮し、格子並進の範囲 [nx, ny, nz] を計算します。

  • 引数:

    • Rmax: float - 考慮する最大距離。

  • 戻り値: tuple - (nx_max, ny_max, nz_max) の形式で、各軸の最大並進数。

RoundSymmetricPosition(self, x, tol = 0.0001)

  • 動作: 座標値 \(x\) を、結晶学で頻出する対称性の高い小数値（例: \(1/3, 2/3, 1/6\) など）に丸めます。

  • 引数:

    • x: float - 丸める座標値。

    • tol: float - 丸め処理の許容誤差。デフォルトは 0.0001。

  • 戻り値: float - 丸められた座標値。

SymmetrizeParameter(self, ls, pos, tol)

  • 動作: 指定された格子系 ls に基づいて、位置 pos を対称化して丸めます。例えば、立方晶系では \(x, y, z\) 座標が等しくなります。

  • 引数:

    • ls: str - 格子系名（例: 'cubic', 'hexagonal'）。

    • pos: list or numpy.ndarray - 対称化する単位胞座標 [x, y, z]。

    • tol: float - 丸め処理の許容誤差。

  • 戻り値: list - 対称化された単位胞座標。

Symmetrize(self, tollatt = 1e-5, tolangle = 1e-5, tolpos = 1e-5)

  • 動作: 格子パラメータの角度を90度や120度などに丸め、現在の格子系に基づいて格子パラメータ自体も対称化します（例: 立方晶なら \(a=b=c\)）。

  • 引数:

    • tollatt: float - 格子長さの丸め許容誤差。デフォルトは 1.0e-5。

    • tolangle: float - 格子角度の丸め許容誤差。デフォルトは 1.0e-5。

    • tolpos: float - 位置の丸め許容誤差。デフォルトは 1.0e-5。

  • 戻り値: なし

格子ベクトル・計量テンソル計算関連メソッド: calculate_lattice_parameters_from_vector(self, aij = None)

  • 動作: 格子ベクトル \(a_{ij}\) から格子パラメータ \(a, b, c, \alpha, \beta, \gamma\) を計算します。

  • 引数:

    • aij: numpy.ndarray - 格子ベクトルを行とする \(3 \times 3\) 行列。None の場合、オブジェクトに格納されている self.__aij が使用されます。デフォルトは None。

  • 戻り値: numpy.ndarray - 格子パラメータの配列 [a, b, c, alpha, beta, gamma]。

CalculateLatticeParametersFromVector(self, aij = None)

  • 動作: calculate_lattice_parameters_from_vector() メソッドのエイリアスです。格子ベクトルから格子パラメータを計算します。

  • 引数:

    • aij: numpy.ndarray - 格子ベクトルを行とする \(3 \times 3\) 行列。デフォルトは None。

  • 戻り値: numpy.ndarray - 格子パラメータの配列。

Metrics(self)

  • 動作: 実空間の計量テンソル \(g_{ij}\) と逆空間の計量テンソル \(g^{ij}\) を取得します。これらのテンソルは、実空間および逆空間での距離や角度の計算に使用されます。

  • 引数: なし

  • 戻り値: tuple - (gij_matrix, Rgij_matrix) の形式で、実空間および逆空間の計量テンソルをそれぞれ表す \(3 \times 3\) numpy.ndarray。

CalcLatticeVectorsFromLatticeParameters(self, latt = None)

  • 動作: 格子パラメータ [a, b, c, alpha, beta, gamma] から格子ベクトル \(a_{ij}\) を計算し、設定します。この計算は、\(\mathbf{a}\) をx軸上、\( \mathbf{b}\) をxy平面上、\(\mathbf{c}\) をxyz空間に配置する標準的な設定に基づいて行われます。 $\( A = \begin{pmatrix} a & 0 & 0 \\ b \cos\gamma & b \sin\gamma & 0 \\ c \cos\beta & c \frac{\cos\alpha - \cos\beta \cos\gamma}{\sin\gamma} & c \sqrt{1 - \cos^2\beta - \left(\frac{\cos\alpha - \cos\beta \cos\gamma}{\sin\gamma}\right)^2} \end{pmatrix} \)\( ただし、コードの実装では \)c_y$ 成分が c * (cosb - cosb * cosg) / sing となっています。

  • 引数:

    • latt: list or numpy.ndarray - 格子パラメータのリスト [a, b, c, alpha, beta, gamma]。None の場合、オブジェクトに格納されている self.__Latt が使用されます。デフォルトは None。

  • 戻り値: numpy.ndarray - 格子ベクトルを行ベクトルとする \(3 \times 3\) 行列。

CalcMetrics(self, update_aij = True)

  • 動作: 現在設定されている格子パラメータから、実空間の計量テンソル \(g_{ij}\)、単位胞の体積、逆空間の計量テンソル \(g^{ij}\)、逆格子パラメータ、逆格子ベクトルを計算し、オブジェクトに格納します。

  • 引数:

    • update_aij: bool - True の場合、格子ベクトル self.__aij も再計算して更新します。デフォルトは True。

  • 戻り値: なし

CalMetricsFromLatticeVector(self)

  • 動作: 現在設定されている格子ベクトル self.__aij から実空間の計量テンソル \(g_{ij}\) を計算し、設定します。

  • 引数: なし

  • 戻り値: numpy.ndarray - 計算された実空間の計量テンソル \(g_{ij}\)。

SetLatticeParameters(self, latt, GuessLatticeSystem = 0, update_aij = True)

  • 動作: 格子パラメータ \(a, b, c, \alpha, \beta, \gamma\) を設定し、同時に空間群の格子系と格子軸タイプも更新し、計量テンソルや逆格子関連の値を再計算します。

  • 引数:

    • latt: list or numpy.ndarray - 設定する格子パラメータのリスト [a, b, c, alpha, beta, gamma]。

    • GuessLatticeSystem: int - 1 の場合、格子パラメータから格子系を推測し設定します。デフォルトは 0。

    • update_aij: bool - True の場合、格子ベクトルも再計算して更新します。デフォルトは True。

  • 戻り値: なし

lattice_parameters(self, UseAtomicUnit = 0)

  • 動作: 現在設定されている格子パラメータ \(a, b, c, \alpha, \beta, \gamma\) を取得します。

  • 引数:

    • UseAtomicUnit: int - 1 の場合、格子長さを原子単位 (\(a_0\)) で返します。デフォルトは 0。

  • 戻り値: list - 格子パラメータのリスト [a, b, c, alpha, beta, gamma]。

LatticeParameters(self, UseAtomicUnit = 0)

  • 動作: lattice_parameters() メソッドのエイリアスです。格子パラメータを取得します。

  • 引数:

    • UseAtomicUnit: int - 1 の場合、格子長さを原子単位 (\(a_0\)) で返します。デフォルトは 0。

  • 戻り値: list - 格子パラメータのリスト。

CalLatticeParametersFromMetrics(self, update_aij = False)

  • 動作: 現在設定されている計量テンソル \(g_{ij}\) から、格子パラメータ \(a, b, c, \alpha, \beta, \gamma\) を計算し、設定します。

  • 引数:

    • update_aij: bool - True の場合、格子ベクトル self.__aij も再計算して更新します。デフォルトは False。

  • 戻り値: なし

set_lattice_vectors(self, aij)

  • 動作: 格子ベクトル \(a_{ij}\) を設定します。同時に、計量テンソルや格子パラメータも自動的に再計算されます。

  • 引数:

    • aij: numpy.ndarray - 格子ベクトルを行ベクトルとする \(3 \times 3\) 行列。

  • 戻り値: なし

SetLatticeVectors(self, aij)

  • 動作: set_lattice_vectors() メソッドのエイリアスです。格子ベクトルを設定します。

  • 引数:

    • aij: numpy.ndarray - 格子ベクトルを行ベクトルとする \(3 \times 3\) 行列。

  • 戻り値: なし

lattice_vectors(self, UseAtomicUnit = 0)

  • 動作: 現在設定されている格子ベクトル \(a_{ij}\) を取得します。

  • 引数:

    • UseAtomicUnit: int - 1 の場合、格子ベクトルを原子単位 (\(a_0\)) で返します。デフォルトは 0。

  • 戻り値: numpy.ndarray - 格子ベクトルを行ベクトルとする \(3 \times 3\) 行列。

LatticeVectors(self, UseAtomicUnit = 0)

  • 動作: lattice_vectors() メソッドのエイリアスです。格子ベクトルを取得します。

  • 引数:

    • UseAtomicUnit: int - 1 の場合、格子ベクトルを原子単位 (\(a_0\)) で返します。デフォルトは 0。

  • 戻り値: numpy.ndarray - 格子ベクトルを行ベクトルとする \(3 \times 3\) 行列。

その他ユーティリティメソッド: count_by_type(self, atype, mode = 'short', target = 'expanded')

  • 動作: 指定された原子タイプ atype の原子サイトの数をカウントします。target で展開済みサイトか非対称サイトかを選択でき、mode で原子名の照合方法を選択できます。

  • 引数:

    • atype: str - 検索する原子タイプ（大文字小文字は区別されません）。

    • mode: str - short (原子シンボルのみで比較), full (完全な原子タイプ名で比較)。デフォルトは short。

    • target: str - expanded (展開済みサイト), asymmetric (非対称サイト)。デフォルトは expanded。

  • 戻り値: int - カウントされた原子サイトの数。

normalize_hkl(self, h, k, l)

  • 動作: 指定された \(hkl\) インデックスを結晶系の対称性に基づいて正規化します。これにより、対称的に等価な面を表現する際に一貫した形式が得られます。

  • 引数:

    • h, k, l: int - ミラー指数。

  • 戻り値: tuple - 正規化されたミラー指数 (h', k', l')。

multiplicity_cubic(self, h, k,l)

  • 動作: 立方晶系における \(hkl\) インデックスの多重度を計算します。

  • 引数:

    • h, k, l: int - ミラー指数。

  • 戻り値: int - 多重度。

multiplicity_tetragonal(self, h, k, l)

  • 動作: 正方晶系における \(hkl\) インデックスの多重度を計算します。

  • 引数:

    • h, k, l: int - ミラー指数。

  • 戻り値: int - 多重度。

multiplicity_orthorhombic(self, h, k, l)

  • 動作: 斜方晶系における \(hkl\) インデックスの多重度を計算します。

  • 引数:

    • h, k, l: int - ミラー指数。

  • 戻り値: int - 多重度。

multiplicity_rhombohedral(self, h, k, l)

  • 動作: 菱面体晶系における \(hkl\) インデックスの多重度を計算します。

  • 引数:

    • h, k, l: int - ミラー指数。

  • 戻り値: int - 多重度。

multiplicity_trigonal(self, h, k, l)

  • 動作: 三方晶系における \(hkl\) インデックスの多重度を計算します（multiplicity_hexagonal を呼び出します）。

  • 引数:

    • h, k, l: int - ミラー指数。

  • 戻り値: int - 多重度。

multiplicity_hexagonal(self, h, k, l)

  • 動作: 六方晶系における \(hkl\) インデックスの多重度を計算します。

  • 引数:

    • h, k, l: int - ミラー指数。

  • 戻り値: int - 多重度、または None (不正な入力の場合)。

multiplicity_hkl(self, h, k, l)

  • 動作: 現在の格子系に基づいて、指定された \(hkl\) インデックスの多重度を計算します。

  • 引数:

    • h, k, l: int - ミラー指数。

  • 戻り値: int - 多重度、または None (未サポートの格子系の場合)。

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

このライブラリ tkcrystalobject.py は、if __name__ == "__main__": ブロックを含んでいません。 したがって、このファイルを直接Pythonインタプリタで実行しても、特別な処理は行われません。 通常、tkcrystalobject.py は他のPythonプログラムから tkCrystalObject クラスをインポートし、その機能を利用することを想定して設計されています。