sim-plugin-hfss 0.1.0__py3-none-any.whl

sim_plugin_hfss/__init__.py

@@ -0,0 +1,22 @@
+"""Ansys HFSS driver plugin for sim-cli.
+
+The package is discovered by sim-cli through entry points. Importing it must
+stay safe on machines without AEDT or PyAEDT; the driver imports PyAEDT lazily
+only when a runtime operation needs it.
+"""
+from importlib.resources import files
+
+from .driver import HfssDriver
+
+skills_dir = files(__name__) / "_skills"
+
+
+plugin_info = {
+    "name": "hfss",
+    "summary": "Ansys HFSS 3D driver plugin for sim-cli.",
+    "homepage": "https://github.com/svd-ai-lab/sim-plugin-hfss",
+    "license_class": "commercial",
+    "solver_name": "hfss",
+}
+
+__all__ = ["HfssDriver", "skills_dir", "plugin_info"]

sim_plugin_hfss/_skills/hfss/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: hfss
+description: "Work with Ansys HFSS 3D through sim-plugin-hfss and PyAEDT. Use when the user asks an agent to inspect, build, edit, run, or debug HFSS 3D models."
+---
+
+# HFSS Skill
+
+Use this skill for Ansys HFSS 3D work through `sim-plugin-hfss`.
+
+This initial plugin targets HFSS 3D through PyAEDT. It does not yet cover HFSS
+3D Layout, Maxwell, Icepak, Q3D, Circuit, or generic AEDT workflows.
+
+## Required Protocol
+
+1. Run `sim check hfss` before launching or editing anything.
+2. If `sim check hfss` reports `not_installed`, stop and ask the user for an
+   AEDT installation or `SIM_HFSS_AEDT_ROOT` path. Do not invent install paths.
+3. Prefer `--ui-mode no_gui` unless the user explicitly needs visual review.
+4. Before setup, solve, export, or result interpretation, inspect:
+
+```bash
+sim inspect session.summary
+sim inspect hfss.project.identity
+sim inspect hfss.design.summary
+```
+
+5. Run one bounded PyAEDT snippet at a time.
+6. Inspect `last.result` and the relevant project/design state after each
+   mutation.
+7. Treat process success as transport success only. Engineering acceptance must
+   come from HFSS results, exported data, convergence, S-parameters, fields, or
+   another domain-specific criterion requested by the user.
+
+## Common Workflows
+
+### Connect to HFSS
+
+```bash
+sim connect --solver hfss --ui-mode no_gui
+sim inspect session.summary
+sim inspect hfss.project.identity
+sim inspect hfss.design.summary
+```
+
+Use GUI mode only when the user needs to watch AEDT:
+
+```bash
+sim connect --solver hfss --ui-mode gui
+```
+
+### Run a PyAEDT script
+
+Use this for a complete script that constructs or opens an HFSS project:
+
+```bash
+sim lint --solver hfss path/to/script.py
+sim run --solver hfss path/to/script.py
+```
+
+The script runs in the current Python environment. PyAEDT and AEDT must be
+available there.
+
+### Execute a bounded snippet
+
+After `sim connect`, snippets can use the live `hfss` object:
+
+```python
+hfss.project_name
+```
+
+Return JSON-serializable data from the last expression when possible:
+
+```python
+{
+    "project": hfss.project_name,
+    "design": hfss.design_name,
+    "setups": list(hfss.setup_names),
+}
+```
+
+## First-Version Limits
+
+- Direct `.aedt` and `.aedtz` solving is not validated yet.
+- Real HFSS release validation is opt-in and must be recorded separately from
+  ordinary no-AEDT unit tests.
+- Do not claim solver correctness from plugin unit tests alone.
+
+## Troubleshooting
+
+- Driver not discovered: reinstall the plugin in the same environment as
+  sim-cli and rerun `sim check hfss`.
+- AEDT not detected: set `SIM_HFSS_AEDT_ROOT` to the directory containing
+  an AEDT launcher, or rely on default discovery for common install layouts. A
+  permanent global `PATH` change is optional, not required.
+- PyAEDT import error: install `pyaedt>=0.26.3,<1` in the active environment.
+- Script not detected: make sure it constructs HFSS through PyAEDT, for
+  example `from ansys.aedt.core.hfss import Hfss` followed by `Hfss(...)`.

sim_plugin_hfss/driver.py

@@ -0,0 +1,776 @@
+"""Ansys HFSS 3D driver for sim-cli.
+
+The driver uses PyAEDT as the runtime control layer but keeps all PyAEDT imports
+lazy. This lets ``sim check hfss`` and protocol tests run on machines that do
+not have AEDT, HFSS, or PyAEDT importable.
+"""
+from __future__ import annotations
+
+import ast
+import glob
+import io
+import json
+import os
+import re
+import shutil
+import sys
+import time
+import traceback
+import uuid
+from contextlib import redirect_stderr, redirect_stdout
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from sim.driver import ConnectionInfo, Diagnostic, LintResult, RunResult, SolverInstall
+from sim.runner import run_subprocess
+
+
+_HFSS_IMPORT_TEXT_RE = re.compile(
+    r"^\s*(?:"
+    r"from\s+ansys\.aedt\.core(?:\.hfss)?\s+import\s+.*\bHfss\b|"
+    r"from\s+pyaedt\s+import\s+.*\bHfss\b|"
+    r"import\s+pyaedt\b|"
+    r"import\s+ansys\.aedt\.core(?:\.hfss)?\b"
+    r")",
+    re.MULTILINE,
+)
+
+_HFSS_CALL_TEXT_RE = re.compile(
+    r"\b(?:Hfss|pyaedt\.Hfss|ansys\.aedt\.core\.Hfss)\s*\("
+)
+
+_AEDT_ENV_VARS = ("SIM_HFSS_AEDT_ROOT", "SIM_AEDT_ROOT")
+_ANSYSEM_ENV_RE = re.compile(
+    r"^(ANSYSEM_ROOT|ANSYSEMSV_ROOT|ANSYSEM_PY_CLIENT_ROOT)(\d{3})$",
+    re.IGNORECASE,
+)
+_VERSION_CODE_RE = re.compile(r"v?(\d{3})", re.IGNORECASE)
+_AEDT_EXECUTABLE_NAMES = ("ansysedt.exe", "ansysedt", "ansysedtsv.exe", "ansysedtsv")
+_STUDENT_EXE_NAMES = ("ansysedtsv.exe", "ansysedtsv")
+_DEFAULT_INSTALL_PATTERNS = [
+    "C:/Program Files/AnsysEM/v*",
+    "C:/Program Files/AnsysEM/v*/Win64",
+    "C:/Program Files/ANSYS Inc/v*",
+    "C:/Program Files/ANSYS Inc/v*/AnsysEM",
+    "C:/Program Files/ANSYS Inc/v*/AnsysEM/Win64",
+    "C:/Program Files/ANSYS Inc/ANSYS Student/v*",
+    "C:/Program Files/ANSYS Inc/ANSYS Student/v*/AnsysEM",
+    "D:/Program Files/AnsysEM/v*",
+    "D:/Program Files/AnsysEM/v*/Win64",
+    "D:/Program Files/ANSYS Inc/v*",
+    "D:/Program Files/ANSYS Inc/v*/AnsysEM",
+    "D:/Program Files/ANSYS Inc/v*/AnsysEM/Win64",
+    "D:/Program Files/ANSYS Inc/ANSYS Student/v*",
+    "D:/Program Files/ANSYS Inc/ANSYS Student/v*/AnsysEM",
+    "/opt/ansys_inc/v*",
+    "/opt/ansys_inc/v*/AnsysEM",
+    "/opt/ansys_inc/v*/AnsysEM/Linux64",
+    "/usr/ansys_inc/v*",
+    "/usr/ansys_inc/v*/AnsysEM",
+    "/usr/ansys_inc/v*/AnsysEM/Linux64",
+    "/opt/AnsysEM/v*",
+    "/opt/AnsysEM/v*/Linux64",
+]
+
+_NOT_INSTALLED_HINT = (
+    "No Ansys Electronics Desktop installation detected on this host. "
+    "Set SIM_HFSS_AEDT_ROOT or SIM_AEDT_ROOT to the AEDT root, or expose an "
+    "AEDT launcher such as ansysedt or ansysedtsv on PATH."
+)
+
+
+@dataclass(frozen=True)
+class _PyaedtApi:
+    Desktop: Any | None
+    Hfss: Any
+    version: str | None
+
+
+def _importlib_version(dist_name: str) -> str | None:
+    try:
+        from importlib.metadata import version
+
+        return version(dist_name)
+    except Exception:
+        return None
+
+
+def _try_import_pyaedt() -> _PyaedtApi | None:
+    """Import PyAEDT lazily, supporting the modern and legacy import paths."""
+    try:
+        import ansys.aedt.core as core  # type: ignore
+
+        Desktop = getattr(core, "Desktop", None)
+        Hfss = getattr(core, "Hfss", None)
+        if Hfss is None:
+            from ansys.aedt.core.hfss import Hfss as HfssClass  # type: ignore
+
+            Hfss = HfssClass
+        return _PyaedtApi(
+            Desktop=Desktop,
+            Hfss=Hfss,
+            version=getattr(core, "__version__", None) or _importlib_version("pyaedt"),
+        )
+    except Exception:
+        pass
+
+    try:
+        import pyaedt  # type: ignore
+
+        return _PyaedtApi(
+            Desktop=getattr(pyaedt, "Desktop", None),
+            Hfss=getattr(pyaedt, "Hfss"),
+            version=getattr(pyaedt, "__version__", None) or _importlib_version("pyaedt"),
+        )
+    except Exception:
+        return None
+
+
+def _patch_pyaedt_student_startup_check() -> None:
+    """Work around PyAEDT 0.26.x parsing ``2025.2SV`` as a float on Windows."""
+    try:
+        import ansys.aedt.core.desktop as desktop_mod  # type: ignore
+
+        desktop_cls = desktop_mod.Desktop
+        original = desktop_cls.check_starting_mode
+        if getattr(original, "_sim_hfss_student_suffix_patch", False):
+            return
+
+        def patched_check_starting_mode(self):
+            version_id = getattr(self, "aedt_version_id", "")
+            if isinstance(version_id, str) and version_id.upper().endswith("SV"):
+                trimmed = version_id[:-2]
+                try:
+                    self.aedt_version_id = trimmed
+                    return original(self)
+                finally:
+                    self.aedt_version_id = version_id
+            return original(self)
+
+        patched_check_starting_mode._sim_hfss_student_suffix_patch = True
+        desktop_cls.check_starting_mode = patched_check_starting_mode
+    except Exception:
+        return
+
+
+def _read_text(path: Path) -> str | None:
+    try:
+        return path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def _has_hfss_signature(text: str) -> bool:
+    """Return True when code appears to create or import a PyAEDT HFSS app."""
+    if _HFSS_IMPORT_TEXT_RE.search(text) and _HFSS_CALL_TEXT_RE.search(text):
+        return True
+
+    try:
+        tree = ast.parse(text)
+    except SyntaxError:
+        return bool(_HFSS_IMPORT_TEXT_RE.search(text) and "Hfss" in text)
+
+    hfss_names: set[str] = set()
+    module_aliases: set[str] = set()
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom):
+            if node.module in {"ansys.aedt.core", "ansys.aedt.core.hfss", "pyaedt"}:
+                for alias in node.names:
+                    if alias.name == "Hfss":
+                        hfss_names.add(alias.asname or alias.name)
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name in {"pyaedt", "ansys.aedt.core", "ansys.aedt.core.hfss"}:
+                    module_aliases.add(alias.asname or alias.name.split(".")[0])
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call):
+            func = node.func
+            if isinstance(func, ast.Name) and func.id in hfss_names:
+                return True
+            if (
+                isinstance(func, ast.Attribute)
+                and func.attr == "Hfss"
+                and isinstance(func.value, ast.Name)
+                and func.value.id in module_aliases
+            ):
+                return True
+
+    return False
+
+
+def _version_from_code(code: str | None) -> str | None:
+    if not code or not code.isdigit() or len(code) != 3:
+        return None
+    return f"20{code[:2]}.{code[2]}"
+
+
+def _code_from_version(version: str | None) -> str | None:
+    if not version:
+        return None
+    m = re.match(r"^20(\d{2})\.(\d+)", version)
+    if not m:
+        return None
+    return f"{m.group(1)}{m.group(2)}"
+
+
+def _version_from_path(path: Path) -> str:
+    for part in [path.name, *[p.name for p in path.parents[:3]]]:
+        m = _VERSION_CODE_RE.search(part)
+        if m:
+            version = _version_from_code(m.group(1))
+            if version:
+                return version
+        m = re.search(r"20(\d{2})[._ -]?R?([12])", part, re.IGNORECASE)
+        if m:
+            return f"20{m.group(1)}.{m.group(2)}"
+    return "unknown"
+
+
+def _find_aedt_executable(root: Path) -> Path | None:
+    if root.is_file() and root.name.lower() in _AEDT_EXECUTABLE_NAMES:
+        return root
+    dirs = (
+        root,
+        root / "Win64",
+        root / "Linux64",
+        root / "AnsysEM",
+        root / "AnsysEM" / "Win64",
+        root / "AnsysEM" / "Linux64",
+    )
+    for directory in dirs:
+        for name in _AEDT_EXECUTABLE_NAMES:
+            candidate = directory / name
+            if candidate.is_file():
+                return candidate
+    return None
+
+
+def _looks_like_student_install(root: Path, exe: Path) -> bool:
+    values = [exe.name, str(root), str(exe)]
+    return any("student" in value.lower() for value in values) or exe.name.lower() in _STUDENT_EXE_NAMES
+
+
+def _install_from_root(
+    root: Path,
+    source: str,
+    version: str | None = None,
+    student_version: bool | None = None,
+) -> SolverInstall | None:
+    exe = _find_aedt_executable(root)
+    if exe is None:
+        return None
+    install_root = exe.parent
+    detected_version = version or _version_from_path(install_root)
+    detected_student = _looks_like_student_install(root, exe)
+    is_student = bool(student_version or detected_student)
+    return SolverInstall(
+        name="hfss",
+        version=detected_version,
+        path=str(install_root),
+        source=source,
+        extra={
+            "executable": str(exe),
+            "aedt_root": str(root),
+            "student_version": is_student,
+        },
+    )
+
+
+def _candidates_from_env() -> list[SolverInstall]:
+    installs: list[SolverInstall] = []
+    for var in _AEDT_ENV_VARS:
+        value = os.environ.get(var)
+        if value:
+            install = _install_from_root(Path(value), f"env:{var}")
+            if install:
+                installs.append(install)
+
+    for key, value in sorted(os.environ.items()):
+        match = _ANSYSEM_ENV_RE.match(key)
+        if not match or not value:
+            continue
+        install = _install_from_root(
+            Path(value),
+            f"env:{key}",
+            version=_version_from_code(match.group(2)),
+            student_version=match.group(1).upper() == "ANSYSEMSV_ROOT",
+        )
+        if install:
+            installs.append(install)
+    return installs
+
+
+def _candidates_from_path() -> list[SolverInstall]:
+    installs: list[SolverInstall] = []
+    for executable in _AEDT_EXECUTABLE_NAMES:
+        found = shutil.which(executable)
+        if not found:
+            continue
+        path = Path(found).resolve()
+        student_version = _looks_like_student_install(path.parent, path)
+        installs.append(
+            SolverInstall(
+                name="hfss",
+                version=_version_from_path(path),
+                path=str(path.parent),
+                source=f"which:{executable}",
+                extra={
+                    "executable": str(path),
+                    "aedt_root": str(path.parent),
+                    "student_version": student_version,
+                },
+            )
+        )
+    return installs
+
+
+def _candidates_from_defaults() -> list[SolverInstall]:
+    installs: list[SolverInstall] = []
+    for pattern in _DEFAULT_INSTALL_PATTERNS:
+        for raw in glob.glob(pattern):
+            install = _install_from_root(Path(raw), f"default-path:{raw}")
+            if install:
+                installs.append(install)
+    return installs
+
+
+_INSTALL_FINDERS = [
+    _candidates_from_env,
+    _candidates_from_path,
+    _candidates_from_defaults,
+]
+
+
+def _scan_aedt_installs() -> list[SolverInstall]:
+    found: dict[str, SolverInstall] = {}
+    for finder in _INSTALL_FINDERS:
+        try:
+            candidates = finder()
+        except Exception:
+            continue
+        for install in candidates:
+            exe = install.extra.get("executable") or install.path
+            try:
+                key = str(Path(exe).resolve())
+            except OSError:
+                key = str(exe)
+            found.setdefault(key, install)
+    return sorted(found.values(), key=_install_sort_key, reverse=True)
+
+
+def _pyaedt_env_key(install: SolverInstall) -> str | None:
+    code = _code_from_version(install.version)
+    if not code:
+        return None
+    if install.extra.get("student_version"):
+        return f"ANSYSEMSV_ROOT{code}"
+    return f"ANSYSEM_ROOT{code}"
+
+
+def _prepare_pyaedt_environment(install: SolverInstall | None) -> dict[str, str]:
+    """Expose a detected install through the process env shape PyAEDT expects."""
+    if install is None:
+        return {}
+    key = _pyaedt_env_key(install)
+    if key is None:
+        return {}
+    os.environ[key] = install.path
+    return {key: install.path}
+
+
+def _install_sort_key(install: SolverInstall) -> tuple[int, int, str]:
+    match = re.match(r"^(\d{4})\.(\d+)$", install.version)
+    if match:
+        return (1, int(match.group(1)) * 10 + int(match.group(2)), install.path)
+    return (0, 0, install.path)
+
+
+def _short_text(value: object, *, limit: int = 240) -> str:
+    text = "" if value is None else str(value)
+    text = "".join(ch if 32 <= ord(ch) < 127 else "?" for ch in text)
+    return text[:limit]
+
+
+def _safe_attr(obj: object, name: str, default: object = None) -> object:
+    try:
+        value = getattr(obj, name)
+        return value() if callable(value) and name.startswith("get_") else value
+    except Exception:
+        return default
+
+
+def _jsonable(value: object) -> object:
+    try:
+        json.dumps(value)
+        return value
+    except TypeError:
+        return repr(value)
+
+
+class HfssDriver:
+    """Sim driver for Ansys HFSS 3D through PyAEDT."""
+
+    def __init__(self) -> None:
+        self._hfss: Any | None = None
+        self._desktop: Any | None = None
+        self._session_id: str | None = None
+        self._ui_mode: str | None = None
+        self._connected_at: str | None = None
+        self._run_count: int = 0
+        self._last_run: dict | None = None
+        self._pyaedt_version: str | None = None
+        self._launch_options: dict[str, object] = {}
+
+    @property
+    def name(self) -> str:
+        return "hfss"
+
+    @property
+    def supports_session(self) -> bool:
+        return True
+
+    def detect(self, script: Path) -> bool:
+        if script.suffix.lower() != ".py":
+            return False
+        text = _read_text(script)
+        if text is None:
+            return False
+        return _has_hfss_signature(text)
+
+    def lint(self, script: Path) -> LintResult:
+        diagnostics: list[Diagnostic] = []
+        if script.suffix.lower() != ".py":
+            return LintResult(
+                ok=False,
+                diagnostics=[Diagnostic("error", "HFSS v0.1.0 only lints PyAEDT Python scripts")],
+            )
+
+        text = _read_text(script)
+        if text is None:
+            return LintResult(
+                ok=False,
+                diagnostics=[Diagnostic("error", f"cannot read file: {script}")],
+            )
+
+        try:
+            ast.parse(text)
+        except SyntaxError as e:
+            diagnostics.append(Diagnostic("error", f"syntax error: {e}", e.lineno))
+
+        if not _has_hfss_signature(text):
+            diagnostics.append(
+                Diagnostic(
+                    "error",
+                    "no PyAEDT HFSS construction found; expected ansys.aedt.core.hfss.Hfss or Hfss",
+                )
+            )
+
+        ok = not any(d.level == "error" for d in diagnostics)
+        return LintResult(ok=ok, diagnostics=diagnostics)
+
+    def detect_installed(self) -> list[SolverInstall]:
+        return _scan_aedt_installs()
+
+    def connect(self) -> ConnectionInfo:
+        installs = self.detect_installed()
+        if not installs:
+            return ConnectionInfo(
+                solver=self.name,
+                version=None,
+                status="not_installed",
+                message=_NOT_INSTALLED_HINT,
+            )
+
+        top = installs[0]
+        _prepare_pyaedt_environment(top)
+        api = _try_import_pyaedt()
+        if api is None:
+            return ConnectionInfo(
+                solver=self.name,
+                version=top.version,
+                status="error",
+                message=(
+                    f"AEDT {top.version} was found, but PyAEDT is not importable. "
+                    "Install with: uv pip install 'pyaedt>=0.26.3,<1'."
+                ),
+                solver_version=top.version,
+            )
+
+        return ConnectionInfo(
+            solver=self.name,
+            version=top.version,
+            status="ok",
+            message=f"AEDT {top.version} with PyAEDT {api.version or 'unknown'}",
+            solver_version=top.version,
+        )
+
+    def parse_output(self, stdout: str) -> dict:
+        if not stdout or not stdout.strip():
+            return {}
+        for line in reversed(stdout.strip().splitlines()):
+            line = line.strip()
+            if line.startswith("{") and line.endswith("}"):
+                try:
+                    return json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+        return {}
+
+    def run_file(self, script: Path) -> RunResult:
+        if script.suffix.lower() != ".py":
+            raise RuntimeError(
+                "HFSS v0.1.0 only runs PyAEDT Python scripts. Direct .aedt/.aedtz "
+                "solve support is deferred until real HFSS validation is available."
+            )
+        return run_subprocess([sys.executable, str(script)], script=script, solver=self.name)
+
+    def launch(
+        self,
+        *,
+        ui_mode: str | None = "no_gui",
+        mode: str | None = None,
+        version: str | int | float | None = None,
+        project: str | None = None,
+        design: str | None = None,
+        solution_type: str | None = None,
+        setup: str | None = None,
+        machine: str = "",
+        port: int = 0,
+        new_desktop: bool = True,
+        close_on_exit: bool = False,
+        student_version: bool | None = None,
+        **kwargs: object,
+    ) -> dict:
+        installs = self.detect_installed()
+        if not installs and not machine:
+            return {
+                "ok": False,
+                "error_code": "SOLVER_NOT_INSTALLED",
+                "message": _short_text(_NOT_INSTALLED_HINT),
+            }
+
+        selected_install = installs[0] if installs else None
+        prepared_env = _prepare_pyaedt_environment(selected_install)
+        api = _try_import_pyaedt()
+        if api is None:
+            return {
+                "ok": False,
+                "error_code": "RUN_FAILED",
+                "message": "PyAEDT is not importable; install pyaedt>=0.26.3,<1.",
+            }
+
+        normalized_ui = (ui_mode or "no_gui").replace("-", "_").lower()
+        if normalized_ui in {"no_gui", "nogui", "headless", "batch"}:
+            non_graphical = True
+            normalized_ui = "no_gui"
+        elif normalized_ui in {"gui", "visible", "desktop"}:
+            non_graphical = False
+            normalized_ui = "gui"
+        else:
+            return {
+                "ok": False,
+                "error_code": "RUN_FAILED",
+                "message": f"unsupported HFSS ui_mode: {ui_mode}",
+            }
+
+        if student_version is None:
+            student_version = bool(selected_install and selected_install.extra.get("student_version"))
+        if student_version:
+            _patch_pyaedt_student_startup_check()
+
+        launch_kwargs = {
+            "project": project,
+            "design": design,
+            "solution_type": solution_type,
+            "setup": setup,
+            "version": version,
+            "non_graphical": non_graphical,
+            "new_desktop": new_desktop,
+            "close_on_exit": close_on_exit,
+            "student_version": student_version,
+            "machine": machine,
+            "port": port,
+        }
+        launch_kwargs = {k: v for k, v in launch_kwargs.items() if v not in {None, ""}}
+
+        try:
+            hfss = api.Hfss(**launch_kwargs)
+        except Exception as e:
+            return {
+                "ok": False,
+                "error_code": "RUN_FAILED",
+                "message": _short_text(f"HFSS launch failed: {type(e).__name__}: {e}"),
+                "details": {"traceback": traceback.format_exc(limit=5)},
+            }
+
+        self._hfss = hfss
+        self._desktop = getattr(hfss, "desktop_class", None) or getattr(hfss, "desktop", None)
+        self._session_id = f"hfss-{uuid.uuid4().hex[:12]}"
+        self._ui_mode = normalized_ui
+        self._connected_at = datetime.now(timezone.utc).isoformat()
+        self._run_count = 0
+        self._last_run = None
+        self._pyaedt_version = api.version
+        self._launch_options = {
+            **launch_kwargs,
+            "ui_mode": normalized_ui,
+            "mode": mode,
+            "prepared_env": prepared_env,
+            **kwargs,
+        }
+        return {
+            "ok": True,
+            "session_id": self._session_id,
+            "solver": self.name,
+            "ui_mode": normalized_ui,
+            "non_graphical": non_graphical,
+            "student_version": student_version,
+            "pyaedt_version": api.version,
+            "launch_options": dict(self._launch_options),
+        }
+
+    def run(self, code: str, label: str = "") -> dict:
+        if self._hfss is None:
+            return {
+                "ok": False,
+                "error_code": "SESSION_NOT_FOUND",
+                "message": "HFSS session is not launched.",
+            }
+
+        stdout_buf = io.StringIO()
+        stderr_buf = io.StringIO()
+        start = time.monotonic()
+        result: object = None
+        ok = True
+        error: str | None = None
+
+        namespace = {
+            "hfss": self._hfss,
+            "desktop": self._desktop,
+            "json": json,
+        }
+        try:
+            with redirect_stdout(stdout_buf), redirect_stderr(stderr_buf):
+                result = self._execute_code(code, namespace)
+        except Exception as e:
+            ok = False
+            error = f"{type(e).__name__}: {e}"
+            stderr_buf.write(traceback.format_exc(limit=5))
+
+        duration = round(time.monotonic() - start, 4)
+        self._run_count += 1
+        payload = {
+            "ok": ok,
+            "stdout": stdout_buf.getvalue(),
+            "stderr": stderr_buf.getvalue(),
+            "duration_s": duration,
+            "label": label,
+            "result": _jsonable(result),
+        }
+        if not ok:
+            payload.update(
+                {
+                    "error_code": "RUN_FAILED",
+                    "message": _short_text(error),
+                }
+            )
+        self._last_run = payload
+        return payload
+
+    def query(self, name: str) -> dict:
+        if name == "session.summary":
+            return {
+                "ok": True,
+                "connected": self._hfss is not None,
+                "session_id": self._session_id,
+                "solver": self.name,
+                "ui_mode": self._ui_mode,
+                "run_count": self._run_count,
+                "connected_at": self._connected_at,
+                "pyaedt_version": self._pyaedt_version,
+            }
+        if name == "last.result":
+            return {"ok": True, "result": self._last_run}
+        if self._hfss is None:
+            return {
+                "ok": False,
+                "error_code": "SESSION_NOT_FOUND",
+                "message": "HFSS session is not launched.",
+            }
+        if name == "hfss.project.identity":
+            return {"ok": True, **self._project_identity()}
+        if name == "hfss.design.summary":
+            return {"ok": True, **self._design_summary()}
+        return {
+            "ok": False,
+            "error_code": "RUN_FAILED",
+            "message": f"unknown HFSS query: {name}",
+        }
+
+    def disconnect(self) -> dict:
+        if self._hfss is None:
+            return {"ok": True, "disconnected": True}
+
+        errors: list[str] = []
+        try:
+            release = getattr(self._hfss, "release_desktop", None)
+            if callable(release):
+                release(close_projects=False, close_desktop=True)
+            elif self._desktop is not None:
+                desktop_release = getattr(self._desktop, "release_desktop", None)
+                if callable(desktop_release):
+                    desktop_release(close_projects=False, close_desktop=True)
+        except Exception as e:
+            errors.append(f"{type(e).__name__}: {e}")
+        finally:
+            self._hfss = None
+            self._desktop = None
+            self._session_id = None
+
+        if errors:
+            return {
+                "ok": False,
+                "disconnected": True,
+                "error_code": "RUN_FAILED",
+                "message": _short_text("; ".join(errors)),
+            }
+        return {"ok": True, "disconnected": True}
+
+    def _execute_code(self, code: str, namespace: dict[str, object]) -> object:
+        tree = ast.parse(code, filename="<hfss-exec>", mode="exec")
+        if tree.body and isinstance(tree.body[-1], ast.Expr):
+            prefix = ast.Module(body=tree.body[:-1], type_ignores=[])
+            ast.fix_missing_locations(prefix)
+            exec(compile(prefix, "<hfss-exec>", "exec"), namespace)
+            expr = ast.Expression(tree.body[-1].value)
+            ast.fix_missing_locations(expr)
+            return eval(compile(expr, "<hfss-exec>", "eval"), namespace)
+        exec(compile(tree, "<hfss-exec>", "exec"), namespace)
+        return namespace.get("result")
+
+    def _project_identity(self) -> dict:
+        hfss = self._hfss
+        assert hfss is not None
+        return {
+            "project_name": _jsonable(_safe_attr(hfss, "project_name")),
+            "project_file": _jsonable(_safe_attr(hfss, "project_file")),
+            "project_path": _jsonable(_safe_attr(hfss, "project_path")),
+            "working_directory": _jsonable(_safe_attr(hfss, "working_directory")),
+            "aedt_version_id": _jsonable(_safe_attr(hfss, "aedt_version_id")),
+        }
+
+    def _design_summary(self) -> dict:
+        hfss = self._hfss
+        assert hfss is not None
+        return {
+            "design_name": _jsonable(_safe_attr(hfss, "design_name")),
+            "design_type": _jsonable(_safe_attr(hfss, "design_type")),
+            "solution_type": _jsonable(_safe_attr(hfss, "solution_type")),
+            "setup_names": _jsonable(_safe_attr(hfss, "setup_names", [])),
+            "excitation_names": _jsonable(_safe_attr(hfss, "excitation_names", [])),
+            "valid_design": _jsonable(_safe_attr(hfss, "valid_design")),
+        }

sim_plugin_hfss-0.1.0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: sim-plugin-hfss
+Version: 0.1.0
+Summary: Ansys HFSS driver for sim-cli, distributed as a plugin
+Project-URL: Homepage, https://github.com/svd-ai-lab/sim-plugin-hfss
+Project-URL: Repository, https://github.com/svd-ai-lab/sim-plugin-hfss
+Project-URL: Issues, https://github.com/svd-ai-lab/sim-plugin-hfss/issues
+Project-URL: Changelog, https://github.com/svd-ai-lab/sim-plugin-hfss/blob/main/CHANGELOG.md
+Author: svd-ai-lab
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: LICENSE-NOTICE.md
+Keywords: aedt,em,hfss,plugin,pyaedt,pyansys,sim-cli,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.10
+Requires-Dist: pyaedt<1,>=0.26.3
+Requires-Dist: sim-cli-core>=0.3.4
+Provides-Extra: test
+Requires-Dist: build>=1.0; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# sim-plugin-hfss
+
+Use Codex, Claude Code, or another AI agent to work with
+[Ansys HFSS](https://www.ansys.com/products/electronics/ansys-hfss) 3D
+projects through [sim-cli](https://github.com/svd-ai-lab/sim-cli).
+
+`sim-plugin-hfss` is an initial HFSS 3D driver plugin for sim-cli. It uses
+PyAEDT as the Python control layer for Ansys Electronics Desktop (AEDT), keeps
+the driver import-safe on machines without AEDT, and bundles an HFSS agent
+skill so an agent has solver-specific workflow guidance after installation.
+
+The HFSS/AEDT application is not bundled. See
+[LICENSE-NOTICE.md](LICENSE-NOTICE.md).
+
+## Current maturity
+
+This is an initial alpha release. It has unit coverage, protocol conformance
+coverage, simulated PyAEDT session coverage, packaging checks, and opt-in real
+HFSS smoke coverage for hosts with AEDT available.
+
+Use it as an integration starting point, not as proof that a production HFSS
+workflow has been validated end to end.
+
+## Scope
+
+Version 0.1.0 targets HFSS 3D through PyAEDT's `ansys.aedt.core.hfss.Hfss`
+interface.
+
+Out of scope for this first version:
+
+- HFSS 3D Layout
+- Maxwell, Icepak, Q3D, Circuit, or generic AEDT workflows
+- Direct `.aedt` or `.aedtz` batch solve without a PyAEDT script
+- Plugin-index catalogue entry before the package is published and smoke-tested
+
+## What an agent can do with HFSS
+
+- Detect PyAEDT Python scripts that instantiate HFSS.
+- Check whether AEDT appears to be installed on the host.
+- Start a PyAEDT-backed HFSS session in graphical or non-graphical mode when
+  AEDT is available.
+- Execute bounded Python snippets against the active `hfss` object.
+- Inspect session, project, and design summaries before continuing.
+- Run complete PyAEDT Python scripts through `sim run --solver hfss`.
+
+## Install
+
+Install from PyPI:
+
+```bash
+uv pip install "sim-plugin-hfss==0.1.0"
+```
+
+For source testing against the current main branch:
+
+```bash
+uv pip install "git+https://github.com/svd-ai-lab/sim-plugin-hfss.git@main"
+```
+
+After installation, sim-cli should auto-discover the driver and bundled skill:
+
+```bash
+sim check hfss
+sim run --solver hfss path/to/script.py
+```
+
+If `sim check hfss` reports that AEDT itself is unavailable, first confirm the
+Python package installed correctly, then fix the local AEDT installation,
+environment variables, or runtime prerequisites.
+
+## AEDT discovery
+
+The driver looks for AEDT using:
+
+- `SIM_HFSS_AEDT_ROOT`
+- `SIM_AEDT_ROOT`
+- `ANSYSEM_ROOT*`
+- AEDT launchers such as `ansysedt`, `ansysedt.exe`, or `ansysedtsv.exe` on
+  `PATH`
+- conservative default Windows and Linux install roots
+
+If AEDT is installed in a nonstandard location, set an explicit root:
+
+```powershell
+$env:SIM_HFSS_AEDT_ROOT = 'C:\path\to\AnsysEM'
+sim check hfss
+```
+
+You do not need to add AEDT to the global system `PATH` when default discovery
+or one of the explicit environment variables works.
+
+## Common agent workflow
+
+1. Run `sim check hfss`.
+2. Choose GUI mode only when visual review is required; otherwise prefer
+   non-graphical mode.
+3. Connect and inspect the active project/design before mutating anything:
+
+   ```bash
+   sim connect --solver hfss --ui-mode no_gui
+   sim inspect session.summary
+   sim inspect hfss.project.identity
+   sim inspect hfss.design.summary
+   ```
+
+4. Run one bounded PyAEDT snippet at a time.
+5. Inspect `last.result` and design state before solving or exporting.
+6. Validate engineering results from HFSS artifacts and domain criteria, not
+   from process success alone.
+
+## Develop
+
+```bash
+git clone https://github.com/svd-ai-lab/sim-plugin-hfss
+cd sim-plugin-hfss
+uv sync --extra test
+uv run pytest -q
+uv build
+```
+
+The test suite is designed to pass on machines without AEDT/HFSS. Real solver
+smoke testing is opt-in:
+
+```bash
+SIM_HFSS_RUN_INTEGRATION=1 uv run pytest tests/test_hfss_real_smoke.py -q
+```
+
+On PowerShell:
+
+```powershell
+$env:SIM_HFSS_RUN_INTEGRATION = '1'
+uv run pytest tests/test_hfss_real_smoke.py -q
+```
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE) and [LICENSE-NOTICE.md](LICENSE-NOTICE.md).

sim_plugin_hfss-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+sim_plugin_hfss/__init__.py,sha256=bDoiNLlNavh4CTUo5xgb66uwfLNTMt6UhYBJDpW_9ME,635
+sim_plugin_hfss/driver.py,sha256=T-krJ1s86QTAaXThGO6lHxACXlOVbJFHa6NBOVRC_Ls,25945
+sim_plugin_hfss/_skills/hfss/SKILL.md,sha256=A4OWy03nwJFIgzkPMsCqf0YQAPNEP_c1gQoV8qQOXMo,2991
+sim_plugin_hfss-0.1.0.dist-info/METADATA,sha256=KNbNVHuhM687s4wpste_hGAX5he8HZC3wwK3sdyoUkw,5407
+sim_plugin_hfss-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sim_plugin_hfss-0.1.0.dist-info/entry_points.txt,sha256=bTRUUKueORoCaRY2GdE5GUDRD94gD0i6JLNqVCPMNBo,146
+sim_plugin_hfss-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+sim_plugin_hfss-0.1.0.dist-info/licenses/LICENSE-NOTICE.md,sha256=9tQWNY5yY7AvIQ0oSQ1owMkMR0bdAzICXS8qgG1-2NU,542
+sim_plugin_hfss-0.1.0.dist-info/RECORD,,

sim_plugin_hfss-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sim_plugin_hfss-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,8 @@
+[sim.drivers]
+hfss = sim_plugin_hfss:HfssDriver
+
+[sim.plugins]
+hfss = sim_plugin_hfss:plugin_info
+
+[sim.skills]
+hfss = sim_plugin_hfss:skills_dir

sim_plugin_hfss-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

sim_plugin_hfss-0.1.0.dist-info/licenses/LICENSE-NOTICE.md

@@ -0,0 +1,14 @@
+# Notice
+
+This plugin is licensed under Apache-2.0 (see [LICENSE](LICENSE)).
+
+This plugin does not bundle, embed, or redistribute Ansys HFSS, Ansys
+Electronics Desktop, vendor binaries, vendor examples, or vendor license
+files. It is a Python adapter that:
+
+- depends on the PyAEDT Python package, and
+- launches or attaches to an AEDT process that the user has installed and
+  licensed separately.
+
+Users are responsible for satisfying all Ansys software, license, and local
+environment prerequisites before using this plugin to drive HFSS.