hfss-pyaedt-antenna-workflow

name	hfss-pyaedt-antenna-workflow
description	Use when building, simulating, troubleshooting, or optimizing HFSS antenna models with PyAEDT, especially microstrip patch antennas, side-fed antennas, non-graphical AEDT sessions, direct project/design creation, wave or lumped ports, attach-mode fallback workflows, S-parameter export, gain/far-field postprocessing, and parameter tuning.

HFSS PyAEDT Antenna Workflow

Use this skill to automate antenna workflows in HFSS with PyAEDT while preserving simulation integrity. Prefer this flow for parameterized microstrip patch antennas and similar RF antenna tasks.

Core Workflow

1. Create a local Python environment inside the project workspace.
2. Install PyAEDT and numerical/postprocessing dependencies into that environment.
3. Put all design variables in a config file, usually configs/design_params.yaml.
4. Build model scripts as separate stages:
   • build_model.py for variables, materials, geometry, ports, boundaries, setup, sweep, and far-field setup.
   • run_simulation.py for HFSS solve only.
   • postprocess.py for solved-data export only.
   • optimize_design.py for iterative true-solve optimization.
5. Export only real solved data. Never fabricate S11, gain, bandwidth, or Touchstone files.

AEDT / PyAEDT Environment Rules

• Verify AEDT executable existence before launching.

• Prefer python.exe -m pip ... inside the project .venv when installing dependencies on Windows PowerShell.

• Use the version key returned by PyAEDT, not only the install folder name. For AEDT 2026 R1 / v261, the PyAEDT specified_version key is usually "2026.1".

• If PyAEDT cannot discover AEDT, set the version-specific environment variable at runtime, for example:

  os.environ["ANSYSEM_ROOT261"] = r"F:\HFSS\ANSYS Inc\v261\AnsysEM"
  

• A proven direct non-GUI startup pattern is:

  hfss = Hfss(
      specified_version="2026.1",
      non_graphical=True,
      new_desktop_session=True,
      close_on_exit=True,
  )
  

• To open an existing project in non-GUI mode:

  hfss = Hfss(
      projectname=str(project_path),
      specified_version="2026.1",
      non_graphical=True,
      new_desktop_session=True,
      close_on_exit=True,
  )
  

• Always explicitly release desktop sessions at script end:

  hfss.release_desktop(close_projects=True, close_desktop=True)
  

• Treat these as separate checks:

  • AEDT can launch.
  • AEDT can create/open a project.
  • HFSS design insertion works.
  • Existing HFSS design can be automated.
  • Solve and postprocess work.

Direct Creation First, Attach Mode Fallback

For new automation projects, first try direct project/design creation in a clean non-GUI session. This is now the preferred path when the local AEDT/PyAEDT pairing supports it.

Attach mode remains a fallback when:

• direct InsertDesign("HFSS", ...) fails;
• the user has already manually created a validated HFSS design;
• an existing GUI session must be reused for diagnosis;
• the project is locked by an active AEDT process.

If PyAEDT can launch AEDT but fails on InsertDesign("HFSS", ...), ask the user to manually create or open an HFSS design. Then attach PyAEDT to the existing design instead of creating one.

Use this pattern:

.\.venv\Scripts\python.exe scripts\build_model.py --attach-existing --aedt-pid <PID> --existing-project "<project.aedt>" --existing-design <HFSSDesignName>

In attach mode:

• Use new_desktop=False.
• Pass aedt_process_id when known.
• Use the actual design name, not the intended config name.
• Save with hfss.save_project() instead of SaveAs.
• Release with close_projects=False, close_desktop=False.

Read references/project-lessons.md and references/nongui-direct-workflow.md when diagnosing non-GUI creation, attach-mode, port, SaveAs, or optimization issues.

Geometry and Port Guidance

• For rectangular microstrip patch antennas, parameterize at least: f0, freq_start, freq_stop, substrate_er, substrate_h, metal_t, tan_delta, patch_length, patch_width, feed_width_50ohm, transformer_width, transformer_length, transformer_impedance, feed_length, substrate_length, substrate_width, ground_length, ground_width, and airbox_padding.
• Use theory formulas for initial patch and microstrip dimensions. Do not invent dimensions without calculation.
• Use side feed as 50 ohm feed -> quarter-wave transformer -> patch edge.
• Prefer 3D copper solids for ground in robust microstrip models. A 2D PEC ground may work in simple cases but can complicate wave-port reference behavior.
• For higher-fidelity patch/feed modeling, use finite-thickness copper solids or verify that 2D sheets are assigned and meshed as intended.
• Ensure dielectric substrate objects have solve_inside=True.
• Prefer manually created air boxes with radiation boundaries over opaque helper APIs when size and placement matter.
• For lumped port integration lines, prefer numeric model-unit coordinates. Avoid mixing "0mm" strings with variable strings if PyAEDT appends units automatically.

Good integration-line pattern:

integration_line=[[0, 0, substrate_h_mm], [0, 0, 0]]

For Driven Modal microstrip feeds, wave ports are often more reliable than lumped ports. Internal wave ports must be backed by a PEC/copper cap, and the integration line endpoints must lie on the port sheet.

Simulation Settings

• Use Driven Modal for a standard patch antenna unless the user requests another solution type.
• PyAEDT/HFSS may default to Terminal solution type in some contexts. Explicitly set and verify hfss.solution_type = "DrivenModal" before creating Driven Modal ports and setups.
• Start with an interpolating sweep for a smooth S11 search over a broad band.
• Use MaxDeltaS <= 0.02 and at least 10 maximum passes when matching the project requirement.
• Add Infinite Sphere for gain and far-field reports.
• For PyAEDT versions where setup templates are fragile, hfss.create_setup(name="Setup1", setup_type=1) is a proven Driven Modal setup pattern.

Postprocessing Rules

• Export S11 CSV from solved HFSS data.
• Export Touchstone only after a successful solve.
• Use setup/sweep names in the "SetupName : SweepName" format for get_solution_data.
• Far-field gain queries should include the Infinite Sphere context and report_category="Far Fields" when required by the PyAEDT version.
• Compute:
  • S11 @ f0
  • minimum S11
  • frequency at minimum S11
  • -10 dB bandwidth
  • peak gain
  • peak realized gain
  • far-field pattern
• If data is missing, write a failure JSON summary instead of placeholder results.

Optimization Strategy

For a side-fed microstrip patch:

1. Tune patch_length first to center the resonance frequency.
2. Tune transformer_length to adjust transformer electrical length.
3. Tune transformer_width to adjust impedance transformation.
4. Stop early once the stated requirements are met.

For a first-order patch-length correction:

new_patch_length ~= old_patch_length * observed_resonance / target_frequency

Then run real HFSS solves for candidate values and select based on S11 @ f0, resonance frequency, and gain.

Completion Criteria

Report final success only when:

• The AEDT project is saved.
• The solve completed successfully.
• S11 and gain are exported from real solved data.
• The final summary compares results to the user’s stated requirements.