このPythonプログラム `analyze_symmetry_k.py` は、与えられた結晶構造に対して、配位子の対称性適応線形結合 (SALC) を計算し、特定の中央金属d軌道とのハイブリダイゼーションの可能性を評価します。さらに、周期境界条件を考慮し、指定されたk点におけるSALCのk点互換性を解析します。

---

### 1) プログラムの動作

`analyze_symmetry_k.py` は、以下の主要なステップを実行します。

1.  **入力パラメータと構造の読み込み**:
    *   コマンドライン引数からJSON形式の入力ファイルパスを受け取ります。デフォルトのファイル名は `structure_k.json` です。
    *   JSONファイルから、格子ベクトル (`lattice`)、配位子の分数座標 (`ligands_frac`) またはデカルト座標 (`ligands_pos`)、中央金属のd軌道の種類 (`d_orbital`)、計算モード (`mode`)、各種許容誤差、SALC計算設定、k点情報などを読み込みます。

2.  **幾何情報と周期境界メタデータの構築**:
    *   入力された格子情報と配位子座標から、配位子のデカルト座標、サイトID、単位格子並進ベクトルなど、SALC計算に必要な幾何学的なメタデータを構築します。
    *   必要に応じて、配位子位置を重心で中心化します。

3.  **点群の自動検出とアラインメント**:
    *   `tkpg` ライブラリに登録されている点群プラグインをロードし、配位子の幾何構造に最も適合する点群を自動で検出します。
    *   検出された点群の正規軸規約に合わせて、配位子の位置を回転変換（アラインメント）します。このアラインメントは対称操作の適用のためであり、周期的なメタデータには影響しません。
    *   検出結果（最良の点群、候補点群のヒット率など）を標準出力に表示します。

4.  **中央金属d軌道の既約表現の特定**:
    *   入力で指定された中央金属の `d_orbital` (例: "d_xy") が、検出された点群においてどの既約表現 (`irrep`) に属するかを特定し、表示します。

5.  **配位子基底の構築と可約表現の分解**:
    *   各配位子の局所座標系を計算し、それらを用いて配位子の軌道（sigma, pi, または full）の基底セットを構築します。
    *   構築された基底が形成する可約表現の指標を計算し、それを検出された点群の既約表現に分解します。
    *   各既約表現の多重度（係数）を標準出力に表示します。

6.  **ハイブリダイゼーションの対称性チェック**:
    *   中央金属のd軌道に対応する既約表現が、配位子の可約表現の分解結果に含まれているかをチェックします。これにより、点群対称性の観点からd軌道と配位子軌道のハイブリダイゼーションが可能かどうかの「Yes/No」を判断し、標準出力に表示します。

7.  **SALCの計算とk点互換性フィルタリング**:
    *   点群の既約表現ごとに、実数ベクトルの点群SALCを抽出します。
    *   入力JSONファイルで指定された各k点（波数ベクトル）について、抽出された点群SALCがBloch位相を考慮してそのk点と互換性があるかをフィルターします。
    *   k点互換性のあるSALCが見つかった場合、その係数とBloch位相を標準出力に整形して表示します。

---

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

このプログラムは、以下の非標準ライブラリに依存しています。

*   **`numpy`**: 高度な数値計算、特に配列操作に使用されます。
*   **`tkpg`**: 対称群の操作、既約表現の計算、SALCの抽出など、プログラムの核心機能を提供するライブラリです。`tkpg.core` モジュールや点群プラグイン (`tkpg.load_plugins()`) が利用されます。

**インストール方法:**

以下のコマンドをターミナルで実行して、必要なライブラリをインストールできます。

```bash
# NumPy のインストール
pip install numpy

# tkpg のインストール (PyPIに登録されている場合)
pip install tkpg

# tkpg が PyPI にない、または特定のソースからインストールする必要がある場合:
# 例: GitHubリポジトリからインストールする場合 (URLはtkpgの公式リポジトリに置き換えてください)
# pip install git+https://github.com/your-tkpg-repo/tkpg.git
# または、ローカルにtkpgのソースコードがある場合:
# cd /path/to/tkpg-source
# pip install .
```

`json` および `argparse` はPythonの標準ライブラリであるため、追加のインストールは不要です。

---

### 3) 必要な入力ファイル

プログラムは、構造情報と計算パラメータを記述したJSON形式のファイルを必要とします。

*   **デフォルトのファイル名**: `structure_k.json`
*   **変更方法**: コマンドライン引数 `--infile` を使用して指定します。

**JSONファイルの主要な構成要素:**

*   **`lattice`**: 3x3の配列で、格子の基底ベクトルをデカルト座標で定義します。
*   **`ligands_frac`** または **`ligands_pos`**: (どちらか必須) 配位子の位置座標。`ligands_frac` は分数座標、`ligands_pos` はデカルト座標です。
*   **`d_orbital`**: (オプション, デフォルト: `"d_xy"`) 中央金属のd軌道の種類 (例: `"d_z2"`, `"d_xy"`, `"d_xz"` など)。
*   **`mode`**: (オプション, デフォルト: `"full"`) 配位子基底の種類 (例: `"full"` (sigma+pi), `"sigma"`, `"pi"`)。
*   **`kpoints_frac`**: (オプション, デフォルト: `[[0.0, 0.0, 0.0]]`) 解析するk点（分数座標）のリスト。
*   **`tolerances`**: (オプション) 幾何学的な一致や対称操作の一致に関する許容誤差。
*   **`salc`**: (オプション) SALC計算や出力に関する詳細設定。
*   **`autodetect`**: (オプション) 点群自動検出に関する詳細設定。

**`structure_k.json` の例:**

```json
{
  "lattice": [
    [5.0, 0.0, 0.0],
    [0.0, 5.0, 0.0],
    [0.0, 0.0, 5.0]
  ],
  "ligands_frac": [
    [0.5, 0.0, 0.0],
    [0.0, 0.5, 0.0],
    [0.5, 0.5, 0.0],
    [0.0, 0.0, 0.5]
  ],
  "d_orbital": "d_xy",
  "mode": "full",
  "center_ligands": false,
  "tolerances": {
    "tol_match_geom": 5e-3,
    "tol_frac_site": 1e-6
  },
  "salc": {
    "print_coeffs": true,
    "print_salc_thr": 1e-3,
    "max_salc_per_irrep": 2
  },
  "kpoints_frac": [
    [0.0, 0.0, 0.0],
    [0.5, 0.0, 0.0],
    [0.0, 0.5, 0.0]
  ],
  "k_tol": 1e-6
}
```

---

### 4) 実行後に生成される出力ファイル

このプログラムは、**ファイル形式の出力を直接生成しません。** すべての解析結果は**標準出力 (stdout)** に表示されます。

標準出力をファイルにリダイレクトすることで、結果を保存できます。

**例:**

```bash
python analyze_symmetry_k.py --infile my_structure.json > analysis_output.txt
```
上記のコマンドを実行すると、`analysis_output.txt` というファイルにプログラムの実行結果が保存されます。

---

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

`analyze_symmetry_k.py` を実行するためのコマンドラインでの使用例を以下に示します。

```bash
python analyze_symmetry_k.py [オプション]
```

**オプション:**

*   `--infile INFILE`: 構造情報を含むJSONファイルのパスを指定します。デフォルトは `structure_k.json` です。

**使用例:**

1.  **デフォルトの入力ファイル名 (`structure_k.json`) を使用して実行する場合:**
    ```bash
    python analyze_symmetry_k.py
    ```

2.  **カスタムの入力ファイル名 (`my_structure.json`) を指定して実行する場合:**
    ```bash
    python analyze_symmetry_k.py --infile my_structure.json
    ```

3.  **解析結果を `results.txt` というファイルに保存する場合:**
    ```bash
    python analyze_symmetry_k.py --infile complex_structure.json > results.txt
    ```