# Python 初心者への短いメモ

本マニュアルは Python チュートリアルではありませんが、qc-rs を操作するとき常に出てくる Python の機能がいくつか
あります。この付録は、各章に散らばる「Python メモ」を 1 か所にまとめたリファレンスです。Python を知っているなら
飛ばしてください。

## キーワード引数

qc-rs の呼び出しは各値を名前でラベル付けします:

```python
qc.chk.new(atom="H 0 0 0; F 0 0 0.9", ao="cc-pvdz", unit="angstrom", charge=0, spin=1)
```

`atom=`, `ao=`, … は**キーワード引数**:順序は問わず、呼び出しが自己説明的になります。qc-rs 全体でこのスタイルを
使います。シグネチャの `*`（例 `scf(mychk, *, ref="r", …)`）は、それ以降の引数がキーワード専用 — 名前を付けねば
ならない — ことを意味します。

## f 文字列

**f 文字列**は式をテキストに埋め込みます;`:.6f` は浮動小数を小数 6 桁で整形します:

```python
print(f"energy = {mychk.scf.energy:.6f} hartree")   # energy = -76.026772 hartree
```

## 三重引用符文字列

`"""… """` は**複数行文字列** — 1 行 1 原子で幾何を書く自然な方法です:

```python
atom = """
    O   0.000   0.000   0.117
    H   0.000   0.757  -0.469
    H   0.000  -0.757  -0.469
"""
```

先頭/末尾の空行やインデントは問題ありません;qc-rs は無視します。

## リスト 対 辞書

- **リスト** `[...]` は順序付き列:`ao=["cc-pvtz", "cc-pvdz"]` は原子ごとの基底の設定*ではありません*。
- **辞書** `{key: value}` は名前を値に対応づけます:`ao={"O": "cc-pvtz", "H": "cc-pvdz"}` は各元素に独自の基底を
  与えます。多くの qc-rs オプション（`ao=`, `pcm=`, `iop=`）が辞書を受け付けます。

## メソッドチェーン

各ワークフロー動詞は新しいチェックポイントを返すので、左から右へ**チェーン**できます:

```python
mychk = qc.chk.new(atom=..., ao="cc-pvdz").scf(ref="r").run()
```

は「チェックポイントを作る → SCF ステップを追加 → 実行」と読めます。関数形式
`qc.scf(qc.chk.new(...), ref="r").run()` は同一ですが、内側から外側へ読みます。

## 配列を読む（numpy）

いくつかのアクセサは NumPy 配列を返します。`np.asarray(...)` で確実に配列にし、`.shape` が次元、`np.round(...)`
が表示を整えます:

```python
import numpy as np
g = np.asarray(mychk.scf.gradient)   # 形 (natom, 3)
print(g.shape, np.round(g, 4))
```

## 仮想環境と `uv`

**仮想環境**（venv）は独自のパッケージを持つ隔離された Python で、プロジェクトが衝突しません。qc-rs は **`uv`**
でこれを管理します。覚えておくこと 2 つ:

- ノートブック/エディタの**カーネル**は qc-rs が入った venv でなければならず、さもないと `import qc` が失敗します
  （[エディタの章](../00-intro/editor-vscode.md)）。`import sys; print(sys.executable)` で確認。
- **`uv add <pkg>` は編集可能な qc-rs 拡張を prune します** — その後再ビルドします（`make install`）。

## ノートブック:`%matplotlib inline`

Jupyter ノートブックでは、この「マジック」でプロットがセル内に表示されます:

```python
%matplotlib inline
mychk.plot_convergence()
```

マジックはセルで設定します — セル内で `pip install` しないでください（パッケージは `uv` で環境に入れます）。

## 基底データの `importlib`

同梱の基底ファイルは通常の Python モジュールです;`importlib` で 1 つ読み込みます:

```python
import importlib
cc_pvdz = importlib.import_module("qc.basis.cc_pvdz")
cc_pvdz.O.description    # "cc-pvdz:O"
```

本マニュアルを追うのに必要な Python はこれで全部です — 残りはすべて qc-rs と化学です。