# 分子指定の文法

これは `qc.chk.new(...)` が受け付ける **`atom=`** 文字列文法の完全なリファレンスです。[分子の入力の章](../20-guide/molecular-input.md)
がチュートリアル的な導入で、本ページは正確で網羅的な仕様です。文法は Gaussian 互換です。

## 原子行の文法

各原子は 1 行（原子は改行または `;` で区切る）:

```text
Element-label[-Atom-type[-Charge]][(param=value,...)] [freeze-code] x y z
```

| フィールド | 必須 | 説明 |
|---|---|---|
| `Element-label` | ✓ | 化学記号、原子番号、または特殊記号 |
| `-Atom-type` | — | MM 力場タイプ（例 `CT`, `O`, `Bq`） |
| `-Charge` | — | MM 部分電荷（浮動小数） |
| `(param=value,...)` | — | 核 / フラグメントパラメータ |
| `freeze-code` | — | 整数:`0` = 自由、`−1` = 固定 |
| `x y z` | ✓ | デカルト座標（`unit=`、既定オングストローム） |

## 元素ラベル

```text
(chemical-symbol | atomic-number) [identifier]
```

- **化学記号** — `H`, `He`, `C`, `Fe`, …（大文字小文字を区別しない）。
- **原子番号** — `1`, `6`, `26`, …。
- **識別子** — 記号/番号の後の任意のラベル接尾辞、長さ制限なし（`C1`, `C2`, `O_a`, `Fe3`）。ラベルは基底辞書の
  引き当てと原子ごとの選択に使われます。

```text
C        # 炭素
C1       # 炭素、ラベル "C1"
6        # 原子番号による炭素
Fe3      # 鉄、ラベル "Fe3"
```

## 原子タイプ（MM フィールド）

```text
Element-AtomType
Element-AtomType-Charge
Element-AtomType--NegCharge     ← 負電荷はダブルダッシュ
```

MM タイプは保存されます（`ParsedAtomLine.mm`）が、現在は量子化学積分に影響しません。原子タイプとしての `Bq`
（例 `O-Bq`）は**ゴースト原子**（下記）を作ります。

```text
C-CT          # SP3 脂肪族炭素
C-CT-0.32     # 部分電荷 +0.32
O-O--0.5      # ダブルダッシュで部分電荷 -0.5
```

## 核パラメータ

元素ラベルの後の括弧内に、カンマ区切りで:

| キーワード | 型 | 意味 |
|---|---|---|
| `Iso=n` | `u32` | 同位体質量数（`Iso=13` → ¹³C） |
| `Spin=n` | `i32` | 核スピン（½ 単位） |
| `ZEff=n` | `f64` | 有効核電荷（スピン軌道、ESR g テンソル） |
| `ZNuc=n` | `f64` | 核電荷 `z` を**上書き** |
| `QMom=n` | `f64` | 核四重極モーメント |
| `NMagM=n` | `f64` | 核磁気モーメント（核磁子） |
| `RadNuclear=r` | `f64` | 有限核半径（a.u.） |
| `Fragment=n` | `u32` | フラグメント番号（カウンターポイズ / `Guess=Fragment`） |
| `RESNum` / `RESName` / `PDBName` | str | PDB メタデータ（受理、QC では無視） |

```text
C(Iso=13,Fragment=2)  0.0 0.0 0.0
O(ZNuc=8.0)           0.0 0.0 0.0
```

これらメタデータの多くは解析・保存されますが、まだハミルトニアンやオプティマイザに影響しません。

## フリーズコード

ラベルと座標の間の整数:`0` = 自由（既定）、`−1` = 固定。解析・保存されます（`ParsedAtomLine.frozen`）が、構造
オプティマイザは**まだ**消費しません。

```text
C  0  0.000 0.000 0.000   # 自由
C -1  0.000 0.000 1.500   # 固定（解析されるが未強制）
```

## 特殊原子

### ゴースト原子（`Element-Bq`）

**核電荷 0、電子なし、しかし名前の元素の完全な基底関数** — カウンターポイズ/BSSE 用。ゴーストは `natom()` に
**数えられ**ます（AO 関数を持つ）が、`nelectron()` と `nuclear_energy()` には 0 を寄与します。

```text
O-Bq     # ゴースト酸素
H-Bq     # ゴースト水素（自動的に "H" の基底を継承）
```

ゴーストの基底引き当て優先度:(1) 原子ラベルキー、(2) 基底元素記号、(3) 元素フォールバック。

### ダミー原子（`X`, `Xx`）

純粋な幾何学的参照点:**核電荷なし、電子なし、基底関数なし**。認識される形式（大文字小文字を区別しない）:`X`,
`Xx`, `X1`, `X-ref`。`dummy_atoms()` に保存;`natom()` に**数えられません**。

### 並進ベクトル（`TV`）

周期系では、幾何の後に格子ベクトルを付けます（1 次元ポリマーは 1 本、シートは 2 本、結晶は 3 本）。
`translation_vectors()`（bohr）に保存;`natom()`/`ndummy()` に数えられません。

```text
C   0.000 0.000 0.000
C   0.000 0.000 1.420
TV  2.460 0.000 0.000
```

## 電荷 / スピン

公開 API では `qc.chk.new(...)` に `charge=` と `spin=` を渡します。`spin` は **Gaussian 多重度 2S+1**
（1 = 一重項、2 = 二重項、3 = 三重項）です。生のテキスト形式（低レベルパーサ用）は `charge mult`、または
フラグメントごとに `total_charge total_mult  frag1_charge frag1_mult  …`。

## 不変条件（要約）

| 規則 | |
|---|---|
| ゴースト & ダミー原子 | 電子と核間反発を**寄与しない** |
| ゴースト原子 | AO 基底関数を**持つ**;`natom()` に数えられる |
| ダミー原子 | 基底関数**なし**;`natom()` に数え**られない** |
| 並進ベクトル | `natom()` / `ndummy()` に数えられない |
| 保存座標 | 常に **bohr**（入力時に `unit=` から変換） |

すべての特殊原子の検証済みの実例は [分子の入力の章](../20-guide/molecular-input.md) を参照。