nvmolkit-usage

nvMolKit の使い方

目的

一般的な RDKit 操作を GPU で高速化し、バッチ処理する実装です。可能な限り RDKit と同じ API を採用していますが、バッチ処理を前提としており、rdkit.Chem.Mol のリスト（またはフィンガープリントのリスト）を受け取り、1 つ以上の GPU で並列処理します。nvMolKit はビルド時に RDKit とリンクされます。入出力は実際の RDKit Mol オブジェクトです。

このスキルでは、インストール済みの Python API を扱います。nvMolKit のソースからのビルドは対象外です。

nvMolKit が適しているケース

次のような場合は nvMolKit の利用をご検討ください。

• 大量の分子をまとめて処理するワークロード（通常は数千個以上）です。
• 評価指標が、分子ごとのレイテンシではなく、スループット／バッチ全体の合計実行時間です。
• バッチ内のすべての分子に対して同じ操作を繰り返し実行するため（ライブラリのフィンガープリンティング、多数のコンフォマーの埋め込み／最小化、一括ペアワイズ類似度計算など）、GPU を高い使用率に保てます。

要件

• Compute Capability 7.0（V100）以上の NVIDIA GPU
• CUDA 12.6 以降と互換性のある CUDA ドライバー
• CUDA をサポートする torch の正常なインストール（nvMolKit は torch の CUDA 配列インターフェイスを介して GPU テンソルを返します）

インストールを案内する際は、nvMolKit のインストール前に、ホストドライバーがサポートする PyTorch CUDA バックエンドをユーザーに選択してもらってください。nvMolKit の PyPI ホイールは CUDA Toolkit 12.9 でビルドされており、CUDA 12 のランタイムパッケージに依存しますが、インストールコマンドで指定しないと、pip/uv が CUDA 13 の PyTorch ホイールを選択する場合があります。

• Conda：conda-forge の pytorch-gpu を推奨します。cuda-version=12.6、またはドライバーがサポートする別の CUDA バージョンを指定してください。
• pip：nvMolKit のインストール前に、PyTorch のインストール選択ページまたは旧バージョンのページを参照して、CUDA 12.x バックエンド用の torch をインストールするよう案内してください。
• uv：たとえば uv pip install --torch-backend=cu128 nvmolkit のように、バックエンドを明示して nvMolKit をインストールしてください。

入力

• 必須：ユーザーのコードまたは分子データセットから操作を選択し、分子またはフィンガープリントを指定します。SMILES は RDKit で解析し、解析に失敗したもの（None）は除外してください。
• 分子操作では RDKit の Mol オブジェクトを使用します。ETKDG では水素を追加してください。最小化とコンフォマーの比較には、既存のコンフォマーが必要です。
• フィンガープリントの類似度計算では、パックされた AsyncGpuResult、torch テンソル、または NumPy 配列を受け取ります。各行に 1 つの分子を格納し、ワードの型は int32 または uint32 にしてください。
• 任意：ユーザーが求めるワークフローに応じて、コンフォマー数、フィンガープリント設定、カットオフ、出力モード、ハードウェアオプションを指定してください。指定がない場合は、文書化された API のデフォルトを使用してください。

制限事項

• CUDA が必須です。CPU へのフォールバックはありません。CPU 実行が必要な場合は、RDKit を直接使用してください。
• 単一分子の処理や、バッチ処理できない操作には、通常の RDKit のほうが適しています。
• ETKDG は、カスタム境界行列、カスタム CPCI、座標マップ、フラグメントを個別に分けた埋め込みをサポートしていません。
• 部分構造検索は、キラリティを考慮したマッチング、拡張立体化学、その他の高度な RDKit SubstructMatchParameters オプションをサポートしていません。

手順

1. nvMolKit のコードを書く前に、以下のスモークテストを実行してください。
2. エントリーポイントの表から API を選び、その入力要件に従ってください。
3. 以下の説明に従って結果を処理してください。ホスト側で読み取る前に、非同期の GPU 結果を同期してください。

実際のコードを書く前にインストールを確認する

import nvmolkit
import torch
from rdkit import Chem
from nvmolkit.fingerprints import MorganFingerprintGenerator

print("nvmolkit:", nvmolkit.__version__)
print("cuda available:", torch.cuda.is_available())
print("device count:", torch.cuda.device_count())

mols = [Chem.MolFromSmiles(smi) for smi in ["CCO", "c1ccccc1", "CC(=O)O"]]
fpgen = MorganFingerprintGenerator(radius=2, fpSize=1024)
result = fpgen.GetFingerprints(mols)
torch.cuda.synchronize()
fps = result.torch()
print("fps shape:", tuple(fps.shape), "dtype:", fps.dtype)
# Expected: shape (3, 32), dtype torch.int32  (1024 bits packed into 32 int32s per row)

失敗した場合は推測で対応せず、ユーザーにインストールガイドを案内してください。

エントリーポイント

タスク	モジュール	主なエントリーポイント
Morgan フィンガープリント	nvmolkit.fingerprints	MorganFingerprintGenerator(radius, fpSize).GetFingerprints(mols)
バルク Tanimoto／コサイン類似度	nvmolkit.similarity	crossTanimotoSimilarity(...)、crossCosineSimilarity(...)、および GPU メモリに収まらない大きさの結果に対応する *MemoryConstrained バリアント
ETKDG 配座埋め込み	nvmolkit.embedMolecules	EmbedMolecules(molecules, params, confsPerMolecule, ...)
MMFF94 最適化（一括実行）	nvmolkit.mmffOptimization	MMFFOptimizeMoleculesConfs(molecules, ..., minimizerKind=..., fireOptions=...)
UFF 最適化（一括実行）	nvmolkit.uffOptimization	UFFOptimizeMoleculesConfs(molecules, ..., minimizerKind=..., fireOptions=...)
カスタムオプションと制約を指定した力場	nvmolkit.batchedForcefield	MMFFBatchedForcefield(mols, properties=..., nonBondedThreshold=..., ignoreInterfragInteractions=..., hardwareOptions=...)、UFFBatchedForcefield(mols, vdwThreshold=..., ...)。分子ごとのビュー ff[i] では、add_distance_constraint、add_position_constraint、add_angle_constraint、add_torsion_constraint を使用できます。メソッド：.compute_energy()、.compute_gradients()、.minimize(maxIters, forceTol, minimizerKind=..., fireOptions=...)
配座間の RMSD	nvmolkit.conformerRmsd	GetConformerRMSMatrix(mol)、GetConformerRMSMatrixBatch(mols)
ねじれフィンガープリント偏差（TFD）	nvmolkit.tfd	GetTFDMatrix(mol)、GetTFDMatrices(mols)
Butina クラスタリング	nvmolkit.clustering	butina(distance_matrix, cutoff)（事前計算済み行列）、fused_butina(fingerprints, cutoff)（メモリ効率の高いオンザフライ処理）。どちらも、RDKit とデバイスへの出力モードを明示的に指定できます
部分構造検索	nvmolkit.substructure	hasSubstructMatch、countSubstructMatches、getSubstructMatches
最大共通部分構造	nvmolkit.mcs	全ペア、明示的に指定したペア、または対応する 2 つの分子リストを対象とする findMCS(mols, ...)
ハードウェアの調整（バッチサイズ、GPU ID）	nvmolkit.types	ETKDG／MMFF／UFF に渡す HardwareOptions(...)
オプションの自動チューニング	nvmolkit.autotune	tune_embed_molecules、tune_mmff_optimize、tune_uff_optimize、tune_batched_forcefield、tune_substructure、tune_mcs。optuna パッケージが必要です

結果の型と実行モデル

処理の出力に応じて、GPU 上に保持される出力を扱う戻り値の形式が 2 種類あります。

AsyncGpuResult

単一のフラットなテンソルを返す処理（フィンガープリント、類似度行列、RMSD／TFD ベクトル、Butina の入力）で使用されます。主な動作：

• 非同期です。呼び出しが戻った時点では、カーネルの処理が完了していない場合があります。
• result.torch() は、GPU 上のゼロコピー torch.Tensor を返します。ホスト側で値を読み取る前に同期する責任は呼び出し側にあります。
• result.numpy() は同期を行い、CPU 上の numpy 配列を返します。
• __cuda_array_interface__ を公開するため、ホストを経由せず、そのまま他の nvMolKit 関数に渡せます（例：フィンガープリントから類似度の計算）。

CUDA ストリームの制御

AsyncGpuResult を返す API の一部は、オプションの stream: torch.cuda.Stream | None = None 引数を受け取り、nvMolKit の処理をデフォルト以外のストリームに送信して、独自のカーネルと並行して実行できます。省略した場合、呼び出しには現在の torch ストリームが使用されます。

stream 引数を受け取る API：

• MorganFingerprintGenerator.GetFingerprints
• crossTanimotoSimilarity、crossCosineSimilarity およびそれらの *MemoryConstrained バリアント
• butina、fused_butina
• GetConformerRMSMatrix、GetConformerRMSMatrixBatch

その他の API（ETKDG、MMFF／UFF 最適化、TFD、部分構造検索、MCS）は、呼び出し元に対して同期的に動作するため、ストリームを指定する必要はありません。

一般的なパターン：

import torch
from rdkit import Chem
from nvmolkit.fingerprints import MorganFingerprintGenerator
from nvmolkit.similarity import crossTanimotoSimilarity

stream = torch.cuda.Stream()
fpgen = MorganFingerprintGenerator(radius=2, fpSize=1024)
mols = [Chem.MolFromSmiles(smi) for smi in ["CCO", "c1ccccc1", "CC(=O)O"]]

with torch.cuda.stream(stream):
    fps = fpgen.GetFingerprints(mols, stream=stream)
    sim = crossTanimotoSimilarity(fps, stream=stream)
stream.synchronize()
print(sim.torch())

Device3DResult

output=CoordinateOutput.DEVICEを指定して呼び出した場合、ETKDGによる埋め込みとMMFF/UFF最適化（ワンショットおよびBatchedForcefield）で使用されます。コンフォーマーをMolオブジェクトに書き戻す処理に相当する、GPU上に配置された結果です。フィールドは次のとおりです。

• values：形状が(total_atoms, 3)のfloat64型AsyncGpuResultです。コンフォーマーの座標をCSR形式のレイアウトで連結したものです。
• atom_starts、mol_indices、conf_indices：レイアウトを示すint32バッファーのAsyncGpuResultです（values[atom_starts[i]:atom_starts[i+1]]は、コンフォーマーiの原子です）。
• energies、converged：MMFF/UFF最小化の場合のみ値が設定されるAsyncGpuResultバッファーです（通常のETKDGでは設定されません）。
• gpu_id：バッファーが配置されているデバイスです。各APIのtargetGpu引数で指定します。targetGpu=-1の場合は、デフォルトの集約デバイスが使用されます。
• .per_molecule()は、コンフォーマーごとのビューを持つネストされたlist[list[torch.Tensor]]を返します。.dense(pad_value=nan)は、パディングされた(n_mols, max_confs, max_atoms, 3)テンソルを生成します。

デフォルトのモード（CoordinateOutput.RDKIT_CONFORMERS）では、最適化された座標が各Molに書き戻され、エネルギーと収束フラグのPythonリストが返されます。後続のGPU処理を連結する場合（例：ETKDG → MMFF → 類似度スコアリングなど）は、ホストとの間でデータをやり取りせずに済むCoordinateOutput.DEVICEを使用してください。

MCSBatchResult

findMCSは同期的に実行され、CPU NumPy配列を基盤とするMCSBatchResultを返します。結果は常にフラットです。result[k]（またはresult.get_result(k)）は、一般には分子kではなく、ペア位置kの結果を具体化します。そのペアを特定するにはresult.pairs[k]を使用してください。all_pairsモードでは、これらはmolsから生成されたペアです。pairsモードでは、指定されたペアの順序がそのまま保持されます。paired_listsモードでは、項目kはmols[k]とmols_b[k]を比較し、result.pairs[k]では結合テーブル内のインデックス(k, len(mols) + k)が使用されます。各MCSResultには、pair、num_atoms、num_bonds、canceled、atom_mapping、bond_mappingがあります。各マッピングの2列は、それぞれ結果ペアの1つ目と2つ目の分子をインデックスします。

設定

ETKDG、力場、部分構造、またはMCSの調整については、詳細設定のリファレンスを参照してください。設定フィールド、デフォルト値、GPUの選択、自動チューニングAPIについて説明しています。

例

Morganフィンガープリント + 一括Tanimoto類似度

import torch
from rdkit import Chem
from nvmolkit.fingerprints import MorganFingerprintGenerator
from nvmolkit.similarity import crossTanimotoSimilarity

smiles = ["CCO", "CCN", "c1ccccc1", "CC(=O)O", "CCOCC"]
mols = [Chem.MolFromSmiles(smi) for smi in smiles]

fpgen = MorganFingerprintGenerator(radius=2, fpSize=1024)
fps = fpgen.GetFingerprints(mols)

sim = crossTanimotoSimilarity(fps)
torch.cuda.synchronize()
print(sim.torch())

入力はlist[Mol]です。GetFingerprintsの出力は、パックされたビットを格納する(n_mols, fpSize / 32)形状のint32テンソルをラップしたAsyncGpuResultです。これをそのままcrossTanimotoSimilarityに渡すと(n, n)の類似度行列が得られます。2つのフィンガープリントセットを渡すと、(n, m)の交差行列が得られます。GPU上にすべてを展開できない大きさのセットには、crossTanimotoSimilarityMemoryConstrainedを使用してください（チャンク単位で計算し、CPU上のnumpyを返します）。

ETKDGによるコンフォーマー埋め込み

from rdkit.Chem import AddHs, MolFromSmiles
from rdkit.Chem.rdDistGeom import ETKDGv3
from nvmolkit.embedMolecules import EmbedMolecules

mols = [AddHs(MolFromSmiles(smi)) for smi in ["C1CCCCC1", "C1CCCCC2CCCCC12", "COO"]]
params = ETKDGv3()

EmbedMolecules(mols, params, confsPerMolecule=10, maxIterations=-1)

for mol in mols:
    print(mol.GetNumConformers())

入力は、水素が追加済み（AddHs）のサニタイズ済みlist[Mol]です。コンフォーマーはインプレースで追加されます。サポートされていない埋め込みオプションについては「制限事項」を参照してください。

コンフォーマーのバッチに対するMMFF94最小化

from rdkit.Chem import AddHs, MolFromSmiles
from rdkit.Chem.rdDistGeom import ETKDGv3
from nvmolkit.embedMolecules import EmbedMolecules
from nvmolkit.mmffOptimization import MMFFOptimizeMoleculesConfs

mols = [AddHs(MolFromSmiles(smi)) for smi in ["CCO", "CCN", "c1ccccc1"]]
params = ETKDGv3()
EmbedMolecules(mols, params, confsPerMolecule=5)

energies = MMFFOptimizeMoleculesConfs(mols, maxIters=500)
for mol, mol_energies in zip(mols, energies):
    print(mol.GetNumConformers(), mol_energies)

入力は、コンフォーマーがすでに設定されているlist[Mol]です（通常はETKDG、RDKitのEmbedMultipleConfs、または以前のnvMolKit呼び出しで生成します）。座標はインプレースで更新されます。戻り値は、入力分子の順序とコンフォーマーのインデックスに対応する、最適化後のエネルギーを格納したlist[list[float]]です。UFFも同じ形式で使用できます。from nvmolkit.uffOptimization import UFFOptimizeMoleculesConfsに置き換えてください。

デフォルトの最小化アルゴリズムはBFGSです。FIREを使用するには、minimizerKind="FIRE"を渡してください。必要に応じて、nvmolkit.types.FireOptionsインスタンスをfireOptions=で指定してカスタマイズできます。ワンショットのMMFF関数とUFF関数、および両方のバッチ力場の.minimize()メソッドで、同じ選択方法を使用できます。

入力分子のいずれかがNoneであるか、MMFF/UFFの原子タイプを持たない場合、呼び出しはValueErrorを発生させます。例外のargs[1]は"none"と"no_params"をキーとする辞書で、問題のあるインデックスを列挙します。ノイズの多い入力セットをフィルタリングする際に便利です。

Conformer RMSD と Butina クラスタリング

import torch
from rdkit import Chem
from rdkit.Chem.rdDistGeom import EmbedMultipleConfs
from nvmolkit.clustering import OutputMode, butina
from nvmolkit.conformerRmsd import GetConformerRMSMatrixBatch

mols = [Chem.AddHs(Chem.MolFromSmiles(smi)) for smi in ["CCCCCC", "c1ccccc1"]]
for mol in mols:
    EmbedMultipleConfs(mol, numConfs=10)

# Remove hydrogens after embedding for heavy-atom RMSD.
heavy_mols = [Chem.RemoveHs(mol) for mol in mols]

# Default RMSD output is RDKit-compatible condensed lower-triangle form.
condensed = GetConformerRMSMatrixBatch(heavy_mols)

# Butina expects a square distance matrix, so request square GPU tensors.
square = GetConformerRMSMatrixBatch(heavy_mols, output_format="square")
results = [
    butina(distance_matrix, cutoff=0.5, output=OutputMode.DEVICE)
    for distance_matrix in square
]

torch.cuda.synchronize()
for result in results:
    print(result.cluster_ids.torch().cpu().tolist())

どちらの Butina 関数も、デフォルトでは GPU 上に結果を返します。

• デフォルトの output=OutputMode.DEVICE は、クラスタ ID、セントロイド、サイズを返します。
• output=OutputMode.RDKIT は、RDKit 形式のクラスタタプルをホスト上に返します。各クラスタの最初の要素がセントロイドです。

デバイス出力の各フィールドは AsyncGpuResult オブジェクトです。ホストへのコピーを行わずに CUDA テンソルへアクセスするには .torch() を使用し、同期してフィールドをホストへコピーするには .numpy() を使用します。

GetConformerRMSMatrix(mol) と GetConformerRMSMatrixBatch(mols) のデフォルトは output_format="condensed" で、長さが N * (N - 1) // 2 の RDKit 形式のフラットベクトルをラップする AsyncGpuResult オブジェクトを返します。butina() や N x N の距離行列を必要とするその他の API へ連携する場合は、output_format="square" を使用してください。どちらの形式も GPU 上にあり、condensed の結果は .numpy() を呼び出すか、square テンソルを CPU へ移動する前に同期してください。

Atom-Atom Path 類似度と有向球排除クラスタリング

有向球排除（DISE）クラスタリングによる Atom-Atom Path（AAP）類似度は、デバイス形式と RDKit 形式の出力モードを提供します。

from rdkit import Chem
from nvmolkit.clustering import OutputMode, fused_dise

molecules = [Chem.MolFromSmiles(smiles) for smiles in ["CCCC", "CCCO", "CCOC"]]
device_result = fused_dise(molecules, 1 - 0.217, metric="aap")
rdkit_clusters = fused_dise(molecules, 1 - 0.217, metric="aap", output=OutputMode.RDKIT)

device_result には cluster_ids、centroids、cluster_sizes の各フィールドがあり、クラスタ ID は 0 始まりで連続しています。OutputMode.RDKIT は、セントロイドを先頭に置く RDKit 形式のクラスタ表現を示すものであり、AAP+DISE アルゴリズムの RDKit 実装を示すものではありません。現在の DISE 制御ループはどちらのモードでも返却前に同期します。DEVICE は安定したスキーマと結果の格納先を示すものであり、呼び出し全体が非同期に実行されることを意味しません。

最大共通部分構造検索

from rdkit import Chem
from nvmolkit.mcs import findMCS

mols = [Chem.MolFromSmiles(smi) for smi in ["CCO", "CCN", "c1ccccc1O"]]
result = findMCS(mols, mode="pairs", pairs=[(0, 1), (0, 2)])

for pair_idx, pair in enumerate(result.pairs):
    item = result[pair_idx]
    print(pair, item.num_atoms, item.num_bonds, item.atom_mapping)

デフォルトの mode="all_pairs" は、対角成分を含む上三角行列を生成します。mode="pairs" は、重複や順序を逆にしたペアを含め、明示的なペアリストをそのまま保持します。mode="paired_lists" は、mols と同じサイズの mols_b をペアにします。タイムアウトはペアごとに設定されます。タイムアウトした結果には、見つかった最良の部分 MCS が含まれている場合があるため、item.canceled を確認してください。

マッチングオプションには、atom_compare、bond_compare、原子価／形式電荷の照合、原子／結合の環のみを対象とする照合が含まれます。サポートされていない RDKit fMCS オプションは、セマンティクスを黙って変更するのではなく、エラーになります。代表的な明示的ペアのワークロードを繰り返し実行する場合、nvmolkit.autotune.tune_mcs は TuneResult を返します。その best_config は、findMCS(..., config=result.best_config) に渡す調整済みの MCSConfig です。

カスタム forcefield オプションと制約（BatchedForcefield）

分子ごとの forcefield 設定、幾何学的制約、またはエネルギーと勾配を個別に呼び出す方法については、 高度な forcefield レシピを参照してください。

トラブルシューティング

症状	考えられる原因	対処方法
torch.cuda.is_available() が false	GPU アクセス、ドライバーとの互換性、または torch の CUDA ビルドがない	GPU とドライバーを確認し、上記のインストール手順に従って互換性のある torch ビルドを選択してください。
RuntimeError: invalid device ordinal	指定した gpuIds のエントリが認識されていない	torch.cuda.device_count() 未満のデバイスインデックス、または API に記載された GPU のデフォルト値を使用してください。
RDKit オプションが拒否される	そのオプションは nvMolKit API でサポートされていない	要求された動作を維持できる場合に限り、サポートされているオプションを使用してください。それ以外の場合は、その処理に RDKit を使用してください。

詳しく知る

• 機能一覧、API リファレンス、ガイド：https://nvidia-bionemo.github.io/nvMolKit/
• 各リリースでの変更点：https://nvidia-bionemo.github.io/nvMolKit/changelog.html
• 実際の使用例（Jupyter ノートブック）：GitHub リポジトリのexamples/ ディレクトリ