shou0715-Arthur/pyaedt-hfss-antenna

PyAEDT HFSS Antenna/RF Simulation Skill

What This Skill Solves

It streamlines the process of having an AI agent drive Ansys HFSS for antenna/RF simulations using Python. It provides three things:

1. Environment Handshake Guidance — how to find the local AEDT, use gRPC or COM, and avoid license conflicts
2. Standard Antenna Simulation Pipeline — create project → model → boundaries/excitation → solver setup → sweep → solve → post-processing, with code skeletons ready to copy and adapt
3. Three High-Frequency Task Templates — S-parameter extraction, far-field pattern, and parametric sweep, ready to use as starting points

It does not design the antenna (geometry, feeding method, target frequency band are the user/engineer's job), only smooths the path from "known design" to "simulation results".

When to Trigger

• User says "simulate this antenna with HFSS", "extract S-parameters", "sweep 2-6 GHz", "plot the radiation pattern", "check gain"
• User provides a .aedt/.aedtz/.hfss project and asks to run it automatically or in batch
• User writes code with import ansys.aedt.core / from pyaedt import Hfss
• User asks "how to start HFSS with pyaedt", "why can't connect to AEDT", "license conflict"

Standard Workflow (One Main Flow)

Regardless of the specific task, antenna/RF simulation follows this main flow. Build a mental map along this flow first, then jump to the corresponding template:

[1] Environment Handshake →   Confirm AEDT version + Python version + communication interface
                               See references/environment-setup.md
                               If unsure, run scripts/check_env.py

[2] Create/Open Project   →   Hfss(project=..., design=..., version=..., new_desktop=...)
                               Key: non_graphical=True for CI/batch
                                     new_desktop=False to reuse open desktop
                                     close_on_exit=True to release license after finishing

[3] Geometry Modeling      →   hfss.modeler.create_box / create_cylinder / create_polyline ...
                               Or use hfss.modeler.import_3d_cad("xxx.step")
                               It is recommended to define variables first (see below), then drive geometry with them

[4] Variable Parameterization → hfss[" $patch_w "] = "30mm"  (project variable, with $)
                               hfss["patch_l"]    = "32mm"   (design variable, without $)
                               Make any dimension that might be swept a variable

[5] Boundaries & Excitation → Radiation boundary: hfss.assign_radiation_boundary_to_objects(["AirBox"])
                              Port:   hfss.lumped_port / hfss.wave_port / hfss.create_floquet_port
                              Ground: hfss.assign_perfecte_to_sheets(...)

[6] Solver Setup          →   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] Solve                 →   hfss.analyze(setup="Setup1", cores=8)   # blocking
                              Or hfss.analyze_setup("Setup1")

[8] Post-Processing       →   S-parameters: hfss.post.get_solution_data("S(1,1)")
                              Far-field:   hfss.insert_infinite_sphere(...)
                                            hfss.post.get_far_field_data(...)
                              Export:      data.export_data_to_csv("xxx.csv")

[9] Cleanup               →   hfss.save_project()
                              hfss.release_desktop(close_projects=False, close_desktop=True)
                              Not releasing will occupy the license forever!

How to Use This Skill

When You First Get an Antenna/RF Simulation Task

1. Read references/environment-setup.md first — find out which AEDT version, Python version, and whether pyaedt is installed on the user's machine. If unclear, run scripts/check_env.py.
2. Then read references/antenna-workflow.md — this is the "blown-up" version of the main flow above, with API usage and common parameters for each step.
3. Glance at references/common-pitfalls.md before hitting errors — 80% of "can't connect / can't run / wrong results" are listed there.

When Writing Code

Go to templates/ and pick the one closest to your task, copy the whole template and modify it:

Task Type	Template
Single project, single/multi-frequency S11/S21 sweep extraction	templates/sparam_extraction.py
Far-field pattern, gain, radiation efficiency, 3D polar plot	templates/far_field_pattern.py
Geometry/material parameter sweep, extract multiple result sets	templates/parametric_sweep.py

All templates are independently runnable scripts with parameters like PROJECT_PATH / DESIGN_NAME / FREQ_* exposed at the top. Modify the top section first, then the geometry/boundary parts in the middle.

Key Principles

• Start small, then refine: For the first run of any script, set MaximumPasses to 3-5 and the sweep points to 21. Get the pipeline working first before refining. Going all-in at once wastes hours.
• Always release_desktop: Not releasing the license = error on next launch. Wrap the end of your script in try/finally.
• non_graphical defaults to True: Unless you need to see the geometry or debug, do not open the GUI; saves memory and allows parallel runs.
• Use absolute paths: Relative paths may not resolve to the expected directory inside the AEDT process.
• Prefer variables: Any dimension that "might need changing" should be a variable first, not a hard-coded literal. Otherwise parametric sweeps will require a rewrite.

Installing pyaedt (If Not Already Installed)

# Recommended combination (2025 R2 / 2026 R1)
pip install pyaedt

# Older AEDT with older pyaedt (see references/environment-setup.md for mapping)
pip install pyaedt==0.17.5     # AEDT 2025 R1
pip install pyaedt==0.13.3     # AEDT 2024 R2

Things NOT to Do

• Do not use import pyaedt directly — since 1.0, the official recommendation is import ansys.aedt.core as pyaedt or from ansys.aedt.core import Hfss. Old code with from pyaedt import Hfss still works but is deprecated.
• Do not use new_desktop=True when AEDT GUI is already open — this will start another process, doubling the license usage. To reuse an already open desktop, use new_desktop=False.
• Do not expect native AEDT on macOS — AEDT only runs on Windows/Linux. On macOS, either remote into a Windows machine or use PyEDB for EDB processing, not HFSS.
• Do not skip hfss.save_project() — you must save before release, or the changes won't be found next time.
• Do not deliver results with MaxDeltaS too loose (>0.05) — insufficient convergence means the S11 you see is noise, not physics.

Reference File List

pyaedt-hfss-antenna/
├── SKILL.md                          ← You are reading this
├── references/
│   ├── environment-setup.md          ← Version mapping, installation, gRPC/COM, licensing
│   ├── antenna-workflow.md           ← Detailed API for the main workflow
│   └── common-pitfalls.md            ← Frequent errors and their solutions
├── templates/
│   ├── sparam_extraction.py          ← S-parameter frequency sweep extraction
│   ├── far_field_pattern.py          ← Far-field pattern / gain
│   └── parametric_sweep.py           ← Variable parametric sweep
└── scripts/
    └── check_env.py                  ← Probe local AEDT/Python/pyaedt

Suggested reading order: This file → environment-setup → top explanation of the template → antenna-workflow (refer to it step by step as needed) → common-pitfalls when issues arise.