point_group.py ドキュメント

概要

point_group.py は、結晶点群操作の解析と可視化を行うPythonユーティリティスクリプトです。 Hermann–Mauguin記号に基づいて、対称操作の表示、指定された方向ベクトルの群作用による展開、およびステレオ投影図の描画機能を提供します。 tkpointgroup ライブラリと連携し、点群の数学的処理を扱います。

インストール

非標準ライブラリ

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

  • numpy

  • matplotlib

  • tkpointgroup

インストール手順

以下のコマンドを使用して、必要なライブラリをインストールしてください。 特に tkpointgroup は一般的なPyPIパッケージではない可能性があるので、入手方法に注意してください。 （コードからは tkpointgroup の標準的なインストール方法は確認できませんが、通常は pip を使用します。）

pip install numpy matplotlib
# tkpointgroup のインストール方法
# pip install tkpointgroup # もしくは、該当するリポジトリからインストール

使用方法

コマンドライン引数

point_group.py は、以下のコマンドライン引数をサポートします。

  • mode (必須): 実行モードを指定します。

    • list: 利用可能な32種の結晶点群（Hermann–Mauguin記号）を一覧表示します。

    • pg: 指定された点群の各対称操作（3x3行列）とその分類を表示します。

    • stereo: 指定された点群の対称要素と、与えられたシードベクトルを群作用で展開した方向をステレオ投影図として可視化します。

    • expand: 指定された点群により、与えられたシードベクトルがどのように展開されるか、その結果の方向ベクトル群を数値的に出力します。

  • --pg, -p: 点群のHermann–Mauguin記号を指定します（例: 4mm, -3m, m-3m）。

  • --vec: stereo または expand モードで使用するシード方向ベクトルを指定します（例: "0.1 0.2 0.3" または "0.8,0.1,0.05"）。デフォルト値は '0.8,0.1,0.05' です。

  • --no-anno: stereo モードで展開された方向の番号ラベルを無効にします。

実行例

以下に、point_group.py の主要な使用例を示します。

点群の一覧表示:

python point_group.py list

指定した点群の対称操作とその分類の表示:

python point_group.py pg --pg Td

指定した点群とシードベクトルによるステレオ投影図の表示:

python point_group.py expand --pg C3v --vec "0.1 0.2 0.3"

指定した点群のステレオ投影図の表示（アノテーションなし）:

python point_group.py stereo --pg D2h
python point_group.py pg --pg Oh --no-anno

stereo モードおよび main() 関数内で matplotlib の図が表示された場合、図が閉じられるまでプログラムは終了せずにユーザーの ENTER キー入力を待ちます。

モジュールの詳細

point_group.py

説明

本スクリプトは、結晶点群（Hermann–Mauguin記号）に基づいて、対称操作の表示、指定された方向ベクトルの群作用による展開、およびステレオ投影図の描画機能を提供します。 tkpointgroup ライブラリと連携し、点群の数学的処理を扱います。

  • list モード: 利用可能な32種の結晶点群（Hermann–Mauguin記号）を一覧表示します。

  • pg モード: 指定された点群の各対称操作（3x3行列）とその分類（回転、鏡映など）を表示します。

  • stereo モード: 指定された点群の対称要素（回転軸、鏡映面）と、与えられたシードベクトルを群作用で展開した方向をステレオ投影図として可視化します。

  • expand モード: 指定された点群により、与えられたシードベクトルがどのように展開されるか、その結果の方向ベクトル群を数値的に出力します。

関連リンク: :doc:point_group_usage

依存関係

  • 標準ライブラリ:

    • sys

    • argparse

  • 非標準ライブラリ:

    • numpy

    • matplotlib.pyplot

    • matplotlib.lines.Line2D

    • tkpointgroup

グローバル定数

  • PG_HM: 32種の結晶点群を表すHermann–Mauguin記号のリストです。

    PG_HM = [
    "1", "-1", "2", "m", "2/m", "222", "mm2", "mmm",
    "4", "-4", "4/m", "422", "4mm", "-42m", "4/mmm",
    "3", "-3", "32", "3m", "-3m",
    "6", "-6", "6/m", "622", "6mm", "-6m2", "6/mmm",
    "23", "m-3", "432", "-43m", "m-3m"
]

  • EPS: 数値計算におけるゼロ判定のための微小許容誤差です。

    EPS = 1e-10

  • HM_TO_SCHOENFLIES_FALLBACK: tkpointgroup ライブラリが直接解釈できない一部のHermann–Mauguin記号を、Schoenflies記号などに変換するためのマッピング辞書です。

    HM_TO_SCHOENFLIES_FALLBACK = {
    "-4":   "S4",
    "-6":   "S6",
    "2/m":  "C2h",
    "422":  "D4",
    "32":   "D3",
    "622":  "D6",
    "-42m": "D2d",
    "-6m2": "D3h",
    "23":   "T",
    "m-3":  "Th",
    "432":  "O",
    "-43m": "Td",
    "m-3m": "Oh",
}

  • PG_ALIASES: 点群記号のエイリアスを定義する辞書で、Schoenflies記号などをHermann–Mauguin記号にマッピングします。

    PG_ALIASES = {
    # C系
    "C1": "1",
    "Ci": "-1", "S2": "-1",
    "C2": "2",
    "Cs": "m",
    "C2h": "2/m",

    "C3": "3",
    "C3i": "-3", "S6": "-3",
    "C3v": "3m",
    "C3h": "3/m",

    "C4": "4",
    "S4": "4̅",   # "bar 4"
    "C4h": "4/m",
    "C4v": "4mm",
    "D2": "222",
    "D2h": "mmm",

    "C6": "6",
    "C6h": "6/m",
    "C6v": "6mm",
    "C3h": "3m1",  # 場合により "31m" と両方必要かも
    "D6h": "6/mmm",

    # T, O, I 系
    "T": "23",
    "Th": "m-3",
    "Td": "-43m",
    "O": "432",
    "Oh": "m-3m",

    "I": "532",
    "Ih": "m-3̅5"
}

関数

_pg_symbol_for_tkg(symbol: str) -> str

概要: Hermann–Mauguin記号を tkpointgroup ライブラリが解釈できる記号に変換して返します。

詳細説明: tkpointgroup は多くのH–M記号を直接受け入れますが、一部はSchoenflies記号などにフォールバック変換する必要があります。この関数は、まず直接試行し、失敗した場合は定義済みのフォールバックマップ (HM_TO_SCHOENFLIES_FALLBACK) を使用します。

パラメータ:

  • symbol: Hermann–Mauguin記号の文字列。

戻り値: tkpointgroup が認識できる点群記号の文字列。

orthogonalize(R)

概要: 入力行列を特異値分解（SVD）を用いて最も近い直交行列へ射影し、det=±1 を保証します。

詳細説明: 行列の数値誤差を修正し、det=±1 の直交行列であることを保証します。 tkpointgroup.snap_matrix を利用して、直交性と行列式の符号を整えます。

パラメータ:

  • R: 3x3の行列（numpy.ndarray またはそれに変換可能なもの）。

戻り値: 直交化された3x3の numpy.ndarray。

unique_dirs(vs, tol=1e-5, hemisphere=True)

概要: 方向ベクトルのリストから重複するものを排除し、一意な方向ベクトルを抽出します。hemisphere=True の場合、z>=0 に統一し、正負を同一視します。

詳細説明: ベクトルはまず正規化されます。hemisphere=True の場合、z座標が負のベクトルは符号を反転させて上半球（z>=0）に統一し、正負を同一視して重複排除を行います。比較には指定された許容誤差 tol を使用します。ノルムが EPS より小さいゼロベクトルに近いものは無視されます。

パラメータ:

  • vs: 方向ベクトルのリストまたは配列。

  • tol: ベクトルの比較に使用する数値的な許容誤差。デフォルトは 1e-5。

  • hemisphere: Trueの場合、z<0のベクトルは反転され、±同一視で重複排除されます。デフォルトは True。

戻り値: 一意な方向ベクトルのリスト。

classify_symop_pg(R)

概要: 直交化された3x3行列から点群の対称操作の種類を簡易的に分類します。

詳細説明: 直交化済み行列 R を受け取り、点群の操作を簡易的に分類します。 恒等操作、反転操作、回転操作（Cn）、鏡映操作（σ）、回反操作（Sn）を判別します。 行列の行列式（det）とトレース（trace）に基づいて分類を行います。 （ここは従来のロジックのままであり、必要に応じて tkg.classify_label も利用可能です）。

パラメータ:

  • R: 直交化された3x3の対称操作行列（numpy.ndarray）。

戻り値: 分類された対称操作の種別を示す文字列（例: "Rotation C3", "Mirror (σ)"）。

display_pg_info(symbol=None)

概要: 指定された点群、または全ての利用可能な点群の情報を表示します。

詳細説明: symbol がNoneの場合、32種の結晶点群Hermann–Mauguin記号を一覧表示します。 symbol が指定された場合、その点群に含まれる全ての対称操作行列（3x3 numpy.ndarray）と、 それぞれの操作の簡易分類 (classify_symop_pg による) を表示します。 tkpointgroup ライブラリを使用して操作行列を取得します。

パラメータ:

  • symbol: 表示する点群のHermann–Mauguin記号（文字列）。Noneの場合は全点群をリストします。デフォルトは None。

戻り値: なし。情報を標準出力に出力します。

stereo_project(v)

概要: 単位球上の点 v=(x,y,z) をステレオ投影（南極からz=0平面へ）します。

詳細説明: 単位球上の点 v=(x,y,z) をステレオ投影（南極から z=0 平面）します。 上半球 z>=0 を単位円内に写す: x' = x/(1+z), y' = y/(1+z)。 z座標が -1 に近い点（南極）は無限遠になるため、数値的に問題がある場合は None を返します。

パラメータ:

  • v: 単位球上の点の3次元座標ベクトル（numpy.ndarray）。

戻り値: ステレオ投影された2次元座標のタプル (x', y')。南極点に近い場合は None。

plot_pg_projection(symbol, seed_vec=None, annotate=True)

概要: 指定された点群のステレオ投影図を生成し、表示します。これには回転軸、鏡映面、そしてシードベクトルを群で展開した方向が含まれます。

詳細説明: 回転軸（固有値1の固有ベクトル）、鏡映面（大円）、および与えられたシードベクトルを点群の操作で展開した方向をプロットします。全ての方向はz>=0の上半球に正規化され、ステレオ投影されます。鏡映面は破線で、回転軸は白い三角形で、展開された方向は番号付きの青い丸で示されます。プロット後、展開された方向の座標もコンソールに出力します。

パラメータ:

  • symbol: 描画する点群のHermann–Mauguin記号。

  • seed_vec: 点群で展開する開始方向ベクトル（3次元 numpy.ndarray）。Noneの場合、デフォルト値 [0.8, 0.1, 0.05] を使用します。デフォルトは None。

  • annotate: 展開された方向に番号ラベルを表示するかどうかのブール値。デフォルトは True。

戻り値: なし。matplotlib の図を表示します。

expand_direction(symbol, vec)

概要: 指定された点群の全操作を与えられた方向ベクトルに作用させ、展開された一意な方向の集合を返します。

詳細説明: 入力ベクトルはまず正規化され、z>=0の上半球に統一されます。 各対称操作によって変換されたベクトルも同様に正規化・上半球統一され、重複排除 (unique_dirs) 後にリストとして返されます。 ゼロベクトルに近い入力は許可されません。

パラメータ:

  • symbol: 方向展開に使用する点群のHermann–Mauguin記号。

  • vec: 展開する開始方向ベクトル（3次元のリスト、タプル、または numpy.ndarray）。

戻り値: 点群によって展開された一意な方向ベクトルのリスト。

例外:

  • RuntimeError: 点群の構築に失敗した場合。

  • ValueError: ゼロベクトルが入力された場合。

main()

概要: 本スクリプトのコマンドラインインターフェースを処理し、指定されたモードに応じた機能を実行します。

詳細説明: プログラムの実行モード（list, pg, stereo, expand）を解析し、対応する関数を呼び出します。点群記号、シードベクトル、アノテーションオプションなどのコマンドライン引数を処理し、不正な入力があった場合はエラーメッセージを表示して終了します。matplotlib の図が表示された場合は、ユーザーが ENTER を押すまでブロックします。

パラメータ:

  • None

戻り値: なし。

入出力仕様

  • 入力:

    • コマンドライン引数:

      • モード (list, pg, stereo, expand)

      • 点群のHermann–Mauguin記号 (--pg)

      • シード方向ベクトル (--vec)

      • アノテーションの有効/無効フラグ (--no-anno)

    • ユーザー入力 (stereo モードの matplotlib ウィンドウ表示後):

      • ENTER キー入力（図を閉じてプログラムを終了するため）

  • 出力:

    • 標準出力:

      • list モード: 利用可能な32種の結晶点群Hermann–Mauguin記号のリスト。

      • pg モード: 指定された点群の対称操作の総数、各対称操作の分類（例: Rotation C3, Mirror (σ)）、および対応する3x3行列。

      • stereo モード: ステレオ投影図のタイトル、正規化されたシード方向ベクトル、および展開された方向ベクトルの座標リスト。

      • expand モード: 指定されたシード方向ベクトルから点群によって展開された一意な方向ベクトルの座標リスト。

      • エラーメッセージ: 無効な点群記号、不正なベクトル形式、ゼロベクトル入力などのエラーが発生した場合。

    • グラフィカル出力:

      • stereo モード: matplotlib を使用したステレオ投影図ウィンドウ。この図には以下の要素が含まれます。

        • 単位円枠。

        • 鏡映面に対応する破線の大円。

        • 回転軸に対応する白い三角形のマーカー。

        • 展開された方向に対応する番号付きの青い丸。

        • 凡例。