tkatomtypeobject.py

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

tkatomtypeobject.py は、原子の型（atom type）とその関連情報（原子番号、質量、電荷など）を管理し、取得するためのユーティリティ関数とクラスを提供するPythonライブラリです。主に、原子のデータベースファイル（INI形式）から情報を読み込み、原子名や原子番号に基づいて標準化された原子情報を抽出・解析することを目的としています。

このライブラリは、以下のような課題を解決します。

様々な形式で記述された原子名（例: Sr.a[b]2+）から、基本となる原子名、サイトタイプ、電荷などの要素を正確に解析します。
原子番号と原子名の相互変換機能を提供します。
原子データベースファイルから原子の物理的・化学的特性（原子半径、質量、融点、沸点など）を効率的に取得します。
他の結晶構造関連ライブラリ (tkcrystal など、コメントアウトされたインポートから推測される) において、原子の情報を一元的に管理・提供する基盤として機能します。

importする方法

このライブラリを他のPythonプログラムからインポートするには、以下のいずれかの方法を使用します。

# ライブラリ全体をインポートし、プレフィックスを付けて利用する
import tkatomtypeobject

# 特定の関数やクラスを直接インポートして利用する
from tkatomtypeobject import Charge2f, SplitAtomName, tkAtomTypeObject

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

tkatomtypeobject.py は、内部で tklib パッケージに依存しています。tklib は、このライブラリが属するプロジェクト内で提供されている可能性が高いですが、外部から利用する場合は別途インストールが必要です。

必要な非標準ライブラリとそのインストール方法は以下の通りです。

tklib:
- tklib.tkprogvars: プログラムのディレクトリ変数などを定義します。
- tklib.tkutils: ユーティリティ関数（型変換、引数取得など）を提供します。
- tklib.tkre: 正規表現関連の機能を提供します。
- tklib.tkinifile: INIファイルの読み書き機能を提供します。
- tklib.tkobject: 基本的なオブジェクトクラスを提供します。

これらのライブラリは、通常、以下の pip コマンドでインストールできますが、tklib が公開されていない場合は、プロジェクトの指示に従って手動でインストールまたはパスを通す必要があります。

pip install tklib

importできる変数と関数

このライブラリは、いくつかのグローバル関数と一つのクラスをエクスポートしています。

グローバル関数

`Charge2f(charge)`

電荷を表す文字列または数値を浮動小数点数に変換します。

動作: 引数 charge が整数または浮動小数点数の場合、そのまま返します。None または空文字列の場合は 0.0 を返します。それ以外の場合、正規表現 r'(\d+)([\+\-])?' を用いて文字列から数値と符号を抽出し、浮動小数点数として変換します。例えば、"2+" は 2.0 に、"1-" は -1.0 に変換されます。
引数:
- charge (int, float, str, None): 変換する電荷の値。
戻り値:
- (float): 変換された電荷の浮動小数点数表現。

`SplitAtomName(atomname)`

原子名文字列を解析し、その構成要素（基本原子名、サイトタイプ、電荷）に分割します。

動作: 正規表現 r'([A-Z][a-z]?(\.[a-zA-Z]*)?)(\[.*\])?([\d+\-\.]*)' を使用して原子名を解析します。この正規表現は、例えば Sr.a[b]2+ のような原子名を ('Sr.a', '.a', '[b]', '2+') のように分解します。解析された電荷文字列も浮動小数点数に変換されます。
引数:
- atomname (str): 解析する原子名文字列。
戻り値:
- (tuple): (name, nametype, sitetype, charge) のタプル。
  - name (str): 基本となる原子名（例: Sr.a）。
  - nametype (str): サイト情報を含む原子名（例: Sr.a[b]）。
  - sitetype (str): サイトタイプ情報（例: .a または [b]）。
  - charge (float): 解析された電荷の浮動小数点数。

`GetAtomName(AtomicNumber)`

原子番号から原子名を取得します。

動作: DBDir で指定されたディレクトリ内の nonrel ファイルを読み込み、与えられた原子番号に対応する原子名を検索します。ファイルは特定の形式で記述されており、原子番号と原子名が関連付けられています。
引数:
- AtomicNumber (int): 検索する原子の原子番号。
戻り値:
- (str or None): 見つかった原子名（最初の文字が大文字に変換される）。ファイルが見つからないか、原子番号が見つからない場合は None。

`read_atom_db(name)`

原子名または原子番号に基づいて、原子データベースファイル（INI形式）を読み込みます。

動作: 引数 name が整数の場合は GetAtomName を使って原子名に変換します。その後、AtomDBDir 内で *-{name}.ini というパターンに一致するINIファイルを検索し、その内容を読み込みます。INIファイルから読み取られた各データは、可能な限り浮動小数点数に変換されます。特に重水素 D の場合、質量は 2.014 に固定されます。
引数:
- name (str or int): 原子名または原子番号。
戻り値:
- (dict): 読み込まれた原子情報を含む辞書。ファイルが見つからない場合は空の辞書を返しますが、エラーメッセージを出力してプログラムを終了する可能性があります。

`get_atom_information(name)`

原子名または原子番号に基づいて、原子情報を取得します。

動作: name が整数の場合は原子番号として扱い、GetAtomName を使って原子名を取得し、電荷を 0 に設定します。文字列の場合は SplitAtomName を使って原子名を解析し、電荷を抽出します。その後、ReadAtomDB を呼び出してデータベースから詳細情報を取得し、抽出された電荷情報を辞書に追加して返します。
引数:
- name (str or int): 原子名または原子番号。
戻り値:
- (dict): 原子番号、質量、電荷などの原子情報を含む辞書。

`ReadAtomDB(name)`

read_atom_db(name) グローバル関数のエイリアスです。

動作: read_atom_db(name) と同じです。
引数: read_atom_db(name) と同じです。
戻り値: read_atom_db(name) と同じです。

`GetAtomInformation(self, name)`

tkAtomTypeObject クラスのメソッドをグローバル関数として提供しているように見えますが、self 引数があるため、通常はインスタンスメソッドとして使用されるべきです。グローバル関数として呼び出す場合は、self にダミーのオブジェクトを渡す必要がありますが、推奨されません。代わりに get_atom_information(name) を使用してください。

クラス `tkAtomTypeObject`

tklib.tkobject.tkObject を継承し、特定の原子の型に関する情報を管理します。

`init(self, atomtype=None, charge=0.0, **args)`

tkAtomTypeObject のコンストラクタです。

動作: 原子の型 (atomtype) とオプションの電荷 (charge) を初期化します。内部的には SetAtomType メソッドを呼び出します。
引数:
- atomtype (str, optional): 原子名または原子タイプ文字列。デフォルトは None。
- charge (float, optional): 初期電荷。atomtype から電荷を解析できない場合に設定されます。デフォルトは 0.0。
- **args: 親クラス tkObject に渡される追加のキーワード引数。

`SetAtomType(self, type=None, charge=None)`

オブジェクトの原子タイプと電荷を設定します。

動作: type で原子タイプを設定し、charge が指定されていない場合は SplitAtomName を使って type から電荷を解析・設定します。
引数:
- type (str, optional): 設定する原子タイプ文字列。デフォルトは None。
- charge (float, optional): 設定する電荷。None の場合、type から解析されます。

`SplitAtomName(self, atomname)`

グローバル関数 SplitAtomName(atomname) のラッパーとして、インスタンスから呼び出せるようにします。

動作: グローバル関数 SplitAtomName と同じ動作をします。
引数:
- atomname (str): 解析する原子名文字列。
戻り値:
- (tuple): グローバル関数 SplitAtomName と同じ形式のタプル。

`AtomTypeOnly(self, DelPar=0)`

現在の原子タイプから、サイトタイプを除いた基本的な原子名またはサイト情報を含む原子名を取得します。

動作: SplitAtomName を使用して現在の原子タイプを解析します。DelPar が 0 (または False) の場合、サイト情報を含む原子名 (nametype) を返し、DelPar が 1 (または True) の場合、基本的な原子名 (name) を返します。
引数:
- DelPar (int, optional): 0 の場合、サイト情報を含む原子名を返します。1 の場合、サイトタイプを除いた原子名を返します。デフォルトは 0。
戻り値:
- (str): 解析された原子名またはサイト情報を含む原子名。

`AtomType(self)`

オブジェクトに設定されている原子タイプ文字列をそのまま返します。

動作: SetAtomType で設定された、または初期化時に渡された生の原子タイプ文字列を返します。
引数: なし。
戻り値:
- (str): オブジェクトの原子タイプ文字列。

`AtomNameOnly(self, DelPar=0)`

AtomTypeOnly(self, DelPar) のエイリアスです。

動作: AtomTypeOnly と同じです。
引数: DelPar (int, optional)。
戻り値: AtomTypeOnly と同じです。

`AtomName(self, DelPar=0)`

AtomType(self) または AtomTypeOnly(self, DelPar) のエイリアスとして振る舞いますが、引数 DelPar が存在するため AtomTypeOnly のラッパーとして機能します。

動作: AtomTypeOnly(DelPar) と同じです。
引数:
- DelPar (int, optional): 0 の場合、サイト情報を含む原子名を返します。1 の場合、サイトタイプを除いた原子名を返します。デフォルトは 0。
戻り値:
- (str): 解析された原子名またはサイト情報を含む原子名。

`Charge(self)`

オブジェクトに設定されている電荷を取得します。

動作: オブジェクトに電荷が設定されていればそれを返します。設定されていない場合は、現在の原子タイプを SplitAtomName で解析し、そこから電荷を抽出して設定し、その値を返します。
引数: なし。
戻り値:
- (float): 電荷の浮動小数点数表現。

`AtomicMass(self)`

Mass() メソッドのエイリアスです。

動作: Mass() と同じです。
引数: なし。
戻り値: Mass() と同じです。

`Mass(self)`

原子の質量を取得します。

動作: 内部に質量がキャッシュされていればそれを返します。なければ、AtomTypeOnly() で原子名を取得し、GetAtomInformation() を使ってデータベースから質量情報を取得し、それを返します。
引数: なし。
戻り値:
- (float): 原子質量。取得できない場合は 0.0。

`AtomicNumber(self)`

原子の原子番号を取得します。

動作: 内部に原子番号がキャッシュされていればそれを返します。なければ、AtomTypeOnly() で原子名を取得し、ReadAtomDB() を使ってデータベースから原子番号 Z の情報を取得し、それを返します。
引数: なし。
戻り値:
- (int or None): 原子番号。取得できない場合は None。

`FillAtomTypeData(self)`

原子タイプに基づいて、電荷と原子質量をオブジェクトに設定します。

動作: AtomTypeOnly() で原子名を取得し、GetAtomInformation() を使って原子情報を取得します。取得した情報から電荷と質量が存在すれば、それぞれ SetCharge() (直接は提供されていないが、内部で__Chargeを更新する処理がある) と SetAtomicMass() (同上) を使ってオブジェクトの内部状態を更新します。
引数: なし。
戻り値: なし。

`read_atom_db(self, name)`

グローバル関数 read_atom_db(name) のラッパーとして、インスタンスから呼び出せるようにします。

動作: グローバル関数 read_atom_db と同じ動作をします。
引数:
- name (str or int): 原子名または原子番号。
戻り値:
- (dict): グローバル関数 read_atom_db と同じ形式の辞書。

`ReadAtomDB(self, name)`

read_atom_db(self, name) メソッドのエイリアスです。

動作: read_atom_db(self, name) と同じです。
引数: name (str or int)。
戻り値: read_atom_db(self, name) と同じです。

`GetAtomName(self, AtomicNumber)`

グローバル関数 GetAtomName(AtomicNumber) のラッパーとして、インスタンスから呼び出せるようにします。

動作: グローバル関数 GetAtomName と同じ動作をします。
引数:
- AtomicNumber (int): 検索する原子の原子番号。
戻り値:
- (str or None): グローバル関数 GetAtomName と同じ形式の戻り値。

`get_atom_information(self, name)`

グローバル関数 get_atom_information(name) のラッパーとして、インスタンスから呼び出せるようにします。

動作: グローバル関数 get_atom_information と同じ動作をしますが、内部で self.GetAtomName や self.ReadAtomDB を呼び出しているため、クラスのコンテキストで動作します。
引数:
- name (str or int): 原子名または原子番号。
戻り値:
- (dict): グローバル関数 get_atom_information と同じ形式の辞書。

`GetAtomInformation(self, name)`

get_atom_information(self, name) メソッドのエイリアスです。

動作: get_atom_information(self, name) と同じです。
引数: name (str or int)。
戻り値: get_atom_information(self, name) と同じです。

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

tkatomtypeobject.py のソースコードには、if __name__ == "__main__": ブロックが存在しません。したがって、このライブラリファイルがPythonインタープリタによって直接実行された場合（例: python tkatomtypeobject.py）、いかなる特定のスクリプトも実行されません。ライブラリとして他のプログラムからインポートされ、その機能が利用されることを意図しています。

tkatomtypeobject.py

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

importする方法

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

importできる変数と関数

グローバル関数

Charge2f(charge)

SplitAtomName(atomname)

GetAtomName(AtomicNumber)

read_atom_db(name)

get_atom_information(name)

ReadAtomDB(name)

GetAtomInformation(self, name)

クラス tkAtomTypeObject

__init__(self, atomtype=None, charge=0.0, **args)

SetAtomType(self, type=None, charge=None)

SplitAtomName(self, atomname)

AtomTypeOnly(self, DelPar=0)

AtomType(self)

AtomNameOnly(self, DelPar=0)

AtomName(self, DelPar=0)

Charge(self)

AtomicMass(self)

Mass(self)

AtomicNumber(self)

FillAtomTypeData(self)

read_atom_db(self, name)

ReadAtomDB(self, name)

GetAtomName(self, AtomicNumber)

get_atom_information(self, name)

GetAtomInformation(self, name)

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

`Charge2f(charge)`

`SplitAtomName(atomname)`

`GetAtomName(AtomicNumber)`

`read_atom_db(name)`

`get_atom_information(name)`

`ReadAtomDB(name)`

`GetAtomInformation(self, name)`

クラス `tkAtomTypeObject`

`init(self, atomtype=None, charge=0.0, **args)`

`SetAtomType(self, type=None, charge=None)`

`SplitAtomName(self, atomname)`

`AtomTypeOnly(self, DelPar=0)`

`AtomType(self)`

`AtomNameOnly(self, DelPar=0)`

`AtomName(self, DelPar=0)`

`Charge(self)`

`AtomicMass(self)`

`Mass(self)`

`AtomicNumber(self)`

`FillAtomTypeData(self)`

`read_atom_db(self, name)`

`ReadAtomDB(self, name)`

`GetAtomName(self, AtomicNumber)`

`get_atom_information(self, name)`

`GetAtomInformation(self, name)`