tkatomsiteobject.py ライブラリ技術ドキュメント

ライブラリの機能や目的

tkatomsiteobject.py は、結晶学や材料科学における「原子サイト（atom site）」の情報を管理するためのPythonライブラリです。このライブラリは、単一の原子サイトに関連する多岐にわたる属性（原子タイプ、位置、電荷、占有率、力、速度、ラベル、IDなど）を一元的にカプセル化し、オブジェクト指向的な方法で操作する機能を提供します。

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

• 原子サイト情報のカプセル化: 原子名、位置座標（分数座標）、電荷、サイト占有率、多重度、力、速度といった原子サイトの基本的な属性を一つのオブジェクトとして管理します。

• 座標の正規化: 結晶学で一般的に使用される分数座標を、周期性を考慮して\(0.0\)から\(1.0\)の範囲に丸める（正規化する）機能を提供します。

• 原子名解析: 原子名文字列（例: 'C1', 'O_anion', 'Fe2+') から、その要素名、タイプ、電荷などの詳細情報を抽出する機能を提供します。

• tklib.tkobject.tkObject の継承: より汎用的なオブジェクト機能を提供する tkObject を継承しており、基本的なオブジェクト管理機能（例: クラスパスの取得）も利用可能です。

• データの一貫性: 設定されていない属性に対してデフォルト値や解析値を提供することで、データの一貫性を保ちます。

このライブラリは、結晶構造データ（CIFファイルなど）の読み込み、処理、操作を行うアプリケーションの基盤となる原子サイト表現として利用されることを想定しています。

importする方法

tkatomsiteobject.py ライブラリを他のPythonプログラムから利用するには、以下の方法でインポートできます。

• ライブラリ全体をインポートする場合：

  import tkatomsiteobject
  

• 特定のクラスや関数を直接インポートする場合：

  from tkatomsiteobject import tkAtomSiteObject, RoundParameter, Round01
  

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

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

• tklib パッケージ:

  • tklib.tkobject.tkObject (ベースクラス)

  • tklib.tkre (未使用だがインポートされている)

  • tklib.tksci.tksci (Reduce01, Round 関数を提供)

  • tklib.tkcrystal.tkatomtypeobject (SplitAtomName, Charge2f 関数を提供)

tklib は、このライブラリが属するプロジェクト内部で使用されるカスタムライブラリである可能性が高いです。そのため、PyPIのような標準的なパッケージリポジトリでは公開されていないかもしれません。

インストール方法: tklib がPyPIで公開されていない場合、pip コマンドでの直接インストールはできません。このライブラリを使用するには、tklib パッケージのソースコードを入手し、tkatomsiteobject.py を使用するプロジェクトのPythonパスが通っているディレクトリ（例: 同じプロジェクトのルートディレクトリや site-packages 内）に配置する必要があります。

もし tklib が利用可能な状態であれば、特別なインストール手順は不要です。

importできる変数と関数

tkatomsiteobject.py からインポートできる主な関数とクラスは以下の通りです。

関数

RoundParameter(x, tol)

• 動作: 浮動小数点数 x を、指定された許容誤差 tol の最も近い倍数に丸めます。この関数は、特定の精度で数値を量子化するために使用されます。丸めは、tol * int( (x + 0.1 * tol) / tol ) という式に基づいて行われます。

• 引数:

  • x (float): 丸めたい数値。

  • tol (float): 丸めの単位となる許容誤差。

• 戻り値: (float) 丸められた結果の数値。

Round01(x)

• 動作: 浮動小数点数 x を\(0.0\)から\(1.0\)の範囲に正規化または丸めます。特に、\(1.0\)に近い値や\(0.0\)に近い値をそれぞれ正確に\(1.0\)または\(0.0\)に調整します（許容誤差 0.0002 を使用）。それ以外の場合、\(x\)の小数部分を返しますが、負の値の場合は\(1.0\)を加算して\(0.0\)から\(1.0\)の範囲に収めます。

• 引数:

  • x (float): 処理対象の数値。

• 戻り値: (float) \(0.0\)から\(1.0\)の範囲に正規化または丸められた数値。

クラス

tkAtomSiteObject

tkatomsiteobject.py ライブラリの中心となるクラスで、一つの原子サイトの全情報を管理します。tklib.tkobject.tkObject を継承しています。

メソッド一覧

__init__(self, atomtype=None, label=None, name='', charge=None, pos=[], force=None, velocity=None, occ=1.0, m=1, ws=None, hydrogen=None, **args)

• 動作: tkAtomSiteObject の新しいインスタンスを初期化します。原子サイトの様々な属性（原子タイプ、ラベル、原子名、電荷、位置、力、速度、占有率、多重度、ワイコフ位置、水素原子フラグ）を設定します。内部で SetAtomSite メソッドを呼び出して実際の属性設定を行います。

• 引数:

  • atomtype (object, optional): 原子タイプを表すオブジェクト。デフォルトは None。

  • label (str, optional): 原子サイトのラベル。デフォルトは None。

  • name (str, optional): 原子サイトの識別名（例: 'C1', 'O_anion'）。デフォルトは空文字列 ''。

  • charge (float/int/str, optional): 原子サイトの電荷。デフォルトは None。

  • pos (list, optional): 原子サイトの分数座標 [x, y, z]。デフォルトは空リスト []。

  • force (list, optional): 原子サイトにかかる力 [fx, fy, fz]。デフォルトは None。

  • velocity (list, optional): 原子サイトの速度 [vx, vy, vz]。デフォルトは None。

  • occ (float, optional): サイト占有率。デフォルトは 1.0。

  • m (int, optional): サイトの多重度。デフォルトは 1。

  • ws (object, optional): ワイコフ位置を表すオブジェクト。デフォルトは None。

  • hydrogen (bool, optional): このサイトが水素原子であるかを示すフラグ。デフォルトは None。

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

• 戻り値: (None)

__str__(self)

• 動作: オブジェクトの文字列表現を返します。親クラス tkObject の ClassPath() メソッドの結果を利用します。

• 引数: (None)

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

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

• 動作: tkAtomSiteObject インスタンスの複数の属性を一度に設定します。各引数に対応する Set メソッドを内部で呼び出します。

• 引数: __init__ と同様。iatomtype が追加されています。

• 戻り値: (None)

SetLabel(self, Label)

• 動作: 原子サイトのラベルを設定します。Label が None の場合、原子名がラベルとして使用されます。

• 引数: Label (str): 設定するラベル文字列。

• 戻り値: (None)

Label(self)

• 動作: 原子サイトのラベルを返します。

• 引数: (None)

• 戻り値: (str) 原子サイトのラベル。

SetAtomName(self, AtomName)

• 動作: 原子サイトの原子名を設定します。

• 引数: AtomName (str): 設定する原子名。

• 戻り値: (None)

atom_name_only(self, del_par=0)

• 動作: 設定されている原子名から、要素名またはタイプ名を解析して返します。内部で SplitAtomName 関数を使用します。

• 引数:

  • del_par (int, optional): 結果の形式を制御します。0 の場合、SplitAtomName から得られる nametype を返します。1 の場合、name を返します。

• 戻り値: (str) 解析された原子の要素名またはタイプ名。

AtomNameOnly(self, DelPar=0)

• 動作: atom_name_only のエイリアス。

• 引数: DelPar (int, optional): del_par と同じ。

• 戻り値: (str) atom_name_only の結果。

atom_name(self)

• 動作: 原子サイトの現在の原子名を返します。

• 引数: (None)

• 戻り値: (str) 原子サイトの原子名。

AtomName(self)

• 動作: atom_name のエイリアス。

• 引数: (None)

• 戻り値: (str) 原子サイトの原子名。

SetCharge(self, charge=None)

• 動作: 原子サイトの電荷を設定します。charge が None の場合、既存の原子名から電荷を解析して設定を試みます。

• 引数: charge (float/int/str, optional): 設定する電荷の値。デフォルトは None。

• 戻り値: (None)

Charge(self)

• 動作: 原子サイトの電荷を浮動小数点数で返します。電荷がまだ設定されていない場合、原子名から解析して設定し、Charge2f で変換した結果を返します。

• 引数: (None)

• 戻り値: (float) 原子サイトの電荷。設定されていない場合は 0.0 を返します。

SetOccupancy(self, occ=1.0)

• 動作: 原子サイトの占有率を設定します。

• 引数: occ (float, optional): サイト占有率。デフォルトは 1.0。

• 戻り値: (None)

Occupancy(self)

• 動作: 原子サイトの占有率を返します。

• 引数: (None)

• 戻り値: (float) 原子サイトの占有率。

SetPosition(self, pos)

• 動作: 原子サイトの分数座標を設定します。

• 引数: pos (list): [x, y, z] 形式の分数座標。

• 戻り値: (None)

position(self, is_reduce01=0)

• 動作: 原子サイトの分数座標を返します。is_reduce01 が 1 の場合、各座標成分は Round01 および Reduce01 関数を使って\(0.0\)から\(1.0\)の範囲に正規化されます。

• 引数:

  • is_reduce01 (int, optional): 座標を\(0.0-1.0\)範囲に正規化するかどうかのフラグ。0 (False) の場合、元の座標が返されます。1 (True) の場合、正規化されます。

• 戻り値: (list) 原子サイトの分数座標 [x, y, z]。

Position(self, IsReduce01=0)

• 動作: position のエイリアス。

• 引数: IsReduce01 (int, optional): is_reduce01 と同じ。

• 戻り値: (list) position の結果。

SetForce(self, force)

• 動作: 原子サイトにかかる力を設定します。

• 引数: force (list): [fx, fy, fz] 形式の力ベクトル。

• 戻り値: (None)

Force(self)

• 動作: 原子サイトにかかる力を返します。力が設定されていない場合は [None, None, None] を返します。

• 引数: (None)

• 戻り値: (list) 力ベクトル [fx, fy, fz]。

SetMultiplicity(self, mult)

• 動作: 原子サイトの多重度を設定します。

• 引数: mult (int): 多重度。

• 戻り値: (None)

Multiplicity(self)

• 動作: 原子サイトの多重度を返します。

• 引数: (None)

• 戻り値: (int) 原子サイトの多重度。

SetVelocity(self, v)

• 動作: 原子サイトの速度を設定します。

• 引数: v (list): [vx, vy, vz] 形式の速度ベクトル。

• 戻り値: (None)

Velocity(self)

• 動作: 原子サイトの速度を返します。速度が設定されていない場合は [None, None, None] を返します。

• 引数: (None)

• 戻り値: (list) 速度ベクトル [vx, vy, vz]。

WycoffPosition(self)

• 動作: 原子サイトのワイコフ位置情報を返します。

• 引数: (None)

• 戻り値: (object) ワイコフ位置を表すオブジェクト。

SetWycoffPosition(self, ws)

• 動作: 原子サイトのワイコフ位置情報を設定します。

• 引数: ws (object): 設定するワイコフ位置オブジェクト。

• 戻り値: (None)

Hydrogen(self)

• 動作: 原子サイトが水素原子であるかを示すフラグを返します。

• 引数: (None)

• 戻り値: (bool) 水素原子の場合は True、そうでなければ False または None。

SetHydrogen(self, h)

• 動作: 原子サイトが水素原子であるかを示すフラグを設定します。

• 引数: h (bool): 設定する水素原子フラグ。

• 戻り値: (None)

SetiAtomType(self, i)

• 動作: 原子タイプに関連付けられたインデックスまたはIDを設定します。

• 引数: i (int): 原子タイプのインデックス。

• 戻り値: (None)

iAtomType(self)

• 動作: 原子タイプに関連付けられたインデックスまたはIDを返します。

• 引数: (None)

• 戻り値: (int) 原子タイプのインデックス。

SetAtomType(self, at)

• 動作: 原子タイプオブジェクトを設定します。

• 引数: at (object): 設定する原子タイプオブジェクト。

• 戻り値: (None)

AtomType(self)

• 動作: 原子タイプオブジェクトを返します。

• 引数: (None)

• 戻り値: (object) 原子タイプオブジェクト。

SetId(self, id)

• 動作: 原子サイトのIDを設定します。内部で SetIdAsymmetricAtomSite を呼び出します。

• 引数: id (int): 設定するID。

• 戻り値: (None)

SetIdAsymmetricAtomSite(self, i)

• 動作: 非対称単位内の原子サイトIDを設定します。__idSite と __IdAsymmetricAtomSite の両方を更新します。

• 引数: i (int): 非対称単位内の原子サイトID。

• 戻り値: (None)

SetIdSite(self, i)

• 動作: 原子サイトのIDを設定します。

• 引数: i (int): 設定するサイトID。

• 戻り値: (None)

IdSite(self)

• 動作: 原子サイトのIDを返します。

• 引数: (None)

• 戻り値: (int) サイトID。

IdAsymmetricAtomSite(self)

• 動作: 非対称単位内の原子サイトIDを返します。

• 引数: (None)

• 戻り値: (int) 非対称単位内の原子サイトID。

Id(self)

• 動作: IdAsymmetricAtomSite のエイリアスとして、非対称単位内の原子サイトIDを返します。

• 引数: (None)

• 戻り値: (int) 非対称単位内の原子サイトID。

SetIsSelected(self, IsSelected)

• 動作: 原子サイトが選択されているかどうかのフラグを設定します。

• 引数: IsSelected (int): 選択状態を示すフラグ（通常は 0 または 1）。

• 戻り値: (None)

IsSelected(self)

• 動作: 原子サイトが選択されているかどうかのフラグを返します。

• 引数: (None)

• 戻り値: (int) 選択状態を示すフラグ。

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

tkatomsiteobject.py のソースコードには、if __name__ == "__main__": ブロックが含まれていません。したがって、このライブラリを main script として直接実行した場合でも、特定の出力や処理は行われません。

このライブラリは、他のPythonプログラムやスクリプトからインポートされ、その中に定義されているクラス (tkAtomSiteObject) や関数 (RoundParameter, Round01) が利用されることを想定して設計されています。