shou0715-Arthur/pyaedt-hfss-antenna

PyAEDT HFSS アンテナ/RF シミュレーション Skill

この skill が解決する問題

「agent が Python を使って Ansys HFSS を駆動し、アンテナ/RF シミュレーションを実行する」という作業をフロー化します。以下の 3 つを提供します。

1. 環境ハンドシェイクガイド —— ローカルマシンの AEDT を見つける方法、gRPC と COM の使い分け、ライセンス競合の回避
2. 標準アンテナシミュレーションパイプライン —— プロジェクト作成 → モデリング → 境界条件/励振 → ソリューション設定 → 掃引 → ソルバー実行 → 後処理。各ステップでコピー＆改変可能なコードスケルトンを提供
3. 3 つの高頻度タスクテンプレート —— S パラメータ抽出、遠方界パターン、パラメトリック掃引。そのまま始点として使用可能

この skill はアンテナの設計（形状、給電方式、目標周波数帯）は行いません。それはユーザー/エンジニアの仕事です。「既知の設計 → シミュレーション結果を出力する」というパスをスムーズにすることに専念します。

いつトリガーするか

• ユーザーが「このアンテナを HFSS でシミュレーションして」「S パラメータを抽出して」「2–6 GHz で掃引して」「放射パターンをプロットして」「ゲインを見て」と言ったとき
• ユーザーが .aedt/.aedtz/.hfss プロジェクトを提供し、自動実行/バッチ実行を要求したとき
• ユーザーが import ansys.aedt.core / from pyaedt import Hfss というコードを書いたとき
• ユーザーが「pyaedt で HFSS を起動する方法」「AEDT に接続できない」「ライセンスが占有されている」と尋ねたとき

標準ワークフロー（1 本の主線）

具体的なタスクによらず、アンテナ/RF シミュレーションは以下の主線に従います。まずこの線に沿ってマインドマップを構築し、それから対応するテンプレートにジャンプしてください。

[1] 環境ハンドシェイク → AEDT バージョン + Python バージョン + 通信インタフェースの確認
                        参考文献 references/environment-setup.md を参照
                        不明な場合は scripts/check_env.py を実行

[2] プロジェクト作成/オープン → Hfss(project=..., design=..., version=..., new_desktop=...)
                               重要: non_graphical=True は CI/バッチ用
                                      new_desktop=False で既存デスクトップを再利用
                                      close_on_exit=True で終了時にライセンスを解放

[3] ジオメトリモデリング → hfss.modeler.create_box / create_cylinder / create_polyline ...
                          または hfss.modeler.import_3d_cad("xxx.step")
                          まず変数を定義し（下記参照）、その変数でジオメトリを駆動することを推奨

[4] 変数パラメータ化 → hfss[" $patch_w "] = "30mm"  (プロジェクト変数、$ 付き)
                     hfss["patch_l"]    = "32mm"   (設計変数、$ なし)
                     掃引を検討するすべての寸法は変数として作成することを推奨

[5] 境界条件と励振 → 放射境界: hfss.assign_radiation_boundary_to_objects(["AirBox"])
                     ポート:   hfss.lumped_port / hfss.wave_port / hfss.create_floquet_port
                     グランド: hfss.assign_perfecte_to_sheets(...)

[6] ソリューション設定 → setup = hfss.create_setup("Setup1", Frequency="3GHz",
                                                 MaximumPasses=15, MaxDeltaS=0.02)
                        sweep = setup.create_linear_count_sweep(
                            unit="GHz", start_frequency=2, stop_frequency=6,
                            num_of_freq_points=401, sweep_type="Interpolating")

[7] ソルバー実行 → hfss.analyze(setup="Setup1", cores=8)   # ブロッキング
                 または hfss.analyze_setup("Setup1")

[8] 後処理       → S パラメータ: hfss.post.get_solution_data("S(1,1)")
                 遠方界:       hfss.insert_infinite_sphere(...)
                               hfss.post.get_far_field_data(...)
                 エクスポート: data.export_data_to_csv("xxx.csv")

[9] 終了処理     → hfss.save_project()
                  hfss.release_desktop(close_projects=False, close_desktop=True)
                  解放しないとライセンスを占有し続ける!

この skill の使い方

初めてアンテナ/RF シミュレーションタスクを受け取ったとき

1. 最初に references/environment-setup.md を読む —— ユーザーのマシン上で AEDT のバージョン、Python のバージョン、pyaedt をインストールする必要があるかどうかを確認します。不明な場合は scripts/check_env.py を実行します。
2. 次に references/antenna-workflow.md を読む —— 上記の主線を「拡大」したもので、各ステップの API の使い方と一般的なパラメータを提供します。
3. エラーが発生する前に references/common-pitfalls.md に目を通す —— 「接続できない / 実行できない / 結果がおかしい」の 80% がここにリストされています。

コードを書くとき

templates/ からタスクに最も近いテンプレートを選び、セクション全体をコピーしてから編集します。

タスクタイプ	テンプレート
単一プロジェクト、単一/複数周波数 S11/S21 掃引抽出	templates/sparam_extraction.py
遠方界パターン、ゲイン、放射効率、3D パターン	templates/far_field_pattern.py
ジオメトリ/材料パラメータのスイープ、複数結果の抽出	templates/parametric_sweep.py

テンプレートはすべて独立して実行可能なスクリプトで、先頭に PROJECT_PATH / DESIGN_NAME / FREQ_* などのパラメータが統一して公開されています。まず先頭部分を編集し、次にジオメトリ/境界部分を編集します。

重要な原則

• まず小さく、後で大きく: 初めてスクリプトを実行するときは、メッシュの MaximumPasses を 3–5 に、掃引点数を 21 に設定し、まずパイプラインが通ることを確認してから精度を上げてください。最初から高精度を目指すと数時間無駄になります。
• 必ず release_desktop: ライセンスを解放しないと、次回起動時にエラーになります。スクリプトの最後は try/finally で囲んでください。
• non_graphical はデフォルトで True: ジオメトリの確認やデバッグが必要な場合を除き、GUI を開かないでください。メモリを節約でき、並列実行も可能です。
• パスは絶対パスを使用: 相対パスは AEDT プロセス内で期待するディレクトリを指すとは限りません。
• 変数を優先: 「後で変更する可能性がある」寸法はすべて最初に変数として作成し、リテラル値をハードコードしないでください。そうしないと、後でパラメトリック掃引を追加する際に書き直しが必要になります。

pyaedt のインストール（まだの場合）

# 推奨組み合わせ（2025 R2 / 2026 R1）
pip install pyaedt

# 古い AEDT には古い pyaedt（詳細は references/environment-setup.md を参照）
pip install pyaedt==0.17.5     # AEDT 2025 R1
pip install pyaedt==0.13.3     # AEDT 2024 R2

やってはいけないこと

• 直接 import pyaedt しない —— バージョン 1.0 以降、公式推奨は import ansys.aedt.core as pyaedt または from ansys.aedt.core import Hfss です。古い from pyaedt import Hfss はまだ使えますが、非推奨 (deprecated) です。
• GUI で AEDT が既に開いている状態で new_desktop=True を使用しない —— 別プロセスが起動し、ライセンスが 2 倍消費されます。既存デスクトップを再利用するには new_desktop=False を使用します。
• Mac でネイティブ AEDT を期待しない —— AEDT は Windows/Linux でのみ動作します。Mac の場合は、Windows にリモート接続するか、HFSS の代わりに PyEDB を使用して EDB を処理します。
• hfss.save_project() を省略しない —— release の前に必ず save してください。そうしないと、次回開いたときに変更が反映されていません。
• MaxDeltaS を緩すぎる（>0.05）値のままで結果を提供しない —— 収束が不十分だと、表示される S11 は物理的な値ではなくノイズです。

参考ファイル一覧

pyaedt-hfss-antenna/
├── SKILL.md                          ← このファイル
├── references/
│   ├── environment-setup.md          ← バージョン対応表、インストール、gRPC/COM、ライセンス
│   ├── antenna-workflow.md           ← メインワークフローの API 詳細
│   └── common-pitfalls.md            ← よくあるエラーと対処法
├── templates/
│   ├── sparam_extraction.py          ← S パラメータ掃引抽出
│   ├── far_field_pattern.py          ← 遠方界パターン/ゲイン
│   └── parametric_sweep.py           ← 変数パラメトリック掃引
└── scripts/
    └── check_env.py                  ← ローカルの AEDT/Python/pyaedt を検出

推奨読み順: 本ファイル → environment-setup.md → テンプレートの先頭説明 → antenna-workflow.md（必要なステップだけ参照）→ 問題発生時は common-pitfalls.md を確認。