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

このドキュメントは、Python言語で記述された tkatomtype.py ライブラリの技術的な詳細について説明します。

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

tkatomtype.py ライブラリは、主にX線回折や結晶学の分野で利用される原子に関する様々な情報を取り扱うための機能を提供します。原子の物理的特性（質量、電荷、原子半径など）、原子散乱因子（ASF: Atomic Scattering Factor）、異常散乱因子（ASF: Anomalous Scattering Factor）、イオン半径などのデータベースとの連携と計算を目的としています。

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

原子基本情報の読み込み: 元素周期表データ (PERIODIC.CSV) から原子の基本情報を読み込みます。
イオン半径データの読み込み: Shannonのイオン半径データ (Shannon_Ionic_Radii.txt) を読み込み、特定のイオンの半径情報を取得します。
原子散乱因子パラメータの読み込みと計算: ASFDC (Atomic Scattering Factor Data Collection) ファイル (asfdc) から原子散乱因子を計算するためのパラメータを読み込み、指定された $s = \sin\theta / \lambda$ 値に対応する原子散乱因子を計算します。
異常散乱因子データの読み込みと補間: 特定の原子に対する異常散乱因子データを読み込み、指定されたX線波長に対応する $f_1, f_2$ を補間計算により取得します。
原子タイプオブジェクト: tkAtomType クラスを通じて、特定の原子タイプに関連する情報を一元的に管理し、上記のような計算やデータ取得を容易にします。

このライブラリは、結晶構造解析ソフトウェアやシミュレーションツールの一部として、原子の物理的・散乱特性を扱う場面で利用されることを想定しています。

importする方法

このライブラリは、Pythonプログラム内で以下の方法でインポートできます。

import tkatomtype

または、特定の変数や関数を直接インポートすることも可能です。

from tkatomtype import tkAtomType, read_atom_inf_csv

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

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

numpy: 数値計算を効率的に行うためのライブラリです。
scipy: 科学技術計算ライブラリで、特にここでは scipy.interpolate.interp1d を使用しています。

これらのライブラリは、pip コマンドを使用してインストールできます。

pip install numpy scipy

また、tkatomtype.py は、内部ライブラリである tklib に依存しています。tklib は pip で公開されている一般的なライブラリではないため、この tkatomtype.py を利用する際には、tklib パッケージがPythonのパス上に適切に配置されている必要があります。

importできる変数と関数

グローバル変数

tkatomtype.py から直接インポートできるグローバル変数とその説明です。

ASFDCPath: 原子散乱因子のデータファイル asfdc への絶対パスを格納します。
ScantteringDir: 原子散乱因子データが格納されているディレクトリ atom_scattering/data への絶対パスを格納します。
atom_inf_db_path: 元素周期表データが格納されているCSVファイル PERIODIC.CSV への絶対パスを格納します。
shannon_ir_db_path: Shannonのイオン半径データが格納されているテキストファイル Shannon_Ionic_Radii.txt への絶対パスを格納します。

関数

tkatomtype.py からインポートできる主な関数とその説明です。

`read_atom_inf_csv(file_path=None)`

指定されたCSVファイルから原子の基本情報を読み込みます。デフォルトでは atom_inf_db_path のファイルを使用します。

動作: PERIODIC.CSV 形式のファイルを読み込み、各行を辞書として格納したリストを返します。各辞書には "Symbol" などのキーが含まれます。シンボルは unicodedata.normalize('NFKC', ...) で正規化されます。
引数:
- file_path (str, オプション): 読み込むCSVファイルのパス。省略された場合は atom_inf_db_path が使用されます。
戻り値:
- list of dict: 読み込まれた原子情報のリスト。
- None: ファイルが見つからない、またはその他のエラーが発生した場合。

`read_shannon_ionic_radii(file_path=None)`

Shannonのイオン半径データベースファイルからデータを読み込みます。デフォルトでは shannon_ir_db_path のファイルを使用します。

動作: Shannon_Ionic_Radii.txt 形式のファイルを読み込み、各レコードを辞書として格納したリストを返します。ファイルのヘッダー行（"Record #"で始まる行）の次からデータを読み込みます。イオン名は原子名と電荷に分割されます。
引数:
- file_path (str, オプション): 読み込むテキストファイルのパス。省略された場合は shannon_ir_db_path が使用されます。
戻り値:
- list of dict: 読み込まれたイオン半径データのリスト。各辞書には "Record#", "atom_name", "charge", "Oxidation State", "Electronic Configuration", "Coordination Number", "Spin State", "Crystal Radius", "Ionic Radius", "NOTES", "Charge to Ionic Radius Ratio" などのキーが含まれます。
- None: ファイルが見つからない、またはヘッダー行が見つからない場合。

`read_SX1_potential(dbpath)`

SX1ポテンシャルデータを読み込みます。

動作: 指定されたパスのファイルを読み込み、各行のデータを辞書として格納します。最初の列が要素名（キー）として使用されます。
引数:
- dbpath (str): 読み込むデータベースファイルのパス。
戻り値:
- dict: 要素名をキーとする辞書で、各要素の値は 'mass', 'charge', 'ai', 'bi', 'ci', 'ratom' を含む辞書です。

クラス

`tkAtomType`

tkAtomTypeObject を継承し、特定の原子タイプに関する情報と計算機能を提供するクラスです。

継承: tklib.tkcrystal.tkatomtypeobject.tkAtomTypeObject
__init__(self, atomtype=None, charge=0.0, **args): tkAtomType オブジェクトを初期化します。
- 引数:
  - atomtype (str, オプション): 原子タイプ名（例: "Si", "O"）。
  - charge (float, オプション): 原子の電荷。デフォルトは 0.0。
  - **args: 親クラス tkAtomTypeObject のコンストラクタに渡される追加のキーワード引数。
- 戻り値: なし
__del__(self): デストラクタです。親クラスのデストラクタを呼び出します。
- 引数: なし
- 戻り値: なし
__str__(self): オブジェクトの文字列表現を返します。
- 引数: なし
- 戻り値: str: オブジェクトのクラスパス。
ASFDCParameters(self): 読み込まれた原子散乱因子パラメータを返します。
- 引数: なし
- 戻り値: list または None: 原子散乱因子パラメータのリスト。
ASFDCAtomName(self): 原子散乱因子パラメータが読み込まれた際の原子名を返します。
- 引数: なし
- 戻り値: str または None: 原子名。
ReadASFParameters(self, AtomName=None, asfdcfile=ASFDCPath, XraySource=None, StopByError=1): ASFDCファイルから原子散乱因子パラメータを読み込みます。
- 動作: 指定された AtomName (またはオブジェクト自身の AtomType) に対応する原子散乱因子パラメータを asfdcfile から検索して読み込みます。XraySource が指定された場合、異常散乱因子 $f_1, f_2$ もパラメータに追加されることがあります。
- 引数:
  - AtomName (str, オプション): パラメータを読み込む原子の名前。省略された場合は、オブジェクト自身の原子タイプが使用されます。
  - asfdcfile (str, オプション): ASFDCファイルのパス。デフォルトは ASFDCPath。
  - XraySource (str or float, オプション): X線源の種類（例: "Cr", "Cu", "Mo" など）またはX線波長（float）。これに基づいて異常散乱因子がパラメータに追加されます。
  - StopByError (int, オプション): エラー発生時にプログラムを終了するかどうか（1で終了、0で継続）。デフォルトは 1。
- 戻り値:
  - list: 原子散乱因子パラメータのリスト。
  - None: ファイル読み込みエラーや原子名が見つからない場合。
asf(self, s, StopByError=1): 指定された $s$ 値における原子散乱因子 $f(s)$ を計算します。
- 動作: 原子散乱因子は、以下の形式の近似式で計算されます。 $$f(s) = C + \sum_{i=1}^{5} A_i \exp(-B_i s_0^2)$$ ここで、$s_0 = 0.01 \cdot s^2$ であり、$s$ は $nm^{-1}$ (またはこれに準ずる単位) で与えられ、$s_0$ は $Å^{-2}$ の単位に変換されます。もし異常散乱因子 $f_1, f_2$ が読み込まれていれば、それらも考慮して複素数として返されます。
- 引数:
  - s (float): $\sin\theta / \lambda$ の値。単位は通常 $nm^{-1}$ ですが、計算内部で $Å^{-2}$ に変換されます。
  - StopByError (int, オプション): エラー発生時にプログラムを終了するかどうか（1で終了、0で継続）。デフォルトは 1。
- 戻り値:
  - float または complex: 計算された原子散乱因子。
ReadAnomalousScatteringFactor(self, AtomName=None): 原子の異常散乱因子データを読み込みます。
- 動作: 指定された AtomName (またはオブジェクト自身の AtomType) に対応する異常散乱因子データファイル ([AtomName].dat) を ScantteringDir から読み込みます。データはエネルギー xE (eV)、波長 xwl (nm)、実部 yf1、虚部 yf2 として格納されます。
- 引数:
  - AtomName (str, オプション): データを読み込む原子の名前。省略された場合は、オブジェクト自身の原子タイプが使用されます。
- 戻り値:
  - tuple: (xE, xwl, yf1, yf2, dbpath) の形式で、それぞれエネルギー、波長、$f_1$、 $f_2$、データファイルのパスです。
AnomalousScatteringFactor(self, wl): 指定された波長における異常散乱因子 $f_1$ と $f_2$ を補間計算します。
- 動作: 事前に ReadAnomalousScatteringFactor で読み込まれたデータ（または必要に応じて読み込み）を基に、指定された波長 wl (nm) に対して線形補間を行い、$f_1$ と $f_2$ の値を計算します。
- 引数:
  - wl (float): 異常散乱因子を計算したい波長 (nm)。
- 戻り値:
  - tuple: (f1, f2) の形式で、それぞれ異常散乱因子の実部と虚部。

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

tkatomtype.py には if __name__ == '__main__': ブロックが存在しないため、このスクリプトを直接実行した場合でも、特別な処理は行われません。ライブラリとして他のプログラムからインポートして利用することを前提としています。

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