shou0715-Arthur/pyaedt-hfss-antenna

PyAEDT HFSS Antena/RF Simulação Skill

O que esta skill resolve

Ela torna o processo de "um agente usar Python para controlar o Ansys HFSS para simulação de antenas/RF" em um fluxo de trabalho padronizado. Ela oferece três coisas:

1. Guia de handshake de ambiente — como encontrar o AEDT local, usar gRPC ou COM e evitar conflitos de licença.
2. Pipeline padrão de simulação de antenas — criar projeto → modelagem → condições de contorno/excitações → configuração de solver → varredura de frequência → resolver → pós-processamento. Cada etapa fornece um esqueleto de código que pode ser copiado e adaptado.
3. Três templates de tarefas de alto uso — extração de parâmetros S, diagrama de campo distante e varredura paramétrica. Use-os como ponto de partida e adapte.

Ela não projeta a antena para você (geometria, método de alimentação e banda de frequência alvo são trabalho do usuário/engenheiro). Ela apenas garante que o caminho de "projeto conhecido → obter resultados de simulação" seja suave.

Quando ativar

• O usuário diz "simule esta antena com HFSS", "extraia os parâmetros S", "faça uma varredura de 2 a 6 GHz", "plote o diagrama de radiação" ou "veja o ganho".
• O usuário fornece um projeto .aedt/.aedtz/.hfss e pede para executá-lo automaticamente ou em lote.
• O usuário escreve código com import ansys.aedt.core / from pyaedt import Hfss.
• O usuário pergunta "como iniciar o HFSS com pyaedt", "por que não consigo conectar ao AEDT" ou "o que fazer se a licença estiver ocupada".

Fluxo de trabalho padrão (a linha principal)

Independentemente da tarefa específica, a simulação de antenas/RF segue esta linha principal. Primeiro, crie um mapa mental ao longo desta linha, depois pule para o template correspondente:

[1] Handshake de ambiente →  Confirmar versão do AEDT + versão do Python + interface de comunicação
                              Consulte references/environment-setup.md
                              Se não tiver certeza, execute scripts/check_env.py

[2] Criar/abrir projeto   →  Hfss(project=..., design=..., version=..., new_desktop=...)
                              Importante: non_graphical=True para CI/lote
                                            new_desktop=False para reutilizar desktop já aberto
                                            close_on_exit=True para liberar licença ao final

[3] Modelagem geométrica   →  hfss.modeler.create_box / create_cylinder / create_polyline ...
                              Ou use hfss.modeler.import_3d_cad("xxx.step")
                              É recomendado definir variáveis (veja abaixo) e depois usá-las para orientar a geometria

[4] Parametrização com variáveis →  hfss[" $patch_w "] = "30mm"  (variável de projeto, com $)
                                    hfss["patch_l"]    = "32mm"  (variável de design, sem $)
                                    Crie variáveis para todas as dimensões que podem ser varridas

[5] Condições de contorno e excitações →  Contorno de radiação: hfss.assign_radiation_boundary_to_objects(["AirBox"])
                                           Porta:            hfss.lumped_port / hfss.wave_port / hfss.create_floquet_port
                                           Aterramento:     hfss.assign_perfecte_to_sheets(...)

[6] Configuração do solver →  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] Resolver              →  hfss.analyze(setup="Setup1", cores=8)   # Bloqueante
                             Ou hfss.analyze_setup("Setup1")

[8] Pós-processamento     →  Parâmetros S: hfss.post.get_solution_data("S(1,1)")
                             Campo distante:  hfss.insert_infinite_sphere(...)
                                               hfss.post.get_far_field_data(...)
                             Exportar:  data.export_data_to_csv("xxx.csv")

[9] Finalização           →  hfss.save_project()
                             hfss.release_desktop(close_projects=False, close_desktop=True)
                             Se não liberar, a licença ficará ocupada para sempre!

Como usar esta skill

Ao receber uma tarefa de simulação de antenas/RF pela primeira vez

1. Primeiro, leia references/environment-setup.md — descubra qual versão do AEDT está na máquina do usuário, qual versão do Python, e se o pyaedt precisa ser instalado. Se não tiver certeza, execute scripts/check_env.py.
2. Depois, leia references/antenna-workflow.md — esta é a versão "ampliada" da linha principal acima. Cada etapa fornece o uso da API e parâmetros comuns.
3. Antes de encontrar um erro, dê uma olhada em references/common-pitfalls.md — 80% dos problemas de "não consigo conectar / não consigo executar / resultados errados" estão listados aqui.

Ao escrever código

Vá até templates/ e escolha o template mais próximo da sua tarefa. Copie o bloco inteiro e adapte:

Tipo de tarefa	Template
Projeto único, varredura de S11/S21 em uma ou várias frequências	templates/sparam_extraction.py
Diagrama de campo distante, ganho, eficiência de radiação, diagrama 3D	templates/far_field_pattern.py
Varredura de dimensões geométricas/parâmetros de material, extraindo múltiplos resultados	templates/parametric_sweep.py

Os templates são scripts independentes executáveis. No topo de cada um, há parâmetros expostos como PROJECT_PATH / DESIGN_NAME / FREQ_*. Primeiro, altere o topo; depois, altere a parte de geometria/condições de contorno.

Princípios-chave

• Primeiro pequeno, depois grande: na primeira execução de qualquer script, defina MaximumPasses para 3-5 e o número de pontos de varredura para 21. Primeiro, garanta que o pipeline funcione; depois, refine. Fazer tudo de uma vez pode desperdiçar horas.
• Sempre libere release_desktop: não liberar a licença = erro na próxima inicialização. Use try/finally para envolver o final do script.
• non_graphical como padrão True: a menos que precise ver a geometria/depurar, não abra a GUI. Economiza memória e permite paralelismo.
• Use caminhos absolutos: caminhos relativos podem não apontar para o diretório que você espera dentro do processo do AEDT.
• Priorize variáveis: qualquer dimensão que "possa ser alterada" deve ser definida como variável primeiro. Não use valores fixos no código, caso contrário, a varredura paramétrica exigirá reescrita.

Instalação do pyaedt (se ainda não estiver instalado)

# Combinação recomendada (2025 R2 / 2026 R1)
pip install pyaedt

# AEDT antigo com pyaedt antigo (consulte references/environment-setup.md para a correspondência)
pip install pyaedt==0.17.5     # AEDT 2025 R1
pip install pyaedt==0.13.3     # AEDT 2024 R2

O que NÃO fazer

• Não faça import pyaedt diretamente — a partir da versão 1.0, o recomendado oficialmente é import ansys.aedt.core as pyaedt ou from ansys.aedt.core import Hfss. O código antigo from pyaedt import Hfss ainda funciona, mas está obsoleto.
• Não use new_desktop=True se o AEDT já estiver aberto com a GUI — isso abrirá outro processo, duplicando o uso da licença. Para reutilizar o desktop já aberto, use new_desktop=False.
• Não espere que o AEDT funcione nativamente no Mac — o AEDT só roda em Windows/Linux. No Mac, ou faça conexão remota para uma máquina Windows ou use PyEDB para processar EDB (não HFSS).
• Não omita hfss.save_project() — você precisa salvar antes de liberar (release), caso contrário, as alterações não serão encontradas na próxima abertura.
• Não entregue resultados com MaxDeltaS muito frouxo (>0.05) — se a convergência for insuficiente, o S11 visto será ruído, não um valor físico.

Lista de arquivos de referência

pyaedt-hfss-antenna/
├── SKILL.md                          ← Você está lendo este
├── references/
│   ├── environment-setup.md          ← Correspondência de versões, instalação, gRPC/COM, licenças
│   ├── antenna-workflow.md           ← Detalhamento da API do fluxo de trabalho principal
│   └── common-pitfalls.md            ← Erros frequentes e soluções
├── templates/
│   ├── sparam_extraction.py          ← Extração de parâmetros S por varredura
│   ├── far_field_pattern.py          ← Diagrama de campo distante/ganho
│   └── parametric_sweep.py           ← Varredura paramétrica de variáveis
└── scripts/
    └── check_env.py                  ← Detecta AEDT/Python/pyaedt na máquina local

Ordem de leitura sugerida: este arquivo → environment-setup → explicação no topo do template → antenna-workflow (leia a etapa conforme necessário) → consulte common-pitfalls quando surgir um problema.