"""
原子サイトオブジェクトを管理するモジュール。
このモジュールは、結晶構造内の原子サイトを表す `tkAtomSiteObject` クラスを提供します。
原子のタイプ、位置、電荷、占有率などの詳細な情報をカプセル化し、
それらの属性を設定・取得するためのインターフェースを提供します。
原子サイトは、結晶構造モデリングやシミュレーションにおいて基本的な構成要素となります。
関連リンク:
:doc:`tkatomsiteobject_usage`
"""
from tklib.tkobject import tkObject
import tklib.tkre as tkre
from tklib.tksci.tksci import Reduce01, Round
#from tkcrystal.tkcrystalobject import tkCrystalObject
from tklib.tkcrystal.tkatomtypeobject import SplitAtomName, Charge2f
[ドキュメント]
def RoundParameter(x, tol):
"""
数値を指定された許容誤差の倍数に丸めます。
概要:
数値を指定された許容誤差の倍数に丸めます。
詳細説明:
この関数は、入力値 `x` を `tol` の倍数に丸めます。
内部的には `(x + 0.1 * tol) / tol` を整数に変換し、再度 `tol` を乗算することで丸め処理を行います。
この丸めは、一般的な四捨五入とは異なる振る舞いをする可能性があります。
:param x: float: 丸める対象の数値。
:param tol: float: 丸めの基準となる許容誤差（単位）。
:returns: float: 丸められた数値。
"""
val = tol * int( (x+0.1*tol) / tol )
return val
[ドキュメント]
def Round01(x):
"""
数値を0.0から1.0の範囲に丸めます。
概要:
数値を0.0から1.0の範囲に丸め、特に1.0や0.0に近い値を正確に扱います。
詳細説明:
入力値 `x` が1.0または0.0に非常に近い場合、それぞれ1.0または0.0を返します。
それ以外の場合、`x` の小数部分を返します。
`x` が1.0より大きい場合は `x - int(x)`、1.0より小さいが0.0より大きい場合は `x - int(x) + 1.0` を計算し、
結果が常に0.0から1.0の範囲に収まるようにします。
:param x: float: 丸める対象の数値。
:returns: float: 0.0から1.0の範囲に丸められた数値。
"""
if abs(x - 1.0) < 0.0002:
return 1.0
if abs(x) < 0.0002:
return 0.0
if x > 1.0:
return x - int(x)
if x < 1.0:
return x - int(x) + 1.0
return x
#class tkAtomSiteObject(tkCrystalObject):
[ドキュメント]
class tkAtomSiteObject(tkObject):
"""
結晶構造における原子サイトの情報を保持するクラス。
概要:
結晶構造における単一の原子サイト（原子の位置とその属性）を表すオブジェクトです。
詳細説明:
このクラスは、原子のタイプ、ラベル、名前、電荷、座標、力、速度、占有率、多重度、
Wyckoff位置、水素原子の有無などの情報をカプセル化します。
これらの属性を設定・取得するためのメソッドを提供し、原子サイトの管理を容易にします。
`tklib.tkobject.tkObject` を継承しています。
"""
def __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のコンストラクタ。
概要:
新しい原子サイトオブジェクトを初期化します。
詳細説明:
原子の各種属性（タイプ、ラベル、名前、電荷、位置など）を指定してオブジェクトを生成します。
初期化時に設定されなかった属性は、デフォルト値が使用されるか、Noneに設定されます。
:param atomtype: object, optional: 原子タイプオブジェクト。
:param label: str, optional: 原子サイトのラベル。Noneの場合、nameが使用されます。
:param name: str, optional: 原子サイトの名前（例: 'C1', 'O2-')。デフォルトは空文字列。
:param charge: float or None, optional: 原子サイトの電荷。デフォルトはNone。
:param pos: list of float, optional: 原子サイトの分数座標（[x, y, z]）。デフォルトは空リスト。
:param force: list of float or None, optional: 原子サイトにかかる力（[fx, fy, fz]）。デフォルトはNone。
:param velocity: list of float or None, optional: 原子サイトの速度（[vx, vy, vz]）。デフォルトはNone。
:param occ: float, optional: 原子サイトの占有率。デフォルトは1.0。
:param m: int, optional: 原子サイトの多重度。デフォルトは1。
:param ws: str or None, optional: Wyckoff位置の記号。デフォルトはNone。
:param hydrogen: bool or None, optional: 水素原子であるかを示すフラグ。デフォルトはNone。
:param args: dict: その他のキーワード引数。
"""
self.__IsSelected = 1
self.__Id = 0
self.__AtomType = None
self.__iAtomType = None
self.SetAtomSite(atomtype, label, name, charge, pos, force, velocity, occ, m, ws, hydrogen)
def __del__(self):
"""
オブジェクトのデストラクタ。
概要:
オブジェクトが破棄される際に呼び出されます。
詳細説明:
現在の実装では何もしません。
"""
pass
def __str__(self):
"""
オブジェクトの文字列表現を返します。
概要:
オブジェクトのクラスパスを文字列表現として返します。
:returns: str: オブジェクトのクラスパス。
"""
return self.ClassPath()
def __del__(self):
"""
オブジェクトのデストラクタ。
概要:
オブジェクトが破棄される際に呼び出されます。
詳細説明:
現在の実装では何もしません。（重複定義）
"""
pass
def __str__(self):
"""
オブジェクトの文字列表現を返します。
概要:
オブジェクトのクラスパスを文字列表現として返します。
:returns: str: オブジェクトのクラスパス。（重複定義）
"""
return self.ClassPath()
[ドキュメント]
def 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):
"""
原子サイトの全てのプロパティを一括で設定します。
概要:
原子サイトのタイプ、ラベル、名前、電荷、位置、力、速度、占有率、多重度、Wyckoff位置、水素原子フラグを更新します。
詳細説明:
このメソッドは、指定された引数に基づいて原子サイトの各属性を更新します。
引数がNoneの場合、その属性は変更されません（ただし、一部のSetメソッド内でデフォルト値が適用される場合があります）。
`label`がNoneの場合、`name`の値が`label`として設定されます。
:param atomtype: object or None, optional: 原子タイプオブジェクト。
:param iatomtype: int or None, optional: 内部原子タイプID。
:param label: str or None, optional: 原子サイトのラベル。
:param name: str or None, optional: 原子サイトの名前。
:param charge: float or None, optional: 原子サイトの電荷。
:param pos: list of float or None, optional: 原子サイトの分数座標。
:param force: list of float or None, optional: 原子サイトにかかる力。
:param velocity: list of float or None, optional: 原子サイトの速度。
:param occ: float, optional: 原子サイトの占有率。デフォルトは1.0。
:param m: int or None, optional: 原子サイトの多重度。
:param ws: str or None, optional: Wyckoff位置の記号。
:param hydrogen: bool or None, optional: 水素原子であるかを示すフラグ。
"""
if atomtype is not None:
self.SetAtomType(atomtype)
if iatomtype is not None:
self.SetiAtomType(iatomtype)
if label is None:
label = name
self.SetLabel(label)
self.SetAtomName(name)
self.SetCharge(charge)
self.SetPosition(pos)
self.SetForce(force)
self.SetVelocity(velocity)
self.SetOccupancy(occ)
self.SetMultiplicity(m)
self.SetWycoffPosition(ws)
self.SetHydrogen(hydrogen)
[ドキュメント]
def SetLabel(self, Label):
"""
原子サイトのラベルを設定します。
概要:
原子サイトの表示用ラベルを設定します。
詳細説明:
`Label`がNoneの場合、内部で保持されている原子名 (`self.AtomName`) がラベルとして設定されます。
それ以外の場合は、指定された`Label`がそのまま設定されます。
:param Label: str or None: 設定するラベル。
"""
if Label is None:
self.__Label = self.AtomName
else:
self.__Label = Label
[ドキュメント]
def Label(self):
"""
原子サイトのラベルを取得します。
概要:
現在設定されている原子サイトのラベルを返します。
:returns: str: 原子サイトのラベル。
"""
return self.__Label
[ドキュメント]
def SetAtomName(self, AtomName):
"""
原子サイトの名称を設定します。
概要:
原子サイトの名称（例: 'C1', 'O2-'）を設定します。
:param AtomName: str: 設定する原子サイトの名称。
"""
self.__AtomName = AtomName
[ドキュメント]
def atom_name_only(self, del_par = 0):
"""
原子サイトの名称から修飾子を除いた部分を取得します。
概要:
原子名からサイトタイプや電荷などの付加情報を取り除いた純粋な原子名またはタイプ名を返します。
詳細説明:
内部で `SplitAtomName` 関数を使用して原子名を解析します。
`del_par` が0（デフォルト）の場合、原子のタイプ名（例: 'C', 'O'）を返します。
`del_par` が0以外の場合、原子の基本名称（例: 'C', 'O'）を返します。
:param del_par: int, optional: 0の場合タイプ名を、0以外の場合基本名称を返すフラグ。デフォルトは0。
:returns: str: 修飾子を除いた原子名またはタイプ名。
"""
name, nametype, sitetype, charge = SplitAtomName(self.__AtomName)
# name, nametype, sitetype, charge = self.SplitAtomName(self.__AtomName)
if del_par:
return name
return nametype
[ドキュメント]
def AtomNameOnly(self, DelPar = 0):
"""
原子サイトの名称から修飾子を除いた部分を取得します。(大文字エイリアス)
概要:
`atom_name_only` メソッドの大文字エイリアスです。原子名からサイトタイプや電荷などの付加情報を取り除いた部分を返します。
:param DelPar: int, optional: 0の場合タイプ名を、0以外の場合基本名称を返すフラグ。デフォルトは0。
:returns: str: 修飾子を除いた原子名またはタイプ名。
"""
return self.atom_name_only(del_par = DelPar)
[ドキュメント]
def atom_name(self):
"""
原子サイトの名称を取得します。
概要:
現在設定されている原子サイトの名称を返します。
:returns: str: 原子サイトの名称。
"""
return self.__AtomName
[ドキュメント]
def AtomName(self):
"""
原子サイトの名称を取得します。(大文字エイリアス)
概要:
`atom_name` メソッドの大文字エイリアスです。現在設定されている原子サイトの名称を返します。
:returns: str: 原子サイトの名称。
"""
return self.__AtomName
[ドキュメント]
def SetCharge(self, charge = None):
"""
原子サイトの電荷を設定します。
概要:
原子サイトの電荷を設定します。
詳細説明:
`charge` がNoneでない場合、その値をfloat型に変換して設定を試みます。
`charge` がNoneの場合、`SplitAtomName` 関数を使用して現在の原子名から電荷を抽出し、設定します。
原子名から電荷が抽出できない場合は、電荷はNoneのままです。
:param charge: float or None, optional: 設定する電荷。デフォルトはNone。
"""
if charge is not None:
try:
self.__Charge = float(charge)
except:
pass
else:
name, nametype, sitetype, charge = SplitAtomName(self.__AtomName)
# name, nametype, sitetype, charge = self.SplitAtomName(self.__AtomName)
self.__Charge = charge
[ドキュメント]
def Charge(self):
"""
原子サイトの電荷を取得します。
概要:
現在設定されている原子サイトの電荷を返します。
詳細説明:
電荷が既に設定されている場合、`Charge2f` 関数を適用して返します。
電荷が設定されていない場合（Noneの場合）、`SplitAtomName` 関数を使用して現在の原子名から電荷を抽出し、
抽出できればそれを設定し、`Charge2f` を適用して返します。
電荷が抽出できない場合、デフォルトで0.0を返します。
:returns: float: 原子サイトの電荷。
"""
if self.__Charge is not None:
return Charge2f(self.__Charge)
name, nametype, sitetype, charge = SplitAtomName(self.__AtomName)
# name, nametype, sitetype, charge = self.SplitAtomName(self.__AtomName)
if charge is None:
return 0.0
self.__Charge = charge
return Charge2f(self.__Charge)
[ドキュメント]
def SetOccupancy(self, occ = 1.0):
"""
原子サイトの占有率を設定します。
概要:
原子サイトの占有率を設定します。
:param occ: float, optional: 設定する占有率。デフォルトは1.0。
"""
self.__Occupancy = occ
[ドキュメント]
def Occupancy(self):
"""
原子サイトの占有率を取得します。
概要:
現在設定されている原子サイトの占有率を返します。
:returns: float: 原子サイトの占有率。
"""
return self.__Occupancy
[ドキュメント]
def SetPosition(self, pos):
"""
原子サイトの座標を設定します。
概要:
原子サイトの分数座標（[x, y, z]）を設定します。
:param pos: list of float: 設定する座標リスト。
"""
self.__Pos = pos
[ドキュメント]
def position(self, is_reduce01 = 0):
"""
原子サイトの座標を取得します。
概要:
現在設定されている原子サイトの座標を返します。
詳細説明:
`is_reduce01` が0以外の場合、座標値を0.0から1.0の範囲に丸めて返します。
具体的には `Round01` と `Reduce01` 関数が適用されます。
`is_reduce01` が0の場合、生の値の座標リストをそのまま返します。
:param is_reduce01: int, optional: 0以外の場合、座標を0-1の範囲に丸めるフラグ。デフォルトは0。
:returns: list of float: 原子サイトの座標リスト。
"""
if is_reduce01:
x = Round01(self.__Pos[0])
y = Round01(self.__Pos[1])
z = Round01(self.__Pos[2])
return [Reduce01(x), Reduce01(y), Reduce01(z)]
return self.__Pos
[ドキュメント]
def Position(self, IsReduce01 = 0):
"""
原子サイトの座標を取得します。(大文字エイリアス)
概要:
`position` メソッドの大文字エイリアスです。現在設定されている原子サイトの座標を返します。
:param IsReduce01: int, optional: 0以外の場合、座標を0-1の範囲に丸めるフラグ。デフォルトは0。
:returns: list of float: 原子サイトの座標リスト。
"""
return self.position(is_reduce01 = IsReduce01)
[ドキュメント]
def SetForce(self, force):
"""
原子サイトにかかる力を設定します。
概要:
原子サイトにかかる力（[fx, fy, fz]）を設定します。
:param force: list of float or None: 設定する力のリスト。
"""
self.__Force = force
[ドキュメント]
def Force(self):
"""
原子サイトにかかる力を取得します。
概要:
現在設定されている原子サイトにかかる力を返します。
詳細説明:
力が設定されていない場合（Noneの場合）、[None, None, None]を返します。
:returns: list of float or list of None: 原子サイトにかかる力のリスト。
"""
if self.__Force is None:
return [None, None, None]
return self.__Force
[ドキュメント]
def SetMultiplicity(self, mult):
"""
原子サイトの多重度を設定します。
概要:
原子サイトの多重度を設定します。
:param mult: int or None: 設定する多重度。
"""
self.__Multiplicity = mult
[ドキュメント]
def Multiplicity(self):
"""
原子サイトの多重度を取得します。
概要:
現在設定されている原子サイトの多重度を返します。
:returns: int or None: 原子サイトの多重度。
"""
return self.__Multiplicity
[ドキュメント]
def SetVelocity(self, v):
"""
原子サイトの速度を設定します。
概要:
原子サイトの速度（[vx, vy, vz]）を設定します。
:param v: list of float or None: 設定する速度のリスト。
"""
self.__Velocity = v
[ドキュメント]
def Velocity(self):
"""
原子サイトの速度を取得します。
概要:
現在設定されている原子サイトの速度を返します。
詳細説明:
速度が設定されていない場合（Noneの場合）、[None, None, None]を返します。
:returns: list of float or list of None: 原子サイトの速度のリスト。
"""
if self.__Velocity is None:
return [None, None, None]
return self.__Velocity
[ドキュメント]
def WycoffPosition(self):
"""
原子サイトのWyckoff位置記号を取得します。
概要:
現在設定されている原子サイトのWyckoff位置記号を返します。
:returns: str or None: Wyckoff位置記号。
"""
return self.__WycoffPosition
[ドキュメント]
def SetWycoffPosition(self, ws):
"""
原子サイトのWyckoff位置記号を設定します。
概要:
原子サイトのWyckoff位置記号を設定します。
:param ws: str or None: 設定するWyckoff位置記号。
"""
self.__WycoffPosition = ws
[ドキュメント]
def Hydrogen(self):
"""
原子サイトが水素原子であるかを取得します。
概要:
原子サイトが水素原子であるかを示すフラグを返します。
:returns: bool or None: 水素原子であるかを示すブール値。
"""
return self.__Hydrogen
[ドキュメント]
def SetHydrogen(self, h):
"""
原子サイトが水素原子であるかを設定します。
概要:
原子サイトが水素原子であるかを示すフラグを設定します。
:param h: bool or None: 設定する水素原子フラグ。
"""
self.__Hydrogen = h
[ドキュメント]
def SetiAtomType(self, i):
"""
原子サイトの内部原子タイプIDを設定します。
概要:
原子サイトの内部原子タイプIDを設定します。
:param i: int or None: 設定する内部原子タイプID。
"""
self.__iAtomType = i
[ドキュメント]
def iAtomType(self):
"""
原子サイトの内部原子タイプIDを取得します。
概要:
現在設定されている原子サイトの内部原子タイプIDを返します。
:returns: int or None: 内部原子タイプID。
"""
return self.__iAtomType
[ドキュメント]
def SetAtomType(self, at):
"""
原子サイトに関連付けられた原子タイプオブジェクトを設定します。
概要:
原子サイトに関連付けられた原子タイプオブジェクトを設定します。
:param at: object or None: 設定する原子タイプオブジェクト。
"""
self.__AtomType = at
[ドキュメント]
def AtomType(self):
"""
原子サイトに関連付けられた原子タイプオブジェクトを取得します。
概要:
現在設定されている原子サイトに関連付けられた原子タイプオブジェクトを返します。
:returns: object or None: 原子タイプオブジェクト。
"""
return self.__AtomType
[ドキュメント]
def SetId(self, id):
"""
原子サイトのIDを設定します。
概要:
原子サイトのIDを設定します。このメソッドは `SetIdAsymmetricAtomSite` を呼び出します。
:param id: int: 設定するID。
"""
self.SetIdAsymmetricAtomSite(id)
[ドキュメント]
def SetIdAsymmetricAtomSite(self, i):
"""
非対称原子サイトのIDを設定します。
概要:
非対称原子サイトのIDを設定します。このIDは `__idSite` と `__IdAsymmetricAtomSite` の両方に設定されます。
:param i: int: 設定するID。
"""
self.__idSite = i
self.__IdAsymmetricAtomSite = i
[ドキュメント]
def SetIdSite(self, i):
"""
サイトIDを設定します。
概要:
原子サイトのサイトIDを設定します。
:param i: int: 設定するサイトID。
"""
self.__idSite = i
[ドキュメント]
def IdSite(self):
"""
サイトIDを取得します。
概要:
現在設定されている原子サイトのサイトIDを返します。
:returns: int: サイトID。
"""
return self.__idSite
[ドキュメント]
def IdAsymmetricAtomSite(self):
"""
非対称原子サイトのIDを取得します。
概要:
現在設定されている非対称原子サイトのIDを返します。
:returns: int: 非対称原子サイトのID。
"""
return self.__IdAsymmetricAtomSite
[ドキュメント]
def Id(self):
"""
原子サイトのIDを取得します。
概要:
原子サイトのID (`__IdAsymmetricAtomSite` の値) を返します。
:returns: int: 原子サイトのID。
"""
return self.__IdAsymmetricAtomSite
[ドキュメント]
def SetIsSelected(self, IsSelected):
"""
原子サイトの選択状態を設定します。
概要:
原子サイトの選択状態を示すフラグを設定します。
:param IsSelected: int: 選択状態（0または1）。
"""
self.__IsSelected = IsSelected
[ドキュメント]
def IsSelected(self):
"""
原子サイトの選択状態を取得します。
概要:
原子サイトが選択されているかを示すフラグを返します。
:returns: int: 選択状態（0または1）。
"""
return self.__IsSelected