# qc-rs とは？ **qc-rs** は *量子化学ツールキット* です。分子について量子力学の方程式を解き、解釈できる数値 — 全エネルギー、 平衡構造、原子電荷、化学結合、反応性、スペクトルなど — に変換するソフトウェアです。操作は **Python**（`qc` パッケージ）から行い、重い数値計算は高速なコンパイル済み **Rust** コア（`qc_rs`）が担います。 :::{note} このマニュアルの対象読者 本書は**とっつきやすい教科書スタイル**のマニュアルです。少しの化学と微積分は知っている前提ですが、量子化学・ 高性能計算（HPC）・Python に既に詳しいことは**前提としません**。新しい概念は、コピペ用のレシピではなく、 その背後にある理論（と数式）とともに一から導入します。電子構造理論に初めて触れる学部生にも使え、実運用の 計算を回す大学院生にも役立つことを目指します。 ::: ## 何が計算できるか qc-rs でできることの概観です（それぞれ後の章で詳説します）: - **自己無撞着場（SCF）** — Hartree–Fock と Kohn–Sham 密度汎関数理論（DFT）。閉殻・開殻分子（RHF/UHF/ROHF）に 対応し、多数の汎関数が使えます。 - **相関法** — 現在は RI-MP2 系列。CASSCF / FCI / DMRG や励起状態は予定。 - **力と構造最適化** — 解析的な核勾配により、分子を平衡構造へ緩和できます。 - **分子物性** — 大規模な解析スイート:原子電荷と結合次数、QTAIM と ELF/LOL トポロジー、非共有結合相互作用マップ （NCI, IGM）、芳香族性指標、概念 DFT 反応性、グリッド上の実空間場。これは *Multiwfn クラス*の波動関数解析を ツールキットに内蔵したものです。 - **環境と補正** — 陰的溶媒和（PCM / SMD）と分散補正（DFT-D3/D4）。 - **スケール** — 同じコードがノート PC でもスーパーコンピュータでも動き、複数 CPU スレッド、**MPI** による多数の マシン、**GPU** を使えます。始めるのにこれらを知る必要はありません — 準備ができたら [Part IV](../30-hpc/index.md) がゼロから教えます。 ## qc-rs はどう作られているか qc-rs は意図的に 2 つの層に分かれており、この分離を理解すると、使い方となぜ速いのかが見えてきます。 - **コンパイル済み Rust コア。** 数値的に重い部分 — 基底関数上の積分の構築、Fock 行列の組み立てと対角化、 グリッド上の密度評価、勾配の計算 — は **Rust** で書かれています。Rust は C/Fortran 並みの速度をメモリ安全性 とともに実現する現代的なコンパイル言語です。積分・SCF ソルバ・グリッド・交換相関汎関数・物性スイート・勾配 など、焦点を絞った複数のライブラリ（"crate"）として構成されています。その下では、密な線形代数に高度に最適化 された **BLAS/LAPACK**（OpenBLAS または Intel MKL）を、DFT 汎関数に **libxc** をリンクします。 - **Python フロントエンド。** qc-rs を*使う*のに Rust を書くことは決してありません。`qc` パッケージが PySCF 風の使いやすい Python API を提供し、Rust コアは単一のコンパイル済み拡張モジュール（`qc_rs`。だから 「qc-rs をインストールする」とはその拡張をコンパイルすること）として公開されます。Python は、分子を作り、 ワークフローを統括し、結果を読む場所 — 生の速度より利便性が重要な部分です。 得られるのは両方の良いとこ取りです:**人には Python の手軽さ、機械には Rust の速度。** 対話的でノートブックに 優しいインターフェースを、実運用級の数値計算が支え、コアがコンパイル済みなので、同じコードがノート PC から スーパーコンピュータまでスケールします（[Part IV](../30-hpc/index.md)）。 ## qc-rs の開発:AI ファースト（"vibe coding"） qc-rs は AI コーディングアシスタントで*使える*だけでなく、大部分がそれらによって*書かれて*います。開発は **AI ファースト** — **"vibe coding"** とも呼ばれる — で、これは意図的な第一義の開発手法であり、目新しさ狙いでは ありません。Rust コア、Python API、大規模な物性スイート、そして*このマニュアル*さえ、**Claude Code** や **Codex** のようなアシスタントで、人間の指示とレビューのもとに執筆されています。1 つのプロジェクトがこれほど 広い範囲をこれほど速くカバーできる大きな理由がこれです。信頼性を保つ歯止めは、検証優先の規律（下記）です: すべての手法を独立した参照と突き合わせ、数値を鵜呑みにしません。 **例外は qc-rs がリンクする外部ライブラリ**です — AI からではなく、その上に築く、確立した手書きの C/Fortran の 土台です: - **[libcint](https://github.com/sunqm/libcint)**（Dr. Qiming Sun）— あらゆる SCF の計算的な**心臓部**にある ガウス積分エンジン。qc-rs は積分カーネルを再実装せず、これをラップします。 - **[libxc](https://gitlab.com/libxc/libxc)**（Miguel A. L. Marques, Susi Lehtola ら）— DFT（`xc=`）手法を 支える交換相関汎関数のライブラリ。 これらの古典の周りに、qc-rs は現代的な Rust ツールキット — ワークフロー、SCF・相関ソルバ、解析スイート、勾配、 HPC 機構 — を提供します。大部分は AI 執筆で、徹底的に検証されています。 ## qc-rs の独自性 いくつかの設計選択が、qc-rs を典型的な量子化学プログラムと一線を画すものにしています: - **組み立て可能なチェックポイント/ワークフローモデル。** 一枚岩の「入力ファイル → 出力ファイル」実行ではなく、 計算は 1 ステップずつ拡張するチェックポイントです — 電子状態と結果を覚え、保存・リスタート・段階的な解析が できます（次節、および [中核概念](concepts.md)）。 - **波動関数解析が第一級市民で、後付けではない。** 多くのプログラムはエネルギーで止まり、*別の*解析ツールへ ファイルを書き出させます。qc-rs は大規模な **Multiwfn クラス**の物性スイートをツールキットに直接内蔵する ので、SCF から電荷・結合次数・QTAIM・ELF・非共有結合相互作用マップ・芳香族性・概念 DFT 反応性まで、Python を 離れずに進めます。 - **忠実で検証済みの純 Rust 再実装。** 信頼できる参照があるところでは、qc-rs はそれを Rust に移植して数値を 再現します — 積分は libcint、DFT-D3/D4 分散は Grimme グループのコード、PCM 溶媒和は PCMSolver — それぞれ 原典と突き合わせ、帰属を明記。ライセンス的に取り込めない解析（例:Multiwfn）は、公開論文から*クリーンルーム*で 再導出し、参照とブラックボックスで突き合わせて検証します。 - **HPC が後付けでなく組み込み。** CPU スレッド、多数マシンにわたる MPI、任意の NVIDIA-GPU パスが設計の一部で、 専用のスクラッチメモリアロケータと片側（RMA）分散プリミティブに支えられています — 同じコードがノート PC でも クラスタでも走ります。 ## 設計哲学と目標 qc-rs はいくつかの信条に導かれています: - **まず正しさ — そして実証可能に。** すべての手法は、出荷前に信頼できる参照（libcint, PySCF, Multiwfn）と 厳しい許容差で検証します;**数値は決して推測しません**。大きな計算を*静かに*破壊する罠 — 例えば BLAS/LAPACK と MPI の 32bit 整数の上限 — にも同じく注意深く、驚きではなく常在するハザードとして扱います。 - **安全性を犠牲にしない速度。** Rust は C/Fortran の性能をメモリ安全性とともに提供します。ホットパスは メモリを浪費せず 1 つの大きなスクラッチ確保を再利用し、密な代数を最適化された BLAS/LAPACK に流し、`unsafe` を 狭い外部関数境界に閉じ込めます。 - **自己完結、しかし巨人の肩の上に。** 目指すのは*全体*の仕事 — 入力、SCF、相関、勾配、物性、溶媒和、分散 — を 1 か所で行うこと。同時に、**最良の参照実装の上に忠実に（帰属を明記して）築く**ことで、拙く再発明することを 避けます。 - **オープンで馴染みやすい。** フリーソフトウェア（**LGPL-3.0-or-later**）で、既に知っているかもしれない PySCF 風の入力を受け付け、すべてを 1 つの使いやすい Python API で公開します。 一文で言えば目標は:**分子から深く信頼できる解析までを 1 か所で行い、ノート PC からスーパーコンピュータまで スケールする、現代的で高速・正確・自己完結の量子化学ツールキット。** ## 中心となる考え方:チェックポイントとワークフロー qc-rs の大部分は、**チェックポイント**という 1 つのオブジェクトを中心に構成されています。分子入力（構造、基底 関数、電荷、スピン）からチェックポイントを作り、そこに*ステップを追加*し（SCF 計算、物性、構造最適化）、最後に `.run()` を呼んで実行します。チェックポイントは現在の電子状態とすべての結果を覚えているので、計算は短く組み立て 可能なパイプラインのように読めます。このモデルは [中核概念](concepts.md) で丁寧に解きほぐします。まずは見た目を: ## 最初のひと味 ```python import qc # チェックポイントを作る:cc-pVDZ 基底の水分子。 mychk = qc.chk.new( atom="O 0.0000 0.0000 0.1173; H 0.0000 0.7572 -0.4692; H 0.0000 -0.7572 -0.4692", ao="cc-pvdz", unit="angstrom", ) # 制限 Hartree–Fock ステップを追加して実行。 mychk = mychk.scf(ref="r").run() print(mychk.scf.energy) # -76.026772 (全 RHF エネルギー、hartree 単位) print(mychk.scf.converged) # True ``` これで水分子の Hartree–Fock 計算が完結します。[クイックスタート](quickstart.md) では 1 行ずつ解説し、実際に 実行します。 :::{tip} Python メモ `qc.chk.new(atom=..., ao=..., unit=...)` は**キーワード引数**を使っています — 各値が名前（`atom=`, `ao=`）で ラベル付けされるので、順序は問わず、呼び出し自体が自己説明的になります。qc-rs 全体でこのスタイルを使います。 ::: ## 既知のツールとの関係 **PySCF** を使ったことがあれば、分子入力のスタイル（`atom=`、基底名、`charge`/`spin`）に馴染みを感じるはずです。 波動関数解析に **Multiwfn** を使ったことがあれば、物性スイートに見覚えがあるでしょう — qc-rs はそれらの解析を 直接（原論文からのクリーンルーム実装で）実装しているので、SCF から電荷・結合次数・NCI プロットへ Python を 離れずに進めます。qc-rs は **LGPL-3.0-or-later** ライセンスのフリーソフトウェアです。 ## 本マニュアルの読み方 - **Part I — はじめに**（現在地）:qc-rs のインストール、エディタとツールの設定、最初の計算、 チェックポイント/ワークフローモデルの学習。 - **[Part II — 基礎](../10-foundations/index.md)**:マニュアル全体の土台となる量子化学理論 — 多電子問題、 基底関数、Hartree–Fock、DFT。 - **[Part III — ユーザーガイド](../20-guide/molecular-input.md)**:日々の計算を機能ごとに。最後は [分子物性スイート](../20-guide/properties/index.md)。 - **[Part IV — 並列計算と HPC](../30-hpc/index.md)**:スレッド・MPI・GPU をゼロから。 - **[Part V — リファレンス](../40-reference/mol-spec.md)** と **[API リファレンス](../90-api/index.md)**: 正確な詳細。 Part I と Part II を順に読み、必要に応じてガイドをつまみ読みできます。準備はいいですか？ [qc-rs をインストールして動かしましょう](installation-and-make-setup.md)。