技術ドキュメント: `class_analyzer.py`

プログラムの動作

class_analyzer.py は、Pythonのオブジェクト指向プログラミングにおけるオブジェクトの構造と振る舞いを動的に解析・表示するためのツールであり、特に材料科学分野で広く利用される pymatgen ライブラリのオブジェクトを対象としています。このプログラムは、指定された結晶構造情報ファイル（CIF）を読み込み、pymatgen の機能を用いてその結晶の対称性を解析します。その過程で生成される様々な pymatgen オブジェクト（CifParser、Structure、SpacegroupAnalyzer、SymmetrizedStructure、Siteなど）に対して、そのオブジェクトが持つメソッド（関数）と属性（変数）を一覧表示する機能を提供します。

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

オブジェクトの内部構造の動的解析: あらゆるPythonオブジェクトに対し、そのクラスが定義する呼び出し可能なメソッドと、呼び出し不可能な属性（変数）を動的に抽出し、リスト化します。
型に応じた情報の表示: 整数、浮動小数点数、真偽値、文字列、リスト、タプル、辞書といった基本的なPythonの型に対しては、その値と型を直接表示します。
カスタムオブジェクトの詳細表示: pymatgen のようなライブラリで定義された複雑なカスタムオブジェクトに対しては、そのクラス名、モジュール名、そして利用可能なメソッドとその呼び出し結果（引数不要な場合）、およびその属性の現在の値と型を整形して表示します。
結晶学的対称性の解析: pymatgen を使用してCIFファイルから結晶構造を読み込み、空間群解析を実行し、対称化された構造や等価サイトの情報を取得します。
非対称単位の抽出: 対称化された構造から、結晶を記述するために必要な最小限のサイト群である非対称単位を抽出します。

このプログラムは、pymatgen オブジェクトがどのようなメソッドや属性を持っているかを学習し、デバッグする際に非常に役立ちます。特に、ライブラリのドキュメントだけでは理解しにくい、複雑なオブジェクトの具体的な中身や操作方法を視覚的に把握することを目的としています。

原理

このプログラムは、主にPythonのオブジェクト内省（Introspection）機能と、pymatgen ライブラリが提供する結晶学的な解析アルゴリズムに基づいています。

オブジェクト内省の原理

get_members 関数と print_variables 関数は、Pythonの組み込み関数や特殊属性を利用してオブジェクトの内省を行います。

dir(obj): オブジェクト obj が持つ有効な属性のリスト（メソッド、変数など）を返します。
callable(obj): オブジェクト obj が呼び出し可能（すなわち、メソッドや関数である）かどうかを判定します。
getattr(obj, name): オブジェクト obj から、指定された名前 name の属性の値を取得します。これにより、属性への動的なアクセスが可能になります。
var.__class__: オブジェクト var のクラスオブジェクトを取得します。dir() をこのクラスに対して適用することで、インスタンスではなくクラスに定義されたすべてのメンバーを取得します。
var.__module__: オブジェクトが属するモジュールの名前を取得します。
var.__dict__: オブジェクトのインスタンス辞書を取得します。これには、インスタンス固有の属性が格納されています。

これらの機能の組み合わせにより、プログラムは実行時に任意のオブジェクトの内部構造を解析し、整形された形式で出力できます。特に、メソッドの自動呼び出しは、引数を必要としない「ゲッター」のようなメソッドの戻り値を直接確認できるため、オブジェクトの状態を素早く把握するのに役立ちます。

結晶学的な解析の原理（`pymatgen` の利用）

pymatgen ライブラリは、結晶構造データの処理と解析のための強力なツールを提供します。

CIF解析 (CifParser): CIFファイルは、結晶学的な情報を記述するための標準的なテキストファイル形式です。CifParser はこのファイルを解析し、結晶の格子パラメータ、原子の種類とその座標、空間群などの情報を Structure オブジェクトとして抽出します。

CIFファイルの基本的な構造は、データブロック（data_...）と、各情報を示すタグ（_cell_length_a など）と値のペアで構成されます。
構造オブジェクト (Structure): pymatgen の Structure オブジェクトは、以下の情報を持つ結晶構造の基本的な表現です。
- 格子 (Lattice): 単位胞の形状とサイズを定義する3つの基本ベクトル \(a, b, c\) とそれらの間の角度 \(\alpha, \beta, \gamma\)。
- サイト (Site): 単位胞内の各原子の位置、原子の種類、および占有率。
\[\begin{split} \mathbf{L} = \begin{pmatrix} a_x & b_x & c_x \\ a_y & b_y & c_y \\ a_z & b_z & c_z \end{pmatrix} \end{split}\]

ここで \(\mathbf{L}\) は格子ベクトルを列に持つ行列です。
空間群解析 (SpacegroupAnalyzer): 空間群は、結晶構造が持つすべての対称操作（並進、回転、鏡映、反転など）の集合を記述します。SpacegroupAnalyzer は、与えられた Structure オブジェクトから以下の情報を導出します。
- 空間群番号と記号: 国際結晶学連合 (International Union of Crystallography, IUCr) によって標準化された識別子。
- 対称操作: 構造をそれ自身に重ね合わせる全ての操作。
- 対称化された構造 (SymmetrizedStructure): 元の構造に空間群情報が関連付けられたオブジェクトで、等価サイトのグループ化などの情報を提供します。
等価サイト (equivalent_sites): 結晶学において、空間群の対称操作によって互いに変換可能なサイトの集合を「等価サイト」と呼びます。例えば、立方晶の体心立方格子では、体心原子と頂点原子は対称操作によって等価となります。SymmetrizedStructure オブジェクトの equivalent_sites プロパティは、このような等価なサイトのリストを返します。
非対称単位 (asymmetric_unit): 結晶構造の非対称単位は、空間群の対称操作を適用することで全結晶構造を生成できる最小限の領域または原子の集合です。通常、各等価サイトのセットから代表として1つのサイトを取り出すことで、非対称単位を構成します。

本プログラムは、これらの pymatgen の概念を具体的なオブジェクトとして生成し、その内部を print_variables 関数によって詳細に表示することで、ユーザーがこれらの結晶学的情報をプログラム的にどのように扱えるかを実例として示します。

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

このプログラムは pymatgen ライブラリを使用しています。これはPythonの標準ライブラリには含まれていないため、事前にインストールする必要があります。

インストールは pip コマンドを使用して行います。

pip install pymatgen

必要な入力ファイル

プログラムの実行には、以下の条件を満たす入力ファイルが必要です。

ファイル名: SrTiO3.cif
形式: CIF (Crystallographic Information File) 形式
内容: 結晶構造に関する情報（格子定数、原子位置、空間群など）が記述されていること。pymatgen.io.cif.CifParser で解析可能な有効なCIFファイルである必要があります。

プログラムの現在の実装では、ファイルパスがスクリプト内に path = 'SrTiO3.cif' とハードコードされています。このファイルは、class_analyzer.py スクリプトと同じディレクトリに配置されている必要があります。

CIFファイルの例（SrTiO3.cif の一部）:

#_chemical_formula_sum             'SrTiO3'
#_cell_length_a                    3.905
#_cell_length_b                    3.905
#_cell_length_c                    3.905
#_cell_angle_alpha                 90
#_cell_angle_beta                  90
#_cell_angle_gamma                 90
#_symmetry_space_group_name_H-M    'P m -3 m'
#_space_group_IT_number           221
#_atom_site_label                   Sr1
#_atom_site_type_symbol             Sr
#_atom_site_fract_x                 0.0
#_atom_site_fract_y                 0.0
#_atom_site_fract_z                 0.0
# ... （以下、Ti, O などの原子サイト情報が続く）

生成される出力ファイル

このプログラムは、いかなるファイルも生成しません。全ての情報は標準出力 (stdout) へと出力されます。

コマンドラインでの使用例 (Usage)

class_analyzer.py は、引数を取らない単純なPythonスクリプトとして設計されています。実行には、Pythonインタプリタを使用してスクリプトを直接起動します。

基本的な実行コマンド:

python class_analyzer.py

SrTiO3.cif ファイルがスクリプトと同じディレクトリに存在している必要があります。

コマンドラインでの具体的な使用例

SrTiO3.cif ファイルが準備されており、pymatgen ライブラリがインストールされている環境で、class_analyzer.py を実行します。

実行コマンド:

python class_analyzer.py

実行結果の説明:

実行すると、以下のような形式で多数の情報が標準出力に表示されます。これは、プログラムが CifParser オブジェクト、Structure オブジェクト、SpacegroupAnalyzer オブジェクト、SymmetrizedStructure オブジェクト、Site オブジェクトなど、様々な pymatgen オブジェクトの内部を詳細に解析し、そのメソッドや属性を列挙しているためです。

例えば、parser オブジェクトに関する出力の一部は以下のようになります（実際の出力はpymatgenのバージョンや実装に依存し、非常に長大なため、一部を抜粋）。

---------------------------------------------------
pymatgen.io.cif.inputs class for variable parser:
  functions:
    as_dict() =  {'@module': 'pymatgen.io.cif.inputs', '@class': 'CifParser', 'filename': 'SrTiO3.cif'}
    get_string() =  #_chemical_formula_sum             'SrTiO3'
#_cell_length_a                    3.905
#_cell_length_b                    3.905
#_cell_length_c                    3.905
#_cell_angle_alpha                 90
#_cell_angle_beta                  90
#_cell_angle_gamma                 90
... (CIFファイルの内容が続く)
    parse_as_dict(True)
    parse_string(None)
    get_structures()
... (他のメソッド)

  Variables:
    filename: SrTiO3.cif <class 'str'>
    _data: {'GLOBAL': {'_chemical_formula_sum': ['SrTiO3'], ...}} <class 'dict'>
... (他の変数)

---------------------------------------------------
pymatgen.core.structure class for variable eq_sites:
  functions:
    as_dict()
    append(None)
    clear()
... (他のメソッド)

  Variables:
    _data: ([<Site Sr (0.0, 0.0, 0.0)>, <Site Sr (0.5, 0.5, 0.5)>], [<Site Ti (0.5, 0.5, 0.0)>, <Site Ti (0.5, 0.0, 0.5)>, <Site Ti (0.0, 0.5, 0.5)>], ...) <class 'tuple'>
... (他の変数)

mat_sym= Full Formula (Sr1 Ti1 O3)
Reduced Formula: SrTiO3
abc   :   3.905000   3.905000   3.905000
angles:  90.000000  90.000000  90.000000
Sites (5)
  0 Sr at (0.0000, 0.0000, 0.0000)
  1 Ti at (0.5000, 0.5000, 0.5000)
  2 O at (0.0000, 0.5000, 0.5000)
  3 O at (0.5000, 0.0000, 0.5000)
  4 O at (0.5000, 0.5000, 0.0000)
asym_unit= [<Site Sr (0.0, 0.0, 0.0)>, <Site Ti (0.5, 0.5, 0.5)>, <Site O (0.0, 0.5, 0.5)>]
---------------------------------------------------
pymatgen.core.sites class for variable asym_unit[0]:
  functions:
    as_dict() =  {'@module': 'pymatgen.core.sites', '@class': 'Site', 'species': [{'element': 'Sr', 'occu': 1}], 'xyz': [0.0, 0.0, 0.0], 'properties': {}, 'label': None}
    distance(None)
    distance_and_image(None)
... (他のメソッド)

  Variables:
    coords: [0.0, 0.0, 0.0] <class 'numpy.ndarray'>
    specie: Sr <class 'pymatgen.core.periodic_table.Element'>
    species: {Sr: 1.0} <class 'pymatgen.core.periodic_table.Specie'>
    x: 0.0 <class 'float'>
    y: 0.0 <class 'float'>
    z: 0.0 <class 'float'>
... (他の変数)

---------------------------------------------------
pymatgen.core.periodic_table class for variable asym_unit[0].specie:
  functions:
    as_dict() =  {'@module': 'pymatgen.core.periodic_table', '@class': 'Element', 'element': 'Sr'}
    atomic_mass() =  87.62
    atomic_radius() =  2.15
... (他のメソッド)

  Variables:
    Z: 38 <class 'int'>
    atomic_mass_uncertainty: 0.01 <class 'float'>
    block: 's' <class 'str'>
... (他の変数)

この出力により、CifParser オブジェクトが get_string() メソッドで元のCIFコンテンツを返すこと、eq_sites が対称的に等価なサイトのグループをリストのタプルとして保持していること、asym_unit がその代表サイトであることを確認できます。また、asym_unit[0] のような個々の Site オブジェクトが、specie（元素）、coords（座標）、x, y, z（個別座標）などの重要な属性を持っていること、さらに specie 自体が Element オブジェクトであり、その atomic_mass() や Z（原子番号）などの情報にアクセスできることが示されます。これにより、pymatgen オブジェクトの構造と、それらがどのように関連しているかを深く理解することができます。

技術ドキュメント: class_analyzer.py