tkrietan.py Technical Documentation

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

tkrietan.py ライブラリは、粉末X線回折データ解析ソフトウェアであるRIETANに関連する科学計算機能とデータ処理機能を提供します。主に以下の目的と機能を持っています。

原子散乱因子 (Atomic Scattering Factor, ASF) の計算: X線および電子線に対する原子散乱因子を計算する機能を提供します。これは、回折パターンシミュレーションや構造精密化において不可欠な要素です。
ASFパラメータの読み込み: 特定の原子やX線源に対応する原子散乱因子のパラメータを外部データベースファイル (ASFDC) から読み込むことができます。
RIETAN関連パスの管理: RIETANプログラムおよび関連するデータベースファイルへのパスを管理します。
既存データフォーマットの読み込み（Perlコードに記述された機能の一部）: ソースコード中にPythonの3重引用符で囲まれたPerlコードの断片として、IGOR Pattern File、RietPlot File、gnuplot File、TOPAS Text File、RINT2000 ASCII Fileなど、様々な回折データファイル形式を読み込む機能の存在が示唆されています。ただし、これらの機能はPythonコードとしては実装されていません。

このライブラリは、特に結晶学、材料科学分野の研究者がX線回折データや電子線回折データを扱う際に、基礎となる物理量の計算やRIETANとの連携のためのユーティリティとして利用されることを想定しています。

importする方法

tkrietan.py ライブラリは、Pythonの標準的な import 文を使用して、他のPythonプログラムからインポートできます。

import tkrietan

または、特定のクラスや関数のみをインポートすることも可能です。

from tkrietan import tkRietan

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

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

numpy: 数値計算を行うための基本的なライブラリです。
tklib: このライブラリが依存するカスタムライブラリです。tkobject, tkcrystal, tkprogvars, tkfile, tkinifile, tksci, tkutils, tkre などのサブモジュールを使用しています。この tklib は標準のPyPIには存在しないため、別途提供される必要があります。

numpy のインストールは pip コマンドで簡単に行えます。

pip install numpy

tklib は、このライブラリと同じプロジェクトの一部として提供されるカスタムライブラリであるため、通常は tkrietan.py と同じ環境（例えば、同じプロジェクトディレクトリ内やPythonのサイトパッケージパス上）に配置することで利用可能になります。

importできる変数と関数

グローバル変数

以下のパス情報は、tkrietan.py がインポートされた際にモジュールレベルで定義されます。

RietanProgramPath: RIETANプログラムのルートディレクトリへのパス。
```
RietanProgramPath = os.path.join(RietanDir, "RIETAN_VENUS")
```
RietanPath: RIETAN実行ファイル (RIETAN64.exe など) へのフルパス。
```
RietanPath  = os.path.join(RietanProgramPath, "RIETAN64.exe")
```

SPGDBPath: 空間群データベース (SPGRA など) へのパス。

SPGDBPath   = os.path.join(RietanDir, "RIETAN_VENUS", "SPGRA")

SPGRDBPath: 空間群情報データベース (spgr.daf など) へのパス。
```
SPGRDBPath  = os.path.join(RietanDir, "RIETAN_VENUS", "spgr.daf")
```
ASFDCPath: 原子散乱因子データベース (asfdc など) へのパス。
```
ASFDCPath   = os.path.join(RietanDir, "RIETAN_VENUS", "asfdc")
```

クラス `tkRietan`

tkRietan クラスは tkCrystalObject を継承しており、結晶構造オブジェクトとしての基本的な機能に加えて、RIETANに関連する特定の機能を提供します。

`tkRietan` のメソッド

__init__(self, **args)
- 動作: tkRietan オブジェクトを初期化します。SPGDBPath と ASFDCPath をインスタンス変数として設定し、tkObject クラスから継承される update メソッドを呼び出します。
- 引数:
  - **args: キーワード引数として、親クラス tkObject の update メソッドに渡される任意のパラメータ。
- 戻り値: なし。
__del__(self)
- 動作: デストラクタ。現在は特に何も行いません。
- 引数: なし。
- 戻り値: なし。
__str__(self)
- 動作: オブジェクトの文字列表現を返します。親クラス tkObject の ClassPath() メソッドの結果を返します。
- 引数: なし。
- 戻り値: str - オブジェクトのクラスパスを示す文字列。
ReadASFParameters(self, AtomName, dbpath=ASFDCPath, XraySource='Cu', StopByError=1)
- 動作: 指定された原子名とX線源に基づいて、原子散乱因子分散補正 (ASFDC) データベースからパラメータを読み込みます。
  - データベースファイル (dbpath) をオープンし、AtomName に一致するエントリを検索します。
  - 該当する原子の原子番号 ($Z$)、質量、電荷、および散乱因子係数を抽出します。
  - XraySource (Cr, Fe, Co, Cu, Mo, Ag, Kb など) に応じて、適切な分散補正項を選択的に適用します。
  - 読み込んだパラメータは self.asfdc に辞書形式で保存され、その辞書が返されます。
- 引数:
  - AtomName: str - 検索する原子名（例: "Fe", "O"）。
  - dbpath: str, オプション - ASFDCデータベースファイルのパス。デフォルトはグローバル変数 ASFDCPath。
  - XraySource: str, オプション - 使用するX線源の種類（例: "Cu", "Fe", "Mo"）。デフォルトは 'Cu'。
  - StopByError: int, オプション - エラー発生時にプログラムを終了するかどうか (1: 終了, 0: 続行)。デフォルトは 1。
- 戻り値: dict - 読み込まれたASFDCパラメータを含む辞書。エラーが発生した場合は 0 を返す（StopByError=0 の場合）。
asf(self, s, StopByError=1)
- 動作: X線に対する原子散乱因子 $f(s)$ を計算します。ASFDCパラメータ ($A_i, B_i, C$) を使用し、以下の数式に基づきます。 $$f(s) = C + \sum_{i=1}^{5} A_i \exp(-B_i s^2)$$ ここで、$s = \sin \theta / \lambda$ (単位は $nm^{-1}$)。分散補正項（$P_{12}, P_{13}$）が存在する場合は、複素数として返されます。
- 引数:
  - s: float - $\sin \theta / \lambda$ の値 (単位: $nm^{-1}$)。
  - StopByError: int, オプション - エラー発生時にプログラムを終了するかどうか。デフォルトは 1。
- 戻り値: float または complex - 計算された原子散乱因子。
asfElectron(self, s, StopByError=1)
- 動作: 電子線に対する原子散乱因子 $f_e(s)$ を計算します。以下の数式に基づきます。 $$f_e(s) = \frac{k}{s^2}(Z - f_X(s))$$ ここで、$k = 1.0 \times 10^{-2} \cdot \frac{8 \pi^2}{a_0 \cdot 1.0 \times 10^9}$、$Z$ は原子番号、$f_X(s)$ はX線原子散乱因子 (`self.asf` で計算)。$a_0$ はボーア半径。
- 引数:
  - s: float - $\sin \theta / \lambda$ の値 (単位: $nm^{-1}$)。$s \le 0.0$ の場合は $1.0 \times 10^{-5}$ に設定されます。
  - StopByError: int, オプション - エラー発生時にプログラムを終了するかどうか。デフォルトは 1。
- 戻り値: float または complex - 計算された電子線原子散乱因子。
HydrogenAtomicScatteringFactor(self, s)
- 動作: 水素原子の原子散乱因子を計算します。以下の数式に基づきます。 $$f(s) = \frac{1}{(1 + k s^2)^2}$$ ここで、$k = 4 \pi^2 a_0^2 \cdot 1.0 \times 10^{18}$、$a_0$ はボーア半径。
- 引数:
  - s: float - $\sin \theta / \lambda$ の値 (単位: $nm^{-1}$)。
- 戻り値: float - 計算された水素原子の原子散乱因子。

注意: ソースコード中には、Pythonの3重引用符で囲まれたPerlコードの断片が多数含まれています (ReadHermannMauguin, Execute, SaveInsFile などの関数定義や変数設定)。これらはPythonの実行には影響せず、この tkrietan.py ライブラリのPythonコードの一部としては機能しません。これらのPerlコードは、過去のバージョンや別の言語による実装例として残されている可能性があります。上記の「importできる変数と関数」のリストは、純粋にPythonで実装されている部分のみを対象としています。

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

tkrietan.py には、if __name__ == "__main__": ブロックが存在しません。したがって、このスクリプトを直接実行しても、特定の処理は行われず、何も出力されません。 tkrietan.py は、他のPythonプログラムからインポートされて利用されることを目的とした純粋なライブラリとして設計されています。