tkspacegroup.py 技術ドキュメント
ライブラリの機能や目的
tkspacegroup.py は、結晶学における空間群（Space Group）に関する情報を管理、解析、および利用するためのPythonライブラリです。主な目的は以下の通りです。
空間群情報の管理: 空間群名、空間群番号、セット番号、ラウエ群、格子システム、格子軸、対称操作といった結晶学的データをオブジェクト指向的に管理します。
データベース連携: RIETANなどの結晶構造解析ソフトウェアが利用する空間群データベース（
spgr.dafなど）から、空間群の詳細情報を読み込む機能を提供します。対称操作の適用: 原子位置や速度ベクトルに、定義された空間群の対称操作を適用し、等価な位置や方向を計算する機能を提供します。
格子情報の解析: 格子定数に基づいて格子システムや格子軸のタイプを自動的に解析する機能を提供します。
結晶学的計算のサポート: 空間群に基づいてブラベー格子を推測するなどの結晶学的計算をサポートします。
このライブラリは、結晶構造モデルの構築、シミュレーション、データ解析など、空間群の厳密な取り扱いが要求される場面で利用されることを想定しています。
importする方法
このライブラリの主要なクラスである tkSpaceGroup を他のPythonプログラムからインポートするには、以下の方法を使用します。
from tklib.tkcrystal.tkspacegroup import tkSpaceGroup
または、モジュール全体をインポートして、モジュール名を通じてクラスにアクセスすることも可能です。
import tklib.tkcrystal.tkspacegroup as tkspacegroup
# その後、tkspacegroup.tkSpaceGroup() のように使用
必要な非標準ライブラリとインストール方法
tkspacegroup.py が正しく機能するためには、以下の非標準ライブラリが必要です。
numpy
数値計算を効率的に行うためのライブラリです。
インストール方法:
pip install numpy
tklib
このライブラリは
tklibというカスタムライブラリに依存しています。tkprogvars,tkfile,tksci,tkutils,tkre,tkspacegroupobjectなど、tklib内部の様々なモジュールを使用しています。tklibは通常、pipで直接インストールできるものではなく、このtkspacegroup.pyが動作する環境にtklibパッケージが適切に配置されている必要があります。tklibの具体的なインストール方法については、このドキュメントの範囲外となりますが、このライブラリを使用するためにはtklibが利用可能な状態になっていることが前提となります。
importできる変数と関数
グローバル変数
tkspacegroup.py モジュールから直接アクセス可能なグローバル変数は以下の通りです。これらは主に、関連するデータベースファイルや実行可能ファイルのパスを定義しています。
RietanProgramPath: RIETAN_VENUSプログラムのベースパス。例:
C:\RIETAN_VENUS
RietanPath: RIETAN64.exe実行ファイルのフルパス。例:
C:\RIETAN_VENUS\RIETAN64.exe
SPGDBPath: 空間群データベースファイルspgraのパス。SPGRDBPath: 空間群データベースファイルSpgr.dafのパス。ASFDCPath:asfdcファイルのパス。AtomsDBDir: 原子データベースディレクトリのパス。
クラス
class tkSpaceGroup(tkSpaceGroupObject)
結晶学における空間群情報を扱うメインクラスです。tklib.tkcrystal.tkspacegroupobject.tkSpaceGroupObject を継承しています。
コンストラクタと特殊メソッド
__init__(self, **args)tkSpaceGroupオブジェクトを初期化します。内部で空間群名、空間群番号、格子定数などを管理するための変数を設定します。
継承元の
tkSpaceGroupObjectの初期化も行います。argsで初期値を渡すことができます。
__del__(self)オブジェクトが削除される際に呼び出されるデストラクタです。
継承元のデストラクタを呼び出します。
__str__(self)オブジェクトの文字列表現を返します。
このクラスのパス（例:
tklib.tkcrystal.tkspacegroup.tkSpaceGroup）を返します。
メソッド
SetP1(self)空間群を三斜晶系の空間群番号1 (P 1) に設定します。
すべての既存の対称操作をクリアし、単一の対称操作 'x,y,z' を追加します。
格子システムを 'triclinic' に設定します。
SetSPGName(self, SPGName)空間群名を設定します。入力された文字列から引用符が削除されます。
引数:
SPGName(str): 設定する空間群名。
SPGName(self)現在設定されている空間群名を取得します。
戻り値: (str) 空間群名。
SetiSPG(self, iSPG)空間群番号を設定します。入力値は整数に変換されます。
引数:
iSPG(int, str): 設定する空間群番号。
iSPG(self)現在設定されている空間群番号を取得します。
戻り値: (int) 空間群番号。
SetiSet(self, iSet = 1)空間群のセット番号を設定します。入力値は整数に変換されます。
引数:
iSet(int, str): 設定するセット番号。デフォルトは1。
iSet(self)現在設定されている空間群のセット番号を取得します。
戻り値: (int) セット番号。
SetSpaceGroup(self, SPGName, iSPG, iSet = 1)空間群名、空間群番号、セット番号を一括で設定します。
引数:
SPGName(str): 設定する空間群名。iSPG(int, str): 設定する空間群番号。iSet(int, str): 設定するセット番号。デフォルトは1。
iLaueG(self)現在設定されているラウエ群のインデックスを取得します。
戻り値: (int) ラウエ群のインデックス。
LaueGroupByRietanIndex(self, idx = None)RIETANデータベースで使用されるインデックスに基づいて、対応するラウエ群の名称を返します。
引数:
idx(int, optional): ラウエ群のインデックス (1-15)。Noneまたは範囲外の場合、空文字列を返します。
戻り値: (str) ラウエ群の名称（例: "Cubic (m3m)"）。
LatticeSystemFromLaueGroup(self, LaueG)ラウエ群の名称から、対応する格子システムの名称を推測して返します。
引数:
LaueG(str): ラウエ群の名称。
戻り値: (str) 格子システムの名称（例: 'triclinic', 'rhombohedral'）。
ReadSpaceGroupFromSPGName(self, SPGName)空間群名に基づいて空間群データベースから情報を読み込みます。
内部で
GetiSPGFromSPGNameを呼び出して空間群番号とセット番号を取得し、ReadSpaceGroupを呼び出します。引数:
SPGName(str): 検索する空間群名。
戻り値: (dict) 空間群情報を含む辞書。
ReadNextSpaceGroup(self, db)空間群データベースファイルオブジェクトから次の空間群のレコードを読み込み、その情報を辞書形式で返します。
引数:
db(tkFile): 読み取り用に開かれたtkFileオブジェクト。
戻り値: (dict or None) 空間群情報を含む辞書、またはファイルの終端やエラーで読み込みができなかった場合は
None。
ReadSpaceGroup(self, ispg, iset, SettoSelf = 0, dbpath = SPGDBPath, StopByError = 1)指定された空間群番号 (
ispg) とセット番号 (iset) に一致する空間群情報をデータベースから読み込みます。引数:
ispg(int): 空間群番号。iset(int): セット番号。SettoSelf(int):1の場合、読み込んだ情報を現在のオブジェクト自身に設定します。0の場合、新しいtkSpaceGroupオブジェクトを作成して辞書に含めて返します。デフォルトは0。dbpath(str): 空間群データベースファイルのパス。デフォルトはグローバル変数SPGDBPath。StopByError(int):1の場合、データベースの読み込みや情報の検索に失敗した際にプログラムを終了します。デフォルトは1。
戻り値: (dict or None) 空間群情報を含む辞書。
SettoSelfが0の場合、キー'SPG'にtkSpaceGroupオブジェクトが含まれます。見つからない場合やエラーの場合はNone。
GetSpaceGroupList(self, dbpath = SPGDBPath, StopByError = 1)空間群データベースから、利用可能なすべての空間群のリストを文字列形式で取得します。
引数:
dbpath(str): 空間群データベースファイルのパス。デフォルトはグローバル変数SPGDBPath。StopByError(int):1の場合、データベースの読み込みに失敗した際にプログラムを終了します。デフォルトは1。
戻り値: (list of str) 各空間群の情報を整形した文字列のリスト。
GetiSPGFromSPGName(self, spgname, dbpath = SPGDBPath, StopByError = 1)空間群名から対応する空間群番号とセット番号をデータベースから検索して取得します。
引数:
spgname(str): 検索する空間群名。dbpath(str): 空間群データベースファイルのパス。デフォルトはグローバル変数SPGDBPath。StopByError(int):1の場合、データベースの読み込みや情報の検索に失敗した際にプログラムを終了します。デフォルトは1。
戻り値: (tuple)
(count, iSPG, iSet)の形式で、データベース内の出現順序、空間群番号、セット番号を返します。見つからない場合は(-1, -1, -1)を返します。
ClearSymmetryOperation(self)オブジェクトに設定されているすべての対称操作と並進ベクトルをクリアし、基本の並進ベクトル
[0, 0, 0]のみを設定します。
DoSymmetryOperation(self, iop, pos, IsReduce01 = 1)指定された対称操作を点座標に適用します。
引数:
iop(int): 適用する対称操作のインデックス。pos(list or tuple): 変換する点座標[x, y, z]。IsReduce01(int):1の場合、変換後の座標を 0 から 1 の範囲に正規化（リデュース）します。デフォルトは1。
戻り値: (list) 変換後の点座標
[x', y', z']のリスト。
DoVelocitySymmetryOperation(self, iop, v, IsReduce01 = 0)指定された対称操作を速度ベクトルに適用します。
引数:
iop(int): 適用する対称操作のインデックス。v(list or tuple): 変換する速度ベクトル[vx, vy, vz]。IsReduce01(int): このメソッドでは常に0として扱われるため、速度ベクトルは 0-1 の範囲に正規化されません。
戻り値: (list) 変換後の速度ベクトル
[vx', vy', vz']のリスト。
nSymmetryOperation(self)現在設定されている対称操作の総数を返します。
戻り値: (int) 対称操作の数。
nTranslation(self)現在設定されている並進ベクトルの総数を返します。
戻り値: (int) 並進ベクトルの数。
TranslationVector(self, i)指定されたインデックスの並進ベクトルを取得します。
引数:
i(int): 並進ベクトルのインデックス。
戻り値: (list) 並進ベクトル
[tx, ty, tz]のリスト。
GuessBravaisLattice(self, tollatt, tolangle, EPSCoord)現在の格子定数と空間群名からブラベー格子を推測します。
引数:
tollatt(float): 格子定数の許容誤差。tolangle(float): 角度の許容誤差。EPSCoord: 座標の許容誤差。
戻り値: (list)
[LatticeSystem, BravaisLattice]の形式で、格子システムとブラベー格子を表す文字列のリスト。
GetBravaisLattice(self)現在の空間群名と格子システムに基づいてブラベー格子を返します。
戻り値: (str) ブラベー格子を示す文字列（例: "P(Cubic)", "FC(Monoclinic)"）。
GetSymmetryOperationList(self)設定されているすべての対称操作のリストを取得します。
戻り値: (list of str) 対称操作の文字列リスト。
SymmetryOperation(self, i)指定されたインデックスの対称操作文字列を取得します。
引数:
i(int): 対称操作のインデックス。
戻り値: (str) 対称操作を表す文字列。
AddSymmetryOperation(self, symop)新しい対称操作をリストに追加します。重複は追加されません。
引数:
symop(str): 追加する対称操作を表す文字列（例: 'x,y,z'）。
戻り値: (int) 追加後の対称操作の総数。
LatticeParameters(self)現在設定されている格子定数
a, b, c, alpha, beta, gammaのリストを取得します。戻り値: (list) 格子定数
[a, b, c, alpha, beta, gamma]のリスト。
LatticeAxis(self)現在の格子定数から解析された、または明示的に設定された格子軸のタイプ（例: 'cubic', 'monoclinic'）を取得します。
戻り値: (str) 格子軸のタイプを表す文字列。
AnalyzeLatticeAxis(self, *, latticesystem = '', SearchByLatticeParameter = 0, tollatt = 1.0e-5, tolangle = 1.0e-5)現在の格子定数に基づいて格子軸のタイプを解析し、内部変数に設定します。
引数:
latticesystem(str, optional): 明示的に設定する格子システム名。SearchByLatticeParameter(int):1の場合、格子定数に基づいて解析を行います。デフォルトは0。tollatt(float): 格子定数の比較に使用する許容誤差。デフォルトは \(1.0 \times 10^{-5}\)。tolangle(float): 角度の比較に使用する許容誤差。デフォルトは \(1.0 \times 10^{-5}\)。
戻り値: (str) 解析または設定された格子軸のタイプを表す文字列。
LatticeSystem(self)現在の格子システム（例: 'triclinic', 'rhombohedral'）を取得します。
戻り値: (str) 格子システム名。
LatticeSystemFromSPGName(self, SPGName)空間群名から格子システム名を推測して返します。
引数:
SPGName(str): 空間群名。
戻り値: (str) 推測された格子システム名。
SetLatticeParameters(self, latt, GuessLatticeSystem = 0)格子定数を設定します。オプションで、格子システムと格子軸も自動的に推測して設定できます。
引数:
latt(list): 格子定数[a, b, c, alpha, beta, gamma]のリスト。GuessLatticeSystem(int):1の場合、格子システムと格子軸を自動的に推測して設定します。デフォルトは0。
SetLatticeSystem(self, *, latticesystem = '', SearchByLatticeParameter = 0, tollatt = 1.0e-5, tolangle = 1.0e-5)格子システムを設定します。明示的に指定するか、現在の空間群情報や格子定数から推測します。
引数:
latticesystem(str, optional): 明示的に設定する格子システム名。SearchByLatticeParameter(int):1の場合、格子定数に基づいて格子システムを解析します。デフォルトは0。tollatt(float): 格子定数の比較に使用する許容誤差。デフォルトは \(1.0 \times 10^{-5}\)。tolangle(float): 角度の比較に使用する許容誤差。デフォルトは \(1.0 \times 10^{-5}\)。
戻り値: (str) 設定された格子システム名。
SetLatticeAxis(self, *, latticeaxis = '', SearchByLatticeParameter = 1, tollatt = 1.0e-5, tolangle = 1.0e-5)格子軸のタイプを設定します。明示的に指定するか、格子定数から推測します。
引数:
latticeaxis(str, optional): 明示的に設定する格子軸タイプ名。SearchByLatticeParameter(int):1の場合、格子定数に基づいて格子軸を解析します。デフォルトは1。tollatt(float): 格子定数の比較に使用する許容誤差。デフォルトは \(1.0 \times 10^{-5}\)。tolangle(float): 角度の比較に使用する許容誤差。デフォルトは \(1.0 \times 10^{-5}\)。
戻り値: (str) 設定された格子軸タイプ名。
SetiLaueGroup(self, iLaueG = None)ラウエ群のインデックスを設定します。
引数:
iLaueG(int, optional): 設定するラウエ群のインデックス。Noneの場合、現在のオブジェクトの状態に基づいて設定を試みます。
main scriptとして実行したときの動作
tkspacegroup.py には if __name__ == '__main__': ブロックが存在しないため、このファイルを直接Pythonインタプリタで実行しても、特別な処理は行われません。このファイルは、他のPythonプログラムからインポートされて利用されるライブラリとしてのみ機能します。