docs

LBM流体解析ツールVirtualFluidsの活用【01:Docker導入方法と動作確認】 この文書では、WSL2のDocker上でLBM（格子ボルツマン法）流体解析ツールVirtualFluidsを活用する方法を紹介します。 VirtualFluidsは、ドイツのブラウンシュヴァイク工科大学（iRMB）で開発されている、格子ボルツマン法（LBM）をベースにしたオープンソースの流体解析（CFD）ソフトウェアコードです。従来のナビ・ストークス方程式を直接解く手法とは異なり、微視的な粒子集団の「衝突」と「移動」に基づくメソスケールのアプローチを採用しています。 最大の技術的特徴として、計算の大部分が局所的なグリッド間で完結するLBMの特性を活かしたGPUやマルチコア環境における超並列・HPC（ハイパフォーマンスコンピューティング）への高度な最適化が挙げられ、分散型の前処理・後処理機能と組み合わせることで100億を超える自由度（DOFs）を持つ大規模かつ高解像度なシミュレーションを実行可能です。 さらに、複雑なCAD形状や入り組んだ境界に対してもデカルトグリッドベースで高精度な境界条件処理を行えるほか、乱流や多相流などの複雑な物理現象を組み込んだシミュレーションにも幅広く対応しており、最先端の研究開発やエンジニアリングにおいて高効率で高精度な数値解析を実現する強力な解析ツールとなっています。 VirtualFluids公式サイト：irmb.gitlab-pages.rz.tu-bs.de VirtualFluids公式GitHubリポジトリ なお、VirtualFluidsに関する技術的な詳細を記述した論文が、以下で公開されています。 「VirtualFluids – open source parallel LBM solver」 sciencedirect.com VirtualFluidsの重要機能の解説 VirtualFluids は、ドイツのブラウンシュヴァイク工科大学（TU Braunschweig）などで開発されている、格子ボルツマン法（LBM）を用いたオープンソースの流体解析ソフトウェアです。GPUやCPUによる並列計算に対応し、複雑な流れや大規模な乱流解析を効率的に実行することを目的としています。以下に、主要な機能を技術的な内容と用途を含めて整理します。 - 格子ボルツマン法（Lattice Boltzmann Method：LBM）： VirtualFluidsは、流体を多数の仮想粒子の運動として表現する格子ボルツマン法を採用しています。各格子点における粒子の分布関数を時間発展させることで、流体の速度や圧力などを計算します。従来の有限体積法などとは異なり、分布関数の衝突（Collision）と伝播（Streaming）を繰り返すことで流れを解析します。LBMは局所的な計算を中心とするため、GPUの並列処理と相性がよく、大規模な3次元流体解析に適しています。 - Cumulant衝突モデル： VirtualFluidsは、従来のBGKモデルに加えて、Cumulant（キュムラント）に基づく衝突モデルを利用できます。Cumulantモデルは、分布関数をキュムラント空間に変換して衝突計算を行う手法であり、各次数のキュムラントを適切に緩和させます。通常のBGKモデルでは、すべての非保存モーメントを基本的に同じ緩和時間で扱いますが、Cumulantモデルでは異なる成分の緩和を制御できます。これにより、数値安定性の向上や高Reynolds数流れへの適用が期待できます。 - GPU計算（CUDA）： NVIDIA CUDAを利用して、GPU上でLBMの衝突・伝播処理を並列実行できます。LBMでは各格子点で比較的独立した計算を行うため、GPUの多数の演算コアを活用しやすい特徴があります。CPUと比較して、大規模な格子を使用する流体解析の計算時間を短縮できる可能性があります。特に、複雑な3次元流れや乱流解析など、膨大な格子点を扱う問題で有効です。 - マルチGPU・MPI並列計算： VirtualFluidsは、複数GPUや複数計算ノードを利用する大規模並列計算に対応しています。計算領域を複数の領域に分割し、それぞれのGPUやCPUに担当させることで、計算負荷を分散します。領域境界では、隣接する計算領域間で分布関数などの情報を交換します。MPI（Message Passing Interface）を利用することで、複数の計算ノードを接続した並列解析環境を構築できます。単一GPUのメモリ容量を超えるような大規模解析にも応用できます。 - マルチスケール格子・格子細分化（Grid Refinement）： VirtualFluidsは、計算領域のすべてを同じ格子幅で分割するのではなく、必要に応じて異なる解像度の格子を配置する機能を備えています。例えば、物体周辺や境界層、渦が発生する領域には細かい格子を配置し、流れが比較的単純な領域には粗い格子を使用します。これにより、全領域を細かい格子で計算する場合と比較して、計算格子数やメモリ使用量を削減しながら、重要な領域の解析精度を確保することを目指します。異なる解像度の格子間では、物理量や分布関数の補間・交換処理が必要になります。 - 乱流解析（Turbulence Modeling）： VirtualFluidsでは、乱流を扱うための計算機能が用意されています。乱流は大小さまざまな渦が時間的・空間的に変化する現象であり、十分な解析精度を確保するには細かな空間解像度と時間解像度が必要です。乱流モデルを利用する場合には、未解像の小さな渦の影響をモデル化して、計算負荷を抑えながら乱流の特徴を再現します。特にLES（Large Eddy Simulation）などのアプローチは、建築物周辺の風環境、自動車周辺の流れ、複雑な流路の流動解析などへの応用が考えられます。 - 境界条件（Boundary Conditions）： VirtualFluidsは、固体壁や流入口、流出口などの境界条件を設定して流体解析を行います。例えば、No-slip条件では壁面で流体速度を壁面速度と一致させ、Velocity条件では流入口などに指定した速度を与えます。Pressure条件では圧力に関する境界条件を設定し、Outflow条件では流体が計算領域から自然に流出するように処理します。これらの境界条件を適切に設定することで、実際の流路や物体周辺の流れを再現できます。 - 移流拡散・熱輸送解析（Advection-Diffusion）： 流体の速度場だけでなく、温度や濃度などのスカラー量が流れによって移動・拡散する現象を扱う機能があります。例えば、空気の流れに伴う温度分布の変化や、流路内の物質濃度の輸送などを解析できます。流体の移動による移流と、温度差・濃度差による拡散を組み合わせて計算することで、流れと熱・物質輸送を関連付けた解析に利用できます。 - 多成分流体解析（Multicomponent Flow）： 複数の流体成分が存在する系を扱うための解析機能です。例えば、異なる流体の混合や、複数の成分が共存する流れなどへの応用が考えられます。単一成分の流体解析とは異なり、各成分の濃度や相互作用を考慮する必要があります。混合現象や成分輸送を扱う研究に利用できる機能です。 - 複雑形状・物体周辺の流れ解析： VirtualFluidsは、複雑な形状を持つ物体や流路を対象とした流体解析に対応しています。計算格子と物体表面の位置関係に基づいて境界処理を行い、物体表面での流速条件を表現します。自動車周辺の空気抵抗、建築物周辺の風の流れ、機械内部の流路など、単純な直方体領域では表現できない形状を対象とする解析に応用できます。 - 解析結果の出力と可視化： 解析結果をVTKなどの可視化形式で出力し、速度、圧力、渦構造などの空間分布を確認できます。また、時間ステップごとの結果を保存することで、流れの時間変化や渦の発生・消滅を観察できます。出力したデータはParaViewなどの可視化ソフトウェアで読み込み、断面表示、流線、等値面、ベクトル表示などを利用して解析結果を評価できます。 - Python連携（pyfluids）： VirtualFluidsは、Pythonバインディングを通じてC++で実装された解析機能をPythonから利用できます。これにより、解析条件の設定、計算処理の呼び出し、解析データの後処理などをPythonで扱うことができます。NumPyやMatplotlibなどのPythonライブラリと組み合わせることで、解析結果の統計処理、グラフ化、パラメータスタディなどを実施できます。また、機械学習による流体解析の高速化や、解析結果を利用したデータ駆動型モデルの構築にも応用できます。 VirtualFluidsの技術的な位置付け | 技術分野 | 主な機能 | 期待される効果 | | ------ | --------------- | ----------- | | LBM | 分布関数による流体解析 | 局所的な並列計算 | | 衝突モデル | BGK、Cumulantなど | 数値安定性の向上 | | GPU計算 | CUDA | 計算の高速化 | | 並列計算 | MPI、マルチGPU | 大規模解析 | | 格子制御 | Grid Refinement | 計算効率と解像度の両立 | | 乱流解析 | LESなど | 非定常乱流の再現 | | 物理現象 | 移流拡散・多成分流れ | 熱・物質輸送への応用 | | Python | pyfluids | 解析自動化・AI連携 | | 可視化 | VTK、ParaView | 解析結果の評価 | 総括すると、VirtualFluidsの大きな特徴は、Cumulant LBMによる数値安定性、GPU・MPIによる大規模並列計算、マルチスケール格子による計算効率の向上を組み合わせられることです。特に、建築物周辺の風環境解析や自動車周辺の空力解析など、複雑な3次元形状と非定常乱流を扱う研究に注目できるソフトウェアです。 ※各機能の実装状況や利用可能なモデルは、VirtualFluidsのバージョンやビルド設定によって異なります。実際の研究で使用する場合は、公式ソースコードと各モデルの実装を確認する必要があります。 VirtualFluidsを活用する計算機環境 VirtualFluidsを利用するためには、以下の「Documentation / Getting Started」を見ると「We recommend using VirtualFluids with Docker：VirtualFluidsはDockerを用いた活用を推奨」とあります。 irmb.gitlab-pages.rz.tu-bs.de そこで、以下の「Getting Started with Docker」の手順を確認します。 irmb.gitlab-pages.rz.tu-bs.de 対応プラットフォームと開発環境 VirtualFluidsは、主に WindowsとLinux の2つのプラットフォームに対応しています。本記事では、Windows11, WSL2, Docker, Visual Studio Code（VS Code）、ターミナル、UbuntuのDockerイメージを組み合わせた開発環境を使用します。この構成を採用する理由は、WindowsとLinuxの両方で共通の開発環境を構築できるためです。また、Dockerを利用することで、開発に必要なソフトウェアを個別にインストールする手間を大幅に削減できます。 使用するUbuntuのDockerイメージには、以下の開発ツールがあらかじめ含まれています。 　コンパイラ　CMake（ビルド管理ツール）　MPI（分散メモリ並列計算） 　OpenMP（共有メモリ並列計算）　Clang-Format（C++ソースコードの整形ツール） このほか、開発に必要な各種ツールも用意されています。 重要な注意点： Docker環境でVirtualFluidsのGPU計算機能を利用する場合は、Windows 11以上が必要です。これは、Windows上のDockerからGPUを利用するための環境要件に関係しています。 要するに、 VirtualFluidsでは、VS CodeとUbuntuベースのDockerを組み合わせることで、OSによる環境の違いを抑え、必要な開発ツールをまとめて利用できる環境を構築できます。またGPUを利用するWindows環境では、Windows 11が必須条件となります。 Windows+DockerでGPUを使う方法 Windows 11でDockerのGPU利用にWSL2が必要な理由 結論からいうと、Windows版Docker Desktopは、Linuxコンテナを動かすためにLinuxカーネルを必要とするためです。Windows 11では、そのLinuxカーネルを提供する役割をWSL2が担っています。特にVirtualFluids、XLB、NVIDIA WarpのようなCUDAを利用する科学技術計算では、この仕組みが重要になります。 【WindowsとLinuxの違い】 まず、Dockerコンテナの仕組みを理解すると分かりやすくなります。Dockerコンテナは、独立した小さなOSのように見えますが、実際にはホスト側のカーネル機能を利用します。例えば、VirtualFluidsのDockerイメージがUbuntuベースの場合、コンテナ内ではLinuxのカーネル機能が必要です。 WSL2を使わないWindows環境：　 Windows 11：Windowsカーネル → Linuxコンテナとはカーネルが異なる → Linuxコンテナ：Linuxカーネルが必要 WSL2を利用するWindows環境： Windows 11：Windowsカーネル → WSL2：Linuxカーネルを提供する軽量VM環境 → Docker Linuxコンテナ：Ubuntu、CUDA、VirtualFluidsなど つまり、WSL2はWindows上でLinux環境（GPUを活用する）を提供する基盤です。 【GPUを利用する場合の仕組み】 GPUの場合は、さらに一段階あります。Windows 11では、NVIDIAのGPUドライバがGPUを管理します。WSL2は、そのGPU機能をLinux側に公開します。そのため、LinuxコンテナからもGPUを利用できます。 ■ NVIDIA GPU：RTX A4500など ⇅ Windows NVIDIA Driver：GPUを管理するドライバ ⇅ WSL2 GPU連携：/dev/dxg、CUDA連携ライブラリ ⇅ Docker Linux Container：NVIDIA Container RuntimeによるGPU公開 ⇅ CUDAアプリケーション：VirtualFluids / XLB / NVIDIA Warp GPU計算の命令は、最終的にWindows側のNVIDIAドライバを通じて実際のGPUに送られます。ここで重要なのは、WSL2の中にWindows用とは別のNVIDIAディスプレイドライバをインストールする必要はないということです。基本的にはWindows側の対応ドライバを使用します。 【なぜWindowsのDockerだけではGPUを使えないのか？】 ここは少し注意が必要です。Docker Desktopには複数の実行方式があります。 | Dockerの実行方式 | Linuxコンテナ | NVIDIA CUDA GPU | | ------------------ | ------------- | ------------------------------------ | | WSL2バックエンド | ○ | ○ | | Hyper-Vバックエンド | ○ | Docker DesktopのLinuxコンテナGPUパススルーは非対応 | | Windowsコンテナ | ×（Linux用ではない） | Linux CUDAコンテナとは別方式 | Docker公式も以下の資料では、Windows上で --gpus を使ってLinuxコンテナにGPUを渡す機能は、WSL2バックエンドで利用可能と説明しています。したがって、VirtualFluidsのようなLinuxベースのCUDAアプリケーションでは、WSL2バックエンドを選ぶのが適切です。 「GPU support in Docker Desktop for Windows」 docs.docker.com 【WSL2を使うメリット】 研究・教育で利用する場合、次のメリットがあります。一方、WSL2にはCUDAの一部機能に制約があります。例えばUnified Memoryの完全な機能や、一部のGPUデバッグ・プロファイリング機能には制限があります。 | 項目 | メリット | | ------- | ----------------------- | | Linux環境 | Ubuntuのコマンドやライブラリを利用できる | | GPU | NVIDIA CUDAを利用できる | | Docker | Linuxコンテナをそのまま実行できる | | Python | Linux版Python環境を利用できる | | C++ | GCC、CMakeなどを利用できる | | 再現性 | Dockerイメージで環境を共有できる | 【今回のVirtualFluidsに適した構成】 これまでのXLBやWarpの利用環境と比較すると、次の構成が扱いやすいと思います。なお、WSL2はDocker Desktop専用ではありません。WSL2のUbuntuにDocker Engineを直接インストールして使う方法もあります。 | ソフトウェア | 役割 | | ----------------- | -------------- | | Windows 11 | ホストOS | | NVIDIA Driver | GPU管理 | | WSL2 Ubuntu 24.04 | Linux環境 | | Docker Desktop | コンテナ管理 | | CUDA | GPU計算 | | VirtualFluids | 流体解析 | | pyfluids | Pythonインターフェース | | ParaView | 解析結果の可視化 | 本検証でのおすすめは、「Windows 11 + WSL2/Ubuntu 24.04 + Docker Desktop + GPU対応VirtualFluids」 です。 これならWindows側でParaViewやVS Codeを使いながら、Linux側でC++・CUDA・Pythonの解析環境を管理できます。 改めて今回構築する環境は以下の通りです。 - OS：Windows 11 - GPU：GeForce RTX 3070 Ti - コンテナ：UbuntuベースのVirtualFluids公式Docker環境 - 開発環境：Docker Desktop + WSL2 + Ubuntu - 計算：NVIDIA GPUを利用するCUDA版VirtualFluids - Python：後半でPythonバインディングの利用を確認 RTX 3070 TiはAmpere世代で、CUDAのCompute Capabilityは 8.6 です。GPU向けにソースからビルドする場合、この値をビルド設定に指定するのが基本です。 参考になる公式資料： - Docker：WindowsでのGPUサポート - Microsoft：WSL2でNVIDIA CUDAを有効にする - NVIDIA：CUDA on WSL User Guide - Docker：WSL2バックエンドの説明 動作環境Ubuntu-24.04-VFluidsの準備 ここでは、「WSL2上のUbuntu24.04LTS」を用いることにして、VirtualFluids用のDocker環境を作ることにします。初めて取り組む方は、以下の手順でWSL2上にUbuntu24.04を、導入してください。 qiita.com WSL2上に複数のUbuntu24.04を利用する場合には、基盤となるUbuntuを導入して、これをexportしてから、目的の環境としてimportします。具体的な以下の手順で行います。環境名としては「Ubuntu-24.04-VFluids」とします。 qiita.com PowerShell 7.6.8 PS C:\Users\ryos> wsl --import Ubuntu-24.04-VFluids .\WSL2VM\Ubuntu-24.04-VFluids .\Ubuntu-24.04-Base.tar [======================== 41.6% ] ↓ この操作を正しく終了しました。 PS C:\Users\ryos> wsl -l -v NAME STATE VERSION * Ubuntu-24.04 Stopped 2 Ubuntu-24.04-VFluids Stopped 2 この導入で、作成したUbuntu-24.04-VFluidsを起動したとき、プロンプトが＃でroot環境の時には、先のQiitaに示した手順で、一般ユーザー（ここではryos）にしておきます。 Ubuntu環境を起動して、最新「Ubuntu 24.04.5 LTS」に更新しておきます。 PS C:\Users\ryos> wsl -d Ubuntu-24.04-VFluids dalab@dalab2312nb01:/mnt/c/Users/ryos$ cd dalab@dalab2312nb01:~$ sudo apt update [sudo] password for dalab: ： dalab@dalab2312nb01:~$ sudo apt upgrade ： dalab@dalab2312nb01:~$ lsb_release -a No LSB modules are available. Distributor ID: Ubuntu Description: Ubuntu 24.04.5 LTS Release: 24.04 Codename: noble NVIDIA GPUドライバの確認、Windowsに導入したNVIDIA Driverが、PowerShellとUbunutで認識されているか、確認します PS C:\Users\ryos> nvidia-smi.exe Sat Oct 24 20:43:20 2026 +-----------------------------------------------------------------------------------------+ | NVIDIA-SMI 595.97 Driver Version: 595.97 CUDA Version: 13.2 | +-----------------------------------------+------------------------+----------------------+ ： dalab@dalab2312nb01:~$ nvidia-smi Sat Oct 24 20:43:44 2026 +-----------------------------------------------------------------------------------------+ | NVIDIA-SMI 595.58.02 Driver Version: 595.97 CUDA Version: 13.2 | +-----------------------------------------+------------------------+----------------------+ | GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC | ： Docker Desktop for Windowsの導入 ここでは、WSLのUbuntuからDockerを利用しますが、ここでは「Docker Desktop for Windows」を、Windowsに導入します。WindowsのWebブラウザで以下の公式サイトに接続します docker.com 左上の青色リンク「Download Docker Desktop」の「Download for Windows - AMD64」に進みます。 ダウンロードフォルダに、ファイル「Docker Desktop Installer.exe(612MB)」が保存されます。 このインストーラーをダブルクリックして、以下の設定でインストールします。 ・Configuration：Per-user installation を選択します。WSL2 backendを用いる場合はこちらが必要です。[OK]で進む。 ・Docker Desktop 4.963：ダウンロードとインストールが進む。完了したら、[Close]で終わる。 Windowsの「Docker Desktop」をスタートメニューなどから起動します。 ・「Docker Subscription Service Agreement」をよく読んで、[Accept]で進む。 ・「Welcome to Docker」でユーザー登録をします。「Work・Personal」で選択できますし、右上[Skip]も可能です。 ・上部の歯車の「Settings」に進みます。右側メニューの「General」に進み、「Choose how to run Docker containers」で、「WSL 2」を確認します。 ・左側メニューの「Resources」の「WSL Integration」タブに進み、「Enable integration with additional distros」において、Dockerを利用するWSLの「Ubuntu-24.04-VFluids」を選択し、[Apply Restart Engine]で進む。 ・「docker desktop」のツールは、起動した状態で以下の作業を行います。 利用するWSLの「Ubuntu-24.04-VFluids」において、dockerコマンドの利用を確認します。 dalab@dalab2312nb01:~$ docker --version Docker version 29.9.2, build a82e528 dalab@dalab2312nb01:~$ docker info Client: Version: 29.9.2 Context: default Debug Mode: false ： 両方とも正常に実行できれば、Dockerの基本環境は準備できています。WindowsではDocker DesktopのWSL2バックエンドを利用するのが、公式ガイドに沿った構成です。 DockerからGPUが使えるか確認 VirtualFluidsのインストールに進む前の確認手順として、汎用CUDAコンテナでGPUを確認します。Ubuntuのターミナルで実行してください。 dalab@dalab2312nb01:~$ sudo docker run --rm --gpus all \ nvidia/cuda:12.8.1-base-ubuntu24.04 \ nvidia-smi [sudo] password for dalab: Unable to find image 'nvidia/cuda:12.8.1-base-ubuntu24.04' locally 12.8.1-base-ubuntu24.04: Pulling from nvidia/cuda 73389fbd088f: Pull complete a102f36d092c: Pull complete 05ec76e31584: Pull complete 398182656c47: Pull complete 5a7813e071bf: Pull complete Digest: sha256:133c78a0575303be34164d0b90137a042172bdf60696af01a3c424ab402d86e2 Status: Downloaded newer image for nvidia/cuda:12.8.1-base-ubuntu24.04 Sat Oct 24 18:59:45 2026 +-----------------------------------------------------------------------------------------+ | NVIDIA-SMI 595.58.02 Driver Version: 595.97 CUDA Version: 13.2 | +-----------------------------------------+------------------------+----------------------+ | GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC | | Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. | | | | MIG M. | |=========================================+========================+======================| | 0 NVIDIA GeForce RTX 3070 ... On | 00000000:01:00.0 Off | N/A | | N/A 51C P0 24W / 85W | 0MiB / 8192MiB | 0% Default | | | | N/A | +-----------------------------------------+------------------------+----------------------+ +-----------------------------------------------------------------------------------------+ | Processes: | | GPU GI CI PID Type Process name GPU Memory | | ID ID Usage | |=========================================================================================| | No running processes found | +-----------------------------------------------------------------------------------------+ この確認用コンテナは、VirtualFluids本体とは別のものです。初回はイメージのダウンロードが発生します。成功すると、コンテナ内でGPU名やドライバ情報が表示されます。これでDockerからGPUが見えていることを確認できます。 もし失敗した場合は、そこで止めてください。VirtualFluidsのビルドより先にGPU連携を直す必要があります。 VirtualFluidsのソースコードを取得する まず、WSL2の「Ubuntu-24.04-VFluids」を起動して、ターミナルを開きます。ソースコードはWindows側の C:\ ではなく、WSL2のLinuxファイルシステム内に置くことをお勧めします。 Dockerとのファイル共有やビルド時の性能面で有利です。公式チュートリアルも、Gitでソースコードを取得してDockerコンテナ内で開発する手順を案内しています。 Dockerコンテナを使用してVirtualFluidsの環境を構築しますが、改めて目標となる構成は、次のとおりです。 ・Windows 11：NVIDIA Driver / Docker Desktop ・WSL2 Ubuntu 24.04：Git / Docker CLI ・Dockerコンテナ：Ubuntu / CUDA / CMake / MPI ・VirtualFluids：GPU計算：RTX 3070 Ti（Compute Capability 8.6） 以下では、公式リポジトリのDocker開発環境を利用する方法を優先します。独自にCUDA環境を組み立てるよりも、VirtualFluidsが想定するコンパイラやMPIなどの依存関係を揃えやすいためです。 作業ディレクトリ「~/VFluidsWork」を作成し、gitコマンドで公式リポジトリ「git.rz.tu-bs.de WSL2 Ubuntuで作業ディレクトリを作る dalab@dalab2312nb01:~$ cd ~ dalab@dalab2312nb01:~$ ls dalab@dalab2312nb01:~$ mkdir ~/VFluidsWork dalab@dalab2312nb01:~$ cd ~/VFluidsWork/ VirtualFluidsのソースコードをダウンロードする 以下のコマンドでリポジトリから入手するのですが、なぜか入手終了までに相当に時間がかかります。 git clone https://git.rz.tu-bs.de/irmb/virtualfluids.git もしGitLab側のリポジトリに接続できない場合や時間がかかって終了しない場合は、公開されているGitHubミラーを使う方法もあります。 公式のDockerチュートリアルも、このGitLabリポジトリからの取得を案内しています。入手が完了したら、ソースコードの場所へ移動して内容を確認します。 dalab@dalab2312nb01:~/VFluidsWork$ git clone https://github.com/irmb/virtualfluids.git Cloning into 'virtualfluids'... remote: Enumerating objects: 92832, done. remote: Counting objects: 100% (13409/13409), done. remote: Compressing objects: 100% (6054/6054), done. remote: Total 92832 (delta 8198), reused 12013 (delta 7175), pack-reused 79423 (from 1) Receiving objects: 100% (92832/92832), 71.50 MiB | 1.48 MiB/s, done. Resolving deltas: 100% (66591/66591), done. dalab@dalab2312nb01:~/VFluidsWork$ ls virtualfluids dalab@dalab2312nb01:~/VFluidsWork$ cd virtualfluids/ dalab@dalab2312nb01:~/VFluidsWork/virtualfluids$ ls 3rdParty CMakePresets.json.license THIRD_PARTY_NOTICES.md sonar-project.properties AUTHORS.md COPYING.txt apps src CHANGELOG.md Containers cpu.cmake tests CITATION.cff Contributing.md docs utilities CMake LICENSES gpu.cmake CMakeLists.txt Python pyproject.toml CMakePresets.json README.md pythonbindings 開発元のDockerイメージについて ここで開発元のDockerイメージを利用する手順が、以下の公式ウエブに記述されています。 irmb.gitlab-pages.rz.tu-bs.de しかし、よく読むと次の通りです。「Currently, it is not possible to access the Git server with an SSH key outside the TU Braunschweig network.」つまり、「TU Braunschweigのネットワーク外では、SSH鍵を使ったGitサーバーへのアクセスはできない」という意味です。リポジトリからソースコードは入手できたので、Dockerイメージだけは利用不可になっているようです。 詳しく調べると、ソースコードの取得は、先ほどの git clone で外部ネットワークから成功しています。一方、Dockerイメージを配布しているレジストリのポート4567には接続できていません。したがって、現時点では認証情報やDockerのGPU設定を変更する必要はありません。公式Dockerイメージを取得できないネットワーク環境として、別の方法で構築するのが合理的です。 公開されていませんが、公式Docker環境の構成を調べます。つまり、すぐに別のCUDA環境をゼロから作るよりも、公式Docker環境の構成を調べ、それを再現するDockerfileを作る方法が可能です。 まずは リポジトリから入手したソースコードのなかで、「.devcontainer/devcontainer.json」 の内容を確認してみます。 dalab@dalab2312nb01:~/VFluidsWork/virtualfluids$ ls -la .devcontainer total 12 drwxr-xr-x 2 dalab dalab 4096 Oct 25 05:14 . drwxr-xr-x 16 dalab dalab 4096 Oct 25 05:14 .. -rw-r--r-- 1 dalab dalab 1988 Oct 25 05:14 devcontainer.json dalab@dalab2312nb01:~/VFluidsWork/virtualfluids$ cat .devcontainer/devcontainer.json // SPDX-License-Identifier: CC-BY-4.0 // SPDX-FileCopyrightText: Copyright © VirtualFluids Project contributors, see AUTHORS.md in root folder { "name": "virtual-fluids-environment", ： 実は、VirtualFluidsのリポジトリには、公式Dockerイメージを取得できない場合に利用できるDockerfile「devcontainer.json」が用意されています。特に、今回の devcontainer.json には次の記述があります。 //"image": "git.rz.tu-bs.de:4567/irmb/virtualfluids/ubuntu24_04:1.0", // only accessible from within the tu-bs network "build": { "dockerfile": "../Containers/Ubuntu24_04.Dockerfile", "target": "base" } これは重要な情報です。 - image：TU Braunschweigのネットワーク内でのみ利用できる公式イメージ：現時点ではtu-bsの外部から利用不可 - build：リポジトリ内のDockerfileから自分でイメージを構築する設定 - target: base：Dockerfile内の base ステージを利用する指定 つまり、今回の環境ではGitLab Registryからイメージをダウンロードする必要はありません。公式Dockerfileから直接構築できます。 DcokerfileからVirtualFluidsのDockerイメージを作成する WSL2 Ubuntuのターミナルで、プロジェクトのルートディレクトリ「~/VFluidsWork/virtualfluids」に移動して、次のコマンドで、公式Dockerfileからイメージを構築します。コンテナを作成するために必要な情報のディレクトリ「Containers」の中身を確認します。 dalab@dalab2403sv01:~$ cd ~/VFluidsWork/virtualfluids/ dalab@dalab2403sv01:~/VFluidsWork/virtualfluids$ ls 3rdParty CMakePresets.json.license THIRD_PARTY_NOTICES.md sonar-project.properties AUTHORS.md COPYING.txt apps src CHANGELOG.md Containers cpu.cmake tests CITATION.cff Contributing.md docs utilities CMake LICENSES gpu.cmake CMakeLists.txt Python pyproject.toml CMakePresets.json README.md pythonbindings dalab@dalab2403sv01:~/VFluidsWork/virtualfluids$ cd Containers/ dalab@dalab2403sv01:~/VFluidsWork/virtualfluids/Containers$ ls Ubuntu20_04.Dockerfile Ubuntu22_04.Dockerfile Ubuntu22_04_wiFI.Dockerfile Ubuntu24_04.Dockerfile 今回は、Ubuntu24.04の環境を利用しているので、定義ファイル「Ubuntu24_04.Dockerfile」を了します。実は変更が必要となるので、このファイルを「Ubuntu24_04.Dockerfile.org」にコピーして、元ファイルを修正します。 dala@dalab2403sv01:~/VFluidsWork/virtualfluids/Containers$ cp Ubuntu24_04.Dockerfile Ubuntu24_04.Dockerfile.org dala@dalab2403sv01:~/VFluidsWork/virtualfluids/Containers$ ls Ubuntu20_04.Dockerfile Ubuntu22_04_wiFI.Dockerfile Ubuntu24_04.Dockerfile.org Ubuntu22_04.Dockerfile Ubuntu24_04.Dockerfile 変更点は以下の２つです。viエディタなどで定義ファイル「Ubuntu24_04.Dockerfile」を開いて、該当部分を修正します。 ① apt-get install に doxygen を追加 64行目： flex bison　→　flex bison doxygen ② Doxygenのソースコードをコンパイルする部分を削除 次の2行を削除するか、#でコメントにしてください。 76行目：　RUN wget doxygen.nl && tar -xvf doxygen-1.9.8.src.tar.gz \ 77行目：　 && cd doxygen-1.9.8 && mkdir build && cd build && cmake -G "Unix Makefiles" .. && make -j8 && make install この状態で、修正したDockerfile「Ubuntu24_04.Dockerfile」から、VirtualFluidsのDockerイメージを構築します。プロジェクトのルートディレクトリ「~/VFluidsWork/virtualfluids」に移動して、以下の手順で行います。 dalab@dalab2312nb01:~/VFluidsWork/virtualfluids$ sudo docker build \ --target base \ --build-arg TZ=Asia/Tokyo \ -f Containers/Ubuntu24_04.Dockerfile \ -t virtualfluids:ubuntu24.04 \ . [sudo] password for dalab: [+] Building 542.7s (9/9) FINISHED docker:default => [internal] load build definition from Ubuntu24_04.Dockerfile 0.0s ： 次の手順で、イメージができたか確認します。「virtualfluids:ubuntu24.04」としてできています。 dala@dalab2403sv01:~/VFluidsWork/virtualfluids$ sudo docker images IMAGE ID DISK USAGE CONTENT SIZE EXTRA nvidia/cuda:12.8.1-base-ubuntu24.04 133c78a05753 411MB 101MB virtualfluids:ubuntu24.04 176cfa16f09e 21.1GB 6.98GB VirtualFluidsのDockerイメージを実行する ここまで成功したら、次はGPUを有効にして、以下の手順でコンテナを起動します。このWSLのUbuntuで、dockerコマンドを利用する場合には、Windowsの「docker desktop」を起動した状態にします。 dala@dalab2403sv01:~/VFluidsWork/virtualfluids$ sudo docker run --rm -it \ --gpus all \ --name virtualfluids-gpu \ -e TZ=Asia/Tokyo \ -e HWLOC_COMPONENTS=-gl \ -v "$PWD":/workspace/virtualfluids \ -w /workspace/virtualfluids \ virtualfluids:ubuntu24.04 \ bash ========== == CUDA == ========== CUDA Version 12.9.1 Container image Copyright (c) 2016-2023, NVIDIA CORPORATION & AFFILIATES. All rights reserved. This container image and its contents are governed by the NVIDIA Deep Learning Container License. By pulling and using the container, you accept the terms and conditions of this license: https://developer.nvidia.com/ngc/nvidia-deep-learning-container-license A copy of this license is made available in this container at /NGC-DL-CONTAINER-LICENSE for your convenience. ubuntu@f359122df793:/workspace/virtualfluids$ pwd /workspace/virtualfluids ubuntu@f359122df793:/workspace/virtualfluids$ ls 3rdParty CMakePresets.json.license THIRD_PARTY_NOTICES.md sonar-project.properties AUTHORS.md COPYING.txt apps src CHANGELOG.md Containers cpu.cmake tests CITATION.cff Contributing.md docs utilities CMake LICENSES gpu.cmake CMakeLists.txt Python pyproject.toml CMakePresets.json README.md pythonbindings コンテナ内でGPUと開発環境を確認する コンテナに入ったら、プロンプト「ubuntu@f359122df793」に変わります。以降はコンテナ内で実行します。 【GPU確認】：利用しているGPUが表示されることを確認します。 ubuntu@f359122df793:/workspace/virtualfluids$ nvidia-smi Sun Oct 25 15:06:25 2026 +-----------------------------------------------------------------------------------------+ | NVIDIA-SMI 595.58.02 Driver Version: 595.97 CUDA Version: 13.2 | +-----------------------------------------+------------------------+----------------------+ ： | 0 NVIDIA RTX A4500 On | 00000000:01:00.0 On | Off | ： 【CUDAコンパイラ確認】：nvccの導入を確認します。 ubuntu@f359122df793:/workspace/virtualfluids$ nvcc --version nvcc: NVIDIA (R) Cuda compiler driver Copyright (c) 2005-2025 NVIDIA Corporation Built on Tue_May_27_02:21:03_PDT_2025 Cuda compilation tools, release 12.9, V12.9.86 Build cuda_12.9.r12.9/compiler.36037853_0 【CMake・MPI・C++コンパイラ確認】：ビルドに必要なツールを確認します。 VirtualFluids公式Dockerイメージには、コンパイラ、CMake、MPI、OpenMPなどが含まれると説明されています。 ubuntu@f359122df793:/workspace/virtualfluids$ cmake --version cmake version 3.26.3 CMake suite maintained and supported by Kitware (kitware.com/cmake). ubuntu@f359122df793:/workspace/virtualfluids$ mpic++ --version g++ (Ubuntu 14.2.0-4ubuntu2~24.04.1) 14.2.0 Copyright (C) 2024 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. ubuntu@f359122df793:/workspace/virtualfluids$ g++ --version g++ (Ubuntu 14.2.0-4ubuntu2~24.04.1) 14.2.0 Copyright (C) 2024 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 利用するGPU向けにVirtualFluidsのGPU版をビルドする ここではNVIDIA GPUに対応したビルドが必要です。重要な情報として、NVIDIAの「RTX 3070 Ti・RTX A4500」のCompute Capabilityは 8.6 です。他のGPUの場合も調べてから、作業を進めます。 次は、Dockerコンテナ内で VirtualFluids本体をCUDA対応でコンパイルし、GPU解析を実行する段階です。まず、コンテナ内でVirtualFluidsのソースコードがあるディレクトリに移動します。 最初に、CMakeのプリセットを確認します。 ubuntu@045094eb5860:/workspace/virtualfluids$ cd /workspace/virtualfluids/ ubuntu@045094eb5860:/workspace/virtualfluids$ cmake --list-presets Available configure presets: "make_all" - all make configuration "make_numerical_tests_gpu" - gpu numerical tests make configuration "make_gpu" - make gpu configuration "make_gpu_debug" - make gpu debug configuration "make_cpu" - make cpu configuration "make_cpu_apple" - make cpu configuration (apple clang + homebrew libomp) "make_cpu_debug" - make cpu debug configuration 公式のBuild and Run資料には、GPU専用プリセットとして make_gpu が掲載されています。RTX 3070 TiでGPU解析を行う目的なので、まずは make_all ではなく、GPU専用の make_gpu を使う方針で進めましょう。 まず、CMakeプリセットの設定を確認します。 ubuntu@045094eb5860:/workspace/virtualfluids$ cat CMakePresets.json ： "name": "default", "binaryDir": "build", これより、binaryDir：ビルドファイルの保存先が「build」でした。 まず、GPU用のVirtualFluidsをビルドするためのcmakeの準備します。CUDAのアーキテクチャ指定には、CMake標準の変数名 CMAKE_CUDA_ARCHITECTURES（複数形）を使用します。コンテナ内の /workspace/virtualfluids で実行してください。 ubuntu@045094eb5860:/workspace/virtualfluids$ cmake --preset=make_gpu \ -DCMAKE_CUDA_ARCHITECTURES=86 Preset CMake variables: CMAKE_BUILD_TYPE="Release" VF_ENABLE_ALL_APPS="ON" VF_ENABLE_DOUBLE_ACCURACY="OFF" VF_ENABLE_GPU="ON" ： -- Configuring done (12.0s) -- Generating done (0.1s) -- Build files have been written to: /workspace/virtualfluids/build CMakeの構成が成功したら、実際にコンパイルします。 ubuntu@045094eb5860:/workspace/virtualfluids$ cmake --build --preset=make_gpu -j 8 [ 0%] Building CXX object _deps/spdlog-build/CMakeFiles/spdlog.dir/src/spdlog.cpp.o [ 0%] Building CXX object _deps/spdlog-build/CMakeFiles/spdlog.dir/src/stdout_sinks.cpp.o [ 0%] Building CXX object _deps/spdlog-build/CMakeFiles/spdlog.dir/src/color_sinks.cpp.o ： [100%] Linking CUDA device code CMakeFiles/ResearchCrossingNeighbourhoodGpu.dir/cmake_device_link.o [100%] Linking CXX executable ../../../bin/ResearchCrossingNeighbourhoodGpu [100%] Built target ResearchCrossingNeighbourhoodGpu [100%] Linking CUDA device code CMakeFiles/ActuatorLineDisk.dir/cmake_device_link.o [100%] Linking CXX executable ../../../bin/ActuatorLineDisk [100%] Built target ActuatorLineDisk ここで、-j 8 は8並列でコンパイルする指定です。メモリ不足が発生する場合は -j 4 に変更してください。 以上のように、エラーなくVirtualFluidsのGPU版ビルドが完了したら、実行ファイルを確認します。４つの実行形式が、ディレクトリ「build/bin」に作られています。 ubuntu@045094eb5860:/workspace/virtualfluids$ find build -type f -executable | grep -E 'LidDrivenCavityGPU|DrivenCavity|SphereInChannel|TaylorGreenVortex' build/bin/SphereInChannel build/bin/TaylorGreenVortex build/bin/DrivenCavityMultiGPU build/bin/DrivenCavity ビルドした実行形式でGPU計算を実行する 例題 DrivenCavity ビルド後、実行ファイルを確認します。公式のBuild and Run資料にあるDrivenCavityの実行例は次のとおりです。 irmb.gitlab-pages.rz.tu-bs.de ubuntu@045094eb5860:/workspace/virtualfluids$ pwd /workspace/virtualfluids ubuntu@045094eb5860:/workspace/virtualfluids$ ./build/bin/DrivenCavity \ ./apps/gpu/DrivenCavity/drivencavity_1level.cfg [2026-10-25 20:35:29.052] [trace] Using command line argument for config path: ./apps/gpu/DrivenCavity/drivencavity_1level.cfg [2026-10-25 20:35:29.053] [info] Start initializing level 0 ： [2026-10-25 20:35:34.409] [info] ... finish Running simulation... [2026-10-25 20:35:34.409] [info] Total runtime: 1190 ms [2026-10-25 20:35:34.409] [info] NUPS: 2416676407 (2416.7e6 NUPS) この例では、計算結果は通常 output 以下に保存されます。VTK形式の結果はParaViewでファイル「LidDrivenCavity_bin_ID_0.pvd」で可視化できます。 ubuntu@045094eb5860:/workspace/virtualfluids$ ls 3rdParty CMakePresets.json.license THIRD_PARTY_NOTICES.md output AUTHORS.md COPYING.txt apps pyproject.toml CHANGELOG.md Containers build pythonbindings CITATION.cff Contributing.md cpu.cmake sonar-project.properties CMake LICENSES docs src CMakeLists.txt Python gpu.cmake tests CMakePresets.json README.md logs utilities ubuntu@045094eb5860:/workspace/virtualfluids$ cd output/ ubuntu@045094eb5860:/workspace/virtualfluids/output$ ls DrivenCavity_uniform ubuntu@045094eb5860:/workspace/virtualfluids/output$ cd DrivenCavity_uniform/ ubuntu@045094eb5860:/workspace/virtualfluids/output/DrivenCavity_uniform$ ls LidDrivenCavity.yaml LidDrivenCavity_bin_ID_0_t_9000.vtk.pvtu LidDrivenCavity_bin_ID_0.pvd LidDrivenCavity_bin_lev_0_ID_0_Part_1_t_0.vtk.bin.vtu LidDrivenCavity_bin_ID_0_t_0.vtk.pvtu LidDrivenCavity_bin_lev_0_ID_0_Part_1_t_1000.vtk.bin.vtu LidDrivenCavity_bin_ID_0_t_1000.vtk.pvtu LidDrivenCavity_bin_lev_0_ID_0_Part_1_t_10000.vtk.bin.vtu ： 現在の結果は、最後の段階の速度vx1が以下のようになって、いつも見るCavityの結果に近い形になります。 !image.png 例題 SphereInChannel 次の例題として、SphereInChannelを以下のように実行してみます。 ubuntu@045094eb5860:/workspace/virtualfluids$ pwd /workspace/virtualfluids ubuntu@e84ed3fe8cc6:/workspace/virtualfluids$ ./build/bin/SphereInChannel ./apps/gpu/SphereInChannel/sp here_1level.cfg [2026-10-30 03:35:43.035] [trace] Using command line argument for config path: ./apps/gpu/SphereInChannel/sphere_1level.cfg Reading stl from ./apps/gpu/SphereInChannel/sphere02.stl. [2026-10-30 03:35:43.035] [info] Start reading ascii STL file: ./apps/gpu/SphereInChannel/sphere02.stl [2026-10-30 03:35:43.036] [info] Reading STL-Group Visualization Toolkit generated SLA File as patch 0 ： [2026-10-30 03:35:45.488] [info] GPU Info: [2026-10-30 03:35:45.488] [info] -------------- [2026-10-30 03:35:45.488] [info] name: NVIDIA GeForce RTX 3070 Ti Laptop GPU, compute capability: 8.6 [2026-10-30 03:35:49.670] [info] PID --- Average performance --- Processing time (ms) Nups in Mio Bandwidth in GB/sec [2026-10-30 03:35:49.670] [info] 0 --- Average performance --- 4181.5/ 4181.5 1213.0 135.9 [2026-10-30 03:35:49.670] [info] Write files t = 10000 ... [2026-10-30 03:35:49.788] [info] ... done [2026-10-30 03:35:49.788] [info] 0 --- Average performance --- 0.0/ 4181.5 1213.0 135.9 [2026-10-30 03:35:49.788] [info] ... finish Running simulation... [2026-10-30 03:35:49.788] [info] Total runtime: 4182 ms [2026-10-30 03:35:49.788] [info] NUPS: 1212975990 (1213.0e6 NUPS) この例も、計算結果は output 以下に保存されます。VTK形式の結果はParaViewでファイル「SphereInChannel_bin_ID_0.pvd」で可視化できます。可視化できます。 ubuntu@e84ed3fe8cc6:/workspace/virtualfluids$ cd output/SphereInChannel_1Level/ ubuntu@e84ed3fe8cc6:/workspace/virtualfluids/output/SphereInChannel_1Level$ ls SphereInChannel.yaml SphereInChannel_bin_ID_0.pvd SphereInChannel_bin_ID_0_t_0.vtk.pvtu SphereInChannel_bin_ID_0_t_10000.vtk.pvtu SphereInChannel_bin_lev_0_ID_0_Part_1_t_0.vtk.bin.vtu SphereInChannel_bin_lev_0_ID_0_Part_1_t_10000.vtk.bin.vtu planeProbe_bin_ID_0_t_10000.vtk.pvtu planeProbe_bin_lev_0_ID_0_Part_1_t_10000.vtk.bin.vtu pointProbe_bin_ID_0_t_10000.vtk.pvtu pointProbe_bin_lev_0_ID_0_Part_1_t_10000.vtk.bin.vtu 現在の結果は、最後の段階の速度vx1が以下のようになって、球周りの速度分布が確認できます。 !image.png コンテナを終了・再起動する方法 計算やビルドが終わったら、コンテナ内で次のコマンドを実行します。 exit 今回は --rm を付けて起動しているため、コンテナ自体は終了時に削除されます。ただし、ソースコードとビルド結果はWSL2側に残ります。

The AI agent kill switch is a procedure, not a feature An invoice-processing agent starts submitting the same job repeatedly. You disable its principal. Even if Microsoft Graph now rejects its requests, the agent may still use a provider key, write export files or leave accepted jobs running. Which effects did the kill switch actually stop? The credential operation may have succeeded without containing the workload. > An AI agent kill switch is an operational procedure with a testable outcome. The hypothetical invoice agent has four action paths: Graph access, model access, local writes and submitted jobs. Following those paths exposes the architectural obligation: someone outside the agent must retain the authority and information needed to stop its consequential activity. The stop objective determines the control "Stop" needs a defined outcome. Containment denies specified consequential actions; quiescence additionally requires relevant execution and outstanding work to reach verified terminal states. A paused or queued job is not terminal, and completed work may still have produced effects requiring recovery. The invoice incident requires both: no further submissions or export writes, no remaining agent execution and no unresolved processing jobs. A lower-risk incident might permit isolated computation to continue while denying every forbidden effect. Three artifacts make that objective reviewable. The stop scope identifies effects, execution units and permitted collateral impact. The shutdown protocol assigns independent authority, dependencies and failure handling. The acceptance report records observed coverage, timing and persistence. Build the scope from credentials, reachable destinations, writable resources and submitted work. "All registered paths are closed" is a bounded claim; "the agent cannot cause harm" is not. Every new tool integration should identify both the authority it adds and how that authority will be withdrawn. For the invoice agent, ending model access is not the business objective; preventing further duplicate submissions and export changes is. If queued work needs no further model call, model denial does not end that exposure. Prioritize interventions by the effects that remain possible, not by which administrative action is easiest. Otherwise a convenient control operation quietly becomes the organization's definition of successful containment. Token revocation changes authorization, not execution "Revoke the token" can mean stopping issuance, invalidating a refresh token or access token, or making a resource reject an existing token. RFC 7009 requires refresh-token revocation support, recommends access-token revocation support and acknowledges propagation delay. These are not interchangeable guarantees. A successful revocation response does not prove resource-side rejection. Self-contained tokens can be validated locally; an issuer-side change therefore needs additional resource interaction for immediate enforcement. Waiting for expiry is a different shutdown assumption. Token introspection lets a protected resource ask whether a token is active: { "active": false } That response carries authorization information, not a termination instruction. Cached active responses can preserve a revoked token's usability. Your design must identify participating resources and refresh behavior, not merely name the introspection protocol. Microsoft Entra continuous access evaluation (CAE) improves enforcement for eligible single-tenant service principals calling Microsoft Graph, with clients declaring cp1 and handling claims challenges. Managed identities and third-party or multitenant applications are excluded from that workload CAE scope. For Microsoft Entra Agent ID, verify eligibility rather than assuming ordinary service-principal behavior applies. Assume the invoice agent's participating Graph path is now denied. Model access, local writes and accepted jobs remain. Revocation could suffice where every forbidden effect depends on a current participating-resource decision and no relevant work is already admitted. This architecture does not meet those conditions. <a name='the-gateway-is-a-stop-point-only-when-it-cannot-be-bypassed'></a> Request boundaries must leave no accepted bypass A gateway lets an operator withdraw access without the caller's cooperation. Separating caller and backend authentication also permits targeting one caller without necessarily withdrawing everyone's backend access. That advantage requires mandatory routes. The topology below separates model and tool requests from local execution, because closing one does not establish the state of the others: flowchart LR A["Agent runtime"] --> G["Model gateway"] G --> M["Model"] A --> T["Tool boundary"] T --> S["Downstream systems"] C["Shutdown control"] -. Deny .-> G C -. Deny .-> T C -. Quarantine .-> R["Host and network"] R -. Contains .-> A Backend authorization and network restrictions must prevent bypass. Azure API Management's return-response policy illustrates denial before backend forwarding in an inbound policy: <return-response> <set-status code="403" reason="Forbidden" /> <set-header name="Content-Type" exists-action="override"> <value>application/json</value> </set-header> <set-body>{"error":"agent_execution_disabled"}</set-body> </return-response> The fragment denies every caller reaching its policy scope. Targeting an agent instead requires validated caller claims, not a supplied agent-name header. Distinguish delegated user identity from client identity; shared principals require another trusted discriminator or an explicitly broader shutdown. Shutdown granularity is therefore an architectural choice made before the incident. Sharing an identity may simplify operation while making isolation of one caller harder. And return-response governs the current pipeline, not jobs already admitted elsewhere. <a name='api-keys-make-credential-custody-part-of-containment'></a> Credential custody determines whether denial can be bypassed. If the agent retains a provider key and direct access, an alternative authentication path survives. Keep backend authority outside the runtime: API Management's own managed identity or Docker's supported host-side credential injection can mediate use without exposing that credential to the workload. Credential custody also determines the incident's blast radius. If the backend credential remains under trusted control, denying the affected caller can preserve service for unrelated workloads. If that credential escaped, caller denial no longer covers its possible use elsewhere. The procedure must then address the credential itself, with any broader disruption explicitly accepted rather than hidden behind a claim of per-agent isolation. Credential modernization is not bypass elimination: Azure AI's disableLocalAuth disables key-based authentication, while Anthropic's workload identity federation replaces static keys for the configured flow. Neither alone makes a gateway mandatory. Managed identity likewise does not imply instant token revocation; it is outside workload CAE. For the example, assume accepted bypasses are now closed and model and tool routes deny the caller. Local execution, admitted jobs and replacement remain. <a name='the-host-and-network-remain-enforcement-planes'></a> Local effects require host and network enforcement Start with the forbidden effects, not the preferred sandbox. Network isolation can deny remote submissions while leaving local writes possible. Microsoft Execution Containers (MXC) can contain a tool or an entire agent; choose the unit at which an independent operator can control the relevant effect. Isolation does not remove deliberately granted access. Docker's local sandboxes use lightweight virtual machines, or microVMs, with separate Linux kernels, yet writes through directly mounted workspaces affect host files immediately. The invoice agent's writable export directory is an authorized capability, not an isolation failure. Its withdrawal still needs a control. Likewise, Docker's outbound policy proxy must cover the actual destinations and connection states. MXC's permissive mode records rather than blocks ungranted access; enforcement and learning modes block it. Count only deployed, enforcing interventions, not experimental or forthcoming capabilities. Windows 365 for Agents offers managed Cloud PCs with session orchestration and intervention capabilities. To use that isolation platform in the procedure, identify the assigned session, independent operator, available intervention and collateral impact. Suppose the export process has now stopped. Local writes and new registered requests have ended; jobs accepted by other systems have not necessarily ended with them. <a name='a-shutdown-procedure-needs-independent-authority'></a> Independent authority must keep the stop latched If the supervisor replaces the terminated process, routine recovery defeats containment. The operator stopped an instance, not the logical agent. A durable administrative stop must govern admission, retries and replacement from the start of the incident until independent clearance. The workload cannot authorize its own restart or remove its restrictions. An agent must not be its own security authority, and the controller needs authority and information that survive the target losing access. Connect the logical agent to principals, runtime instances, boundaries and accepted jobs. Validated identity alone does not supply that inventory. Record external job identifiers, owning services and available interventions outside the submitting process so termination does not destroy the means to cancel its work. Independent control does not require one all-powerful credential. Keep intervention privileges at the relevant boundaries, with named owners and a coordinated procedure. The requirement is that each intervention remains available after the target loses access. If stopping the agent also disables the only credential that can inspect or cancel its submitted jobs, the procedure has removed its own ability to finish. Include uncertain submissions. If a service accepted a job but its response was lost, the missing identifier leaves an unresolved obligation. Reconcile the attempt with the owning service; until then, retain an explicit coverage gap. If a downstream service offers no cancellation, independently verified completion may be the only route to quiescence. That waiting time belongs in the stop budget. If the organization cannot tolerate it, constrain what the agent can admit before delegating that capability. During the incident, an uncancellable job remains outstanding work; tracking its identifier does not turn it into a stopped job or remove the need to assess its effects. The protocol follows those dependencies: prevent replacement, close paths, stop execution and reconcile admitted work. Some interventions can run in parallel, but the control planes do not constitute one atomic transaction. Gateway denial can succeed while execution or an external job remains active. Record requested actions separately from observed outcomes. Name an escalation owner and any permitted broader intervention, including its collateral impact. A per-agent failure must not silently become a shared-service shutdown, nor a successful command become a claim that every path is closed. <a name='the-stop-condition-must-be-observable-and-timed'></a> Acceptance requires coverage, timing and persistence A command response is not an acceptance test: RFC 7009 returns HTTP 200 even for an already-invalid token. Use controlled fixtures to verify effects across every in-scope path: | Acceptance test | Required observation | What failure means | |---|---|---| | Replay a pre-incident credential against the participating resource | Forbidden action rejected within the agreed interval | Resource enforcement cannot carry that path's guarantee | | Submit through each denied gateway route | Requests denied before forwarding across serving instances | Route remains open or convergence is unverified | | Attempt each registered direct-provider route | No accepted independent route for the affected workload | Credential custody or backend access permits a bypass | | Continue a harmless local-write fixture and observe the runtime | Writes cease; execution also stops where quiescence is required | Local effects or required execution remain outside stop coverage | | Reconcile accepted jobs against the trusted inventory | Every in-scope job cancelled or independently proven terminal | Admitted work remains active or its outcome is unknown | | Exercise queued retries and replacement instances | No submission-capable replacement before clearance | Instance termination mistaken for a durable agent stop | The following YAML is an example operational contract, not product configuration. Its 15-, 30- and 60-second thresholds are illustrative targets to negotiate and test, not vendor latency guarantees: agent: invoice-reviewer scope: one-agent clock_starts_at: incident_trigger_accepted required_observations: model_tool_and_credential_paths_denied: within_seconds: 15 evidence: independent_authenticated_probes_denied runtime_execution_stopped: within_seconds: 30 evidence: supervisor_confirms_no_agent_execution known_downstream_jobs: within_seconds: 60 evidence: every_job_cancelled_or_proven_terminal restart: automatic: forbidden requires: independent_approval failure: state: containment_incomplete action: escalate_and_keep_stop_latched Choose the time budget from acceptable exposure, not a convenient vendor timeout. Fast denial on one route fails coverage; comprehensive but late denial fails timing. An unavailable enforcement point leaves an unverified path, not a latency to average away. Test the intended denial, not merely a failed request. A controlled action should be known to work before the stop, and its rejection afterward should be attributable to the selected enforcement point. A timeout, malformed credential or unrelated outage cannot establish that the procedure withdrew authority. Capture the trigger, target, observed result and enforcement evidence without copying raw credentials into the report. Test old credentials and cached authorization decisions, not only new tokens. Preserve running work, queued retries and replacement behavior in the fixtures. Verify the execution boundary independently of model access, and reconcile jobs against service-observed outcomes. Suppose gateway denial is verified at eight seconds, runtime termination at 22 and the last job becomes terminal at 41. With all required paths covered, those illustrative observations support a 41-second stop, not an eight-second stop. A submission-capable replacement at 43 seconds invalidates it. Record coverage, completion times, unresolved paths and the observation window. Distinguish cancellation from completion: a terminal job may already have submitted the duplicate, just as host-file writes may already have changed an export. Shutdown ends further activity; it does not certify earlier results. Choose an observation window that exercises the deployment's relevant retry and replacement behavior. A snapshot showing no process at one instant is weaker evidence than a denied restart attempt under the latched stop. The report should say which behaviors were tested and which remain unverified. That preserves the boundary between a demonstrated operational result and an unlimited assurance about future execution. <a name='re-entry-is-a-separate-authorization-decision'></a> Re-entry requires independent clearance Restarting does not establish that the cause changed. Persistent sandbox state and queued work can reproduce the incident. An independent approver must authorize reused state and restored permissions after the cause is addressed. Likewise, returning a Cloud PC to its pool is resource lifecycle, not incident clearance. Choose controls, including resource-enforced revocation, for the authority they remove rather than the length of the security checklist. Delegating work creates an obligation to retain independent withdrawal and account for work already set in motion. For every action that survives the stop command, require an owner, an intervention and evidence of its result. A product name is not that answer. References - OAuth 2.0 token revocation, RFC 7009 - OAuth 2.0 token introspection, RFC 7662 - Continuous access evaluation for workload identities - Authenticate and authorize access to AI APIs in Azure API Management - Azure API Management return-response policy - Secure applications and APIs by validating claims - Microsoft.CognitiveServices accounts resource reference - Microsoft Execution Containers: Policy-driven containment for AI agents - Docker Sandboxes architecture - Docker Sandboxes isolation documentation - What is Windows 365 for Agents? - Anthropic workload identity federation