`dft`¶

概要¶

要約: PySCF/GPU4PySCF を使用して ML 領域の DFT 一点計算を実行し、MM エネルギーと再結合して ML(dft)/MM 総エネルギーを取得します。結果にはエネルギーと集団解析（Mulliken、meta-Lowdin、IAO 電荷）が含まれます。

mlmm dft は完全酵素 PDB から ML 領域を抽出し、リンク水素を付加して PySCF（または GPU4PySCF）による一点計算を実行します。DFT 評価後、PySCF 高レベルエネルギーと全系の MM 評価（REAL-low）および ML サブセットの MM 評価（MODEL-low）を組み合わせて ML(dft)/MM 総エネルギー を再計算します:

E_total = E_REAL_low + E_ML(DFT) - E_MODEL_low

デフォルトの --engine は gpu（GPU4PySCF）です。CPU のみで実行するには --engine cpu を指定してください。gpu エンジンは GPU4PySCF が利用できない場合にエラーを返します。デフォルトの汎関数/基底関数は wb97m-v/def2-tzvpd です。closed-shell の GPU 経路では GPU4PySCF の低メモリ実装 rks_lowmem.RKS をデフォルトで使用し（--lowmem/--no-lowmem）、open-shell や CPU では標準 RKS/UKS に自動フォールバックします。

最小例¶

mlmm dft -i enzyme.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -m 1 --out-dir ./result_dft

出力の見方¶

result_dft/ml_region_with_linkH.xyz
result_dft/result.yaml
標準出力の ML(dft)/MM 合成エネルギー表示

よくある例¶

汎関数/基底関数を変更して一点計算する。

mlmm dft -i enzyme.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -m 1 --func-basis "wb97m-v/def2-tzvpd" --out-dir ./result_dft_tz

ML/MM 側で凍結原子を指定して DFT を実行する。

mlmm dft -i enzyme.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q -1 -m 2 --freeze-atoms "1,3,5" --out-dir ./result_dft_freeze

SCF 収束を厳しくして反復回数を増やす。

mlmm dft -i enzyme.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -m 1 --conv-tol 1e-10 --max-cycle 200 --out-dir ./result_dft_tight

ワークフロー¶

入力処理 – 完全酵素 PDB（-i）、Amber トポロジー（--parm）、ML 領域定義（--model-pdb または --model-indices または --detect-layer による B 因子検出）を読み込みます。リンク水素は自動付加されます（C/N 親原子が 1.7 Å 以内）。YAML で明示的な link_mlmm ペアが提供されない限り有効です。
SCF 構築 – --func-basis が汎関数と基底関数に解析されます。GPU4PySCF バックエンドは利用可能な場合に使用され、closed-shell の GPU 経路では --lowmem（デフォルト）が有効なら低メモリ実装 gpu4pyscf.dft.rks_lowmem.RKS を使用します。CPU モードを強制するには --engine cpu を使用してください。mlmm dft は SCF オブジェクトに対して density_fit() を呼びません。標準 GPU/CPU 経路ではバックエンドのデフォルト JK 実装を使用し、lowmem 経路では rks_lowmem.RKS のメモリ効率の良い直接 JK が使用されます。--embedcharge が有効な場合、Amber トポロジーの MM 点電荷が pyscf.qmmm.mm_charge() を介して QM ハミルトニアンに埋め込まれ、DFT 波動関数が MM 環境で自己無撞着に分極します。
ML(dft)/MM 再結合 – DFT が収束した後、全系（REAL-low）と ML サブセット（MODEL-low）の MM 評価が計算されます。結合エネルギーは Hartree と kcal/mol で報告されます。
集団解析と出力 – Mulliken、meta-Lowdin、IAO 電荷とスピン密度（UKS のみ）が結合エネルギーブロックとともに result.yaml に書き出されます。

CLI オプション¶

オプション	説明	デフォルト
`-b, --backend CHOICE`	ONIOM 低レベル再結合用 MLIP バックエンド: `uma`（デフォルト）、`orb`、`mace`、`aimnet2`。	`uma`
`--embedcharge/--no-embedcharge`	静電埋め込みの有効化: Amber トポロジーの MM 点電荷を PySCF QM ハミルトニアンに追加し、DFT 波動関数が MM 環境により分極。	`False`
`--embedcharge-cutoff FLOAT`	`--embedcharge` 有効時に PySCF QM ハミルトニアンに埋め込む MM 点電荷の ML 領域からのカットオフ半径（Å）。	`12.0`
`--cmap/--no-cmap`	model parm7 に CMAP（骨格クロスマップ二面角補正）を含めるかどうか。デフォルト: 無効（Gaussian ONIOM と同一）。	`--no-cmap`
`-i, --input PATH`	完全酵素構造ファイル（PDB または XYZ）。XYZ の場合は `--ref-pdb` でトポロジーを指定。	必須
`--parm PATH`	全系の Amber parm7 トポロジー。	必須
`--model-pdb PATH`	ML 領域を定義する PDB（原子 ID が酵素 PDB と一致必須）。`--detect-layer` 有効時はオプション。	None
`--model-indices TEXT`	ML 領域のカンマ区切り原子インデックス（範囲指定可、例: `1-5`）。`--model-pdb` 省略時に使用。	None
`--model-indices-one-based / --model-indices-zero-based`	`--model-indices` を 1 始まりまたは 0 始まりとして解釈。	`True`（1 始まり）
`--detect-layer / --no-detect-layer`	入力 PDB の B 因子（B=0/10/20）から ML/MM レイヤーを検出。	`True`
`-q, --charge INT`	ML 領域の電荷。	必須
`-m, --multiplicity INT`	ML 領域のスピン多重度 (2S+1)。	`1`
`--freeze-atoms TEXT`	凍結する 1 始まりカンマ区切りインデックス（例: `"1,3,5"`）。YAML `geom.freeze_atoms` とマージ。	None
`--func-basis TEXT`	汎関数/基底関数ペア（`"FUNC/BASIS"`）。	`wb97m-v/def2-tzvpd`
`--max-cycle INT`	最大 SCF 反復数。	`100`
`--conv-tol FLOAT`	SCF 収束閾値 (Hartree)。	`1e-9`
`--grid-level INT`	DFT 積分グリッドレベル (0=粗, 3=デフォルト, 5=fine, 9=very fine)。	`3`
`--engine {gpu,cpu}`	GPU4PySCF（`gpu`）または CPU PySCF（`cpu`）を強制。	`gpu`
`--lowmem/--no-lowmem`	closed-shell の GPU 経路で `gpu4pyscf.dft.rks_lowmem.RKS` を使用（メモリ効率の良い直接 JK；`mlmm dft` はどちらの経路でも `density_fit()` を呼ばない）。open-shell、CPU、`rks_lowmem` 非搭載の旧 `gpu4pyscf` では標準 RKS/UKS に自動フォールバック。	`True`
`-o, --out-dir DIR`	出力ディレクトリ。	`./result_dft/`
`--link-atom-method {scaled,fixed}`	リンク原子位置モード: `scaled`（g-factor、Gaussian ONIOM 標準）または `fixed`（旧式 1.09/1.01 Å 固定）。	`scaled`
`--mm-backend {hessian_ff,openmm}`	ONIOM 低レベル評価用 MM バックエンド: `hessian_ff`（解析ヘシアン）または `openmm`（有限差分ヘシアン）。	`hessian_ff`
`--out-json/--no-out-json`	機械可読な `result.json` を `out_dir` に出力。	`False`
`--config FILE`	明示的な CLI オプション適用前に読み込むベース YAML。	None
`--show-config/--no-show-config`	解決済み設定を表示して実行を継続。	`False`
`--dry-run/--no-dry-run`	実行せずに設定検証と実行計画表示のみ行う。`--help-advanced` に表示。	`False`
`--ref-pdb FILE`	XYZ/GJF 入力時の参照 PDB（原子順序と残基マッピングのテンプレート）。	None
`--convert-files/--no-convert-files`	PDB テンプレートがあれば XYZ/TRJ → PDB コンパニオンファイルを生成。	`True`

出力¶

out_dir/ (デフォルト: ./result_dft/)
├── ml_region_with_linkH.xyz    # DFT に使用された ML 領域座標（リンク水素付き）
├── result.yaml                 # DFT + ML(dft)/MM エネルギーサマリー、電荷、スピン密度
├── result.json                 # --out-json 指定時のみ
└── (stdout)                    # 整形された設定ブロックとエネルギーの出力

result.yaml の内容:
- energy: Hartree/kcal/mol 値、収束フラグ、実行時間、バックエンド情報（engine: gpu4pyscf(rks_lowmem) / gpu4pyscf / pyscf(cpu)、used_gpu、used_lowmem）。
- mlmm_energy: REAL-low / MODEL-low の MM 評価値と再結合エネルギー E_total = E_REAL_low + E_ML(DFT) - E_MODEL_low（Hartree と kcal/mol）。
- charges: Mulliken、meta-Lowdin、IAO 原子電荷（手法失敗時は null）。
- spin_densities: Mulliken、meta-Lowdin、IAO スピン密度（UKS のみ）。
電荷、多重度、スピン (2S)、汎関数、基底関数、収束パラメータ、解決済み出力ディレクトリも要約されます。

YAML 設定¶

マッピングルートを受け付けます。dft セクション（およびオプションの geom、calc/mlmm）が存在する場合に適用されます。マージ順:

デフォルト
--config
明示的に指定した CLI オプション

dft キー（括弧内はデフォルト）:

func_basis（"wb97m-v/def2-tzvpd"）: 結合 FUNC/BASIS 文字列。
conv_tol（1e-9）: SCF 収束閾値 (Hartree)。
max_cycle（100）: 最大 SCF 反復数。
grid_level（3）: PySCF grids.level。
verbose（4）: PySCF 冗長度 (0-9)。
out_dir（"./result_dft/"）: 出力ディレクトリルート。

geom:
 coord_type: cart                  # オプションの geom_loader 設定
calc:
 model_charge: 0                   # ML 領域の電荷
 model_mult: 1                     # スピン多重度 2S+1
mlmm:
 real_parm7: real.parm7            # Amber parm7 トポロジー
 model_pdb: ml_region.pdb          # ML 領域定義
dft:
 func_basis: wb97m-v/def2-tzvpd      # 交換相関汎関数 / 基底関数セット
 conv_tol: 1.0e-09                # SCF 収束閾値 (Hartree)
 max_cycle: 100                    # 最大 SCF 反復数
 grid_level: 3                     # PySCF グリッドレベル
 verbose: 4                        # PySCF 冗長度 (0-9)
 out_dir: ./result_dft/            # 出力ディレクトリルート

注意事項¶

Blackwell アーキテクチャ GPU（RTX 50xx）: GPU4PySCF は小規模な系（~100原子）でもメモリ不足エラーが発生する場合があります。これらの GPU では --engine cpu または外部 DFT プログラム（ORCA, Gaussian）を使用してください。
def2-TZVPD でメモリ不足になる場合: デフォルトの基底関数 def2-tzvpd は大きく、16–24 GB GPU で 150 原子以上の系では OOM が発生する場合があります。--func-basis 'wb97m-v/def2-svp' を使用してください。def2-SVP と def2-TZVPD のバリアハイト差は通常 1–3 kcal/mol です。
GPU4PySCF のコンパイル済みホイールは非 x86 環境では動作しない場合があります。ソースからビルドしてください（参照: https://github.com/pyscf/gpu4pyscf）。

dft¶

概要¶