shou0715-Arthur/pyaedt-hfss-antenna

PyAEDT HFSS 안테나/RF 시뮬레이션 Skill

이 Skill이 해결하는 문제

"에이전트가 Python으로 Ansys HFSS를 구동하여 안테나/RF 시뮬레이션을 수행"하는 과정을 표준화합니다. 다음 세 가지를 제공합니다:

1. 환경 설정 가이드 — 로컬 AEDT 찾는 법, gRPC/COM 사용, 라이선스 충돌 방지
2. 표준 안테나 시뮬레이션 파이프라인 — 프로젝트 생성 → 모델링 → 경계/여기 → 솔버 설정 → 주파수 스윕 → 솔빙 → 후처리, 각 단계별로 복사하여 수정할 수 있는 코드 템플릿 제공
3. 세 가지 고빈도 작업 템플릿 — S-파라미터 추출, 원거리 방사 패턴, 파라미터 스윕. 바로 시작점으로 사용 가능

안테나 자체를 설계하지는 않습니다(형상, 급전 방식, 목표 주파수 대역은 사용자/엔지니어의 작업임). "알려진 설계 → 시뮬레이션 결과 도출" 과정을 원활하게 만드는 것이 목적입니다.

트리거 조건

• 사용자가 "이 안테나 HFSS로 시뮬레이션" "S-파라미터 추출" "2-6 GHz 스윕" "방사 패턴 그리기" "이득 확인"을 언급할 때
• 사용자가 .aedt/.aedtz/.hfss 프로젝트 파일을 제공하고 자동/배치 실행을 요청할 때
• 사용자가 import ansys.aedt.core / from pyaedt import Hfss 코드를 작성할 때
• 사용자가 "pyaedt로 HFSS 시작하는 방법" "AEDT 연결 안 됨" "라이선스 점유 문제"를 물을 때

표준 워크플로우(단일 메인 라인)

구체적인 작업과 관계없이, 안테나/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를 사용하지 마세요 — 새 프로세스가 시작되어 라이선스가 두 배로 소모됩니다. 열려 있는 데스크탑을 재사용하려면 new_desktop=False를 사용하세요.
• Mac에서 네이티브 AEDT를 기대하지 마세요 — AEDT는 Windows/Linux에서만 실행됩니다. Mac에서는 Windows로 원격 접속하거나, HFSS 대신 PyEDB로 EDB를 처리하세요.
• hfss.save_project()를 생략하지 마세요 — release 전에 반드시 저장해야 합니다. 그렇지 않으면 다음에 열 때 변경 사항을 찾을 수 없습니다.
• 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 → 템플릿 상단 설명 → antenna-workflow(필요한 단계만 참조) → 문제 발생 시 common-pitfalls 확인.