shou0715-Arthur/pyaedt-cli

Compétence PyAEDT CLI

Vous avez accès à la CLI pyaedt pour interagir avec ANSYS Electronics Desktop (AEDT). Cette compétence vous apprend à l'utiliser efficacement.

Vérification préalable (à exécuter en premier)

Avant toute commande CLI, vérifiez que pyaedt est installé :

pyaedt --json version

Si la commande échoue, arrêtez-vous et demandez à l'utilisateur de l'installer d'abord en utilisant la cible d'installation all pour activer toutes les fonctionnalités.

pip install pyaedt[all]

---

Appel de la CLI

Avant d'exécuter une commande, localisez le binaire pyaedt une fois :

1. Essayez pyaedt directement. S'il est dans le PATH système, utilisez-le tel quel.
2. S'il n'est pas trouvé, utilisez le binaire local dans l'environnement virtuel du répertoire de travail actuel :
   • Windows : .venv\Scripts\pyaedt
   • Linux/macOS : .venv/bin/pyaedt

Tous les exemples utilisent pyaedt par souci de concision. Remplacez-le par le chemin résolu si nécessaire.

Répertoire de travail pour les artefacts générés

Utilisez des répertoires temporaires pour toutes les exportations et fichiers générés, sauf indication contraire de l'utilisateur.

Règles :

• Créez un sous-répertoire spécifique à la tâche sous le répertoire temporaire du système d'exploitation.
• Utilisez tempfile.mkdtemp(prefix="pyaedt-skill-") (Python), $env:TEMP (Windows), ou ${TMPDIR:-/tmp} (Linux/macOS).
• N'écrivez pas dans le dépôt ou dans des dossiers arbitraires sauf demande explicite.
• Déplacez les artefacts du répertoire temporaire uniquement après une exportation réussie, si l'utilisateur souhaite les conserver.

Référence rapide :

import tempfile

temp_dir = tempfile.mkdtemp(prefix="pyaedt-skill-")

Passez ce chemin à --path ou --output dans les commandes d'exportation.

Utilisez --json pour les commandes non interactives

Utilisez --json pour chaque commande non interactive afin que la sortie reste structurée et lisible par une machine.

La sortie JSON renvoie : {"status": "ok", "data": {...}} ou {"status": "error", "error": "message"}

Analysez toujours le champ status avant d'utiliser data. Ne vous fiez jamais à la sortie lisible par un humain.

Exceptions :

• session attach lance une console interactive, le mode humain est donc acceptable.
• Les commandes doc ouvrent des pages de navigateur et ne sont généralement pas consommées comme une sortie d'automatisation structurée.

Structure actuelle de la CLI

Les commandes sont organisées comme suit :

pyaedt [--json] <groupe> <commande> [options]

Groupes disponibles dans la CLI actuelle :

• session
• project
• script
• export
• test-config
• panels
• doc

Commandes de premier niveau :

• version
• aedt-versions

N'inventez pas d'autres groupes de commandes ou commandes qui n'existent pas dans la CLI actuelle. Si une opération requise n'est pas prise en charge par la CLI, signalez-le à l'utilisateur au lieu d'essayer de contourner le problème.

Modèle basé sur les ports

La CLI actuelle est principalement basée sur les ports.

• session start lance une nouvelle instance AEDT et renvoie son port gRPC.
• session list découvre les instances AEDT en cours d'exécution.
• La plupart des commandes opérationnelles nécessitent --port explicitement.
• session attach peut également être utilisé pour sélectionner une session AEDT existante, notamment par --project ou --design, donc tous les flux de travail ne partent pas d'un port connu.
• Il n'y a pas d'état session connect persistant à réutiliser ultérieurement.

Implication pratique :

# Découvrir ou démarrer AEDT
pyaedt --json session list
pyaedt --json session start --version 2026.1 --non-graphical

# Puis passer --port à la commande souhaitée
pyaedt --json project list --port 50051
pyaedt --json run my_script.py --port 50051

Règles de résolution des projets et des conceptions

Les commandes liées à une conception utilisent un ensemble de règles de résolution partagées. Ceci est important et doit être appliqué de manière cohérente dans les conseils et les exemples.

Commandes concernées :

• export screenshot
• export config
• session attach lorsqu'il est utilisé avec --project ou --design

Règles de résolution :

• Si --project et --design sont fournis, utilisez-les directement.
• Si seul --project est fourni, ce projet doit contenir exactement une conception.
• Si seul --design est fourni, exactement un projet doit être ouvert.
• Si aucun n'est fourni, il doit y avoir exactement un projet ouvert et exactement une conception dans ce projet.
• Si la sélection est ambiguë, la commande échoue et le sélecteur manquant doit être fourni.

Lorsque vous aidez un utilisateur, ne décrivez pas ce comportement comme un recours au "projet actif" ou à la "conception active" à moins que la commande n'utilise effectivement ce comportement. Le comportement attendu est une résolution basée sur l'unicité.

Référence des commandes

Commandes de premier niveau

Commande	Description
pyaedt --json version	Affiche la version de PyAEDT
pyaedt --json aedt-versions	Liste les versions d'AEDT installées sur la machine

Gestion des sessions

Commande	Description
pyaedt --json session start --version 2026.1 [--port 50051] [--non-graphical]	Démarre une nouvelle instance AEDT
pyaedt --json session list	Liste les instances AEDT en cours d'exécution avec PID, version et port
pyaedt --json session stop --port 50051	Arrête une instance AEDT spécifique par port
pyaedt --json session stop --all	Ferme toutes les instances AEDT
pyaedt session attach [--port 50051] [--project NOM] [--design NOM]	Lance une console PyAEDT interactive attachée à une instance en cours d'exécution

Notes :

• session attach peut fonctionner de manière interactive si --port est omis et que l'utilisateur sélectionne une instance.
• --project ou --design avec session attach ne fonctionne qu'avec les instances gRPC disposant d'un port utilisable.

Commandes de projet

Le port est requis pour toutes les commandes de projet afin de spécifier l'instance AEDT cible.

Commande	Description
pyaedt --json project list --port 50051	Liste tous les projets ouverts et leurs conceptions
pyaedt --json project open "C:/chemin/vers/fichier.aedt" --port 50051 [--non-graphical]	Ouvre un fichier projet AEDT
pyaedt --json project save --port 50051 [--path "C:/nouveau/fichier.aedt"]	Sauvegarde le projet actif, éventuellement sous un nouveau nom
pyaedt --json project create --name ProjetA --port 50051	Crée un projet. Utilisez --name.
pyaedt --json project create --project ProjetA --design Conception1 --type Hfss --port 50051	Crée une conception dans un projet existant. Utilisez --project + --design + --type.
pyaedt --json project close --port 50051 [--project ProjetA]	Ferme un projet, ou le projet actif s'il est omis

Comportement de project create :

• --name est pour la création de projet.
• --project + --design + --type est pour la création de conception.
• Ne mélangez pas --name avec --design / --type.

Valeurs --type prises en charge :

• Hfss
• Maxwell2d
• Maxwell3d
• Q3d
• Q2d
• Icepak
• Circuit
• TwinBuilder
• Mechanical
• Emit
• Rmxprt
• Hfss3dLayout
• MaxwellCircuit

Commandes de script

Commande	Description
pyaedt --json run "chemin/vers/script.py" --port 50051	Exécute un script Python dans AEDT

Commandes d'exportation

Commande	Description
pyaedt --json export screenshot --port 50051 [--path apercu.jpg] [--project NOM] [--design NOM]	Capture une capture d'écran pour une conception résolue
pyaedt --json export config --port 50051 [--output config.json] [--project NOM] [--design NOM] [--overwrite]	Exporte une configuration de conception au format JSON

Les deux commandes sont liées à une conception et suivent donc les règles de résolution projet/conception partagées ci-dessus.

Documentation

Commande	Description
pyaedt doc	Ouvre la page d'accueil de la documentation et affiche l'aide
pyaedt doc examples	Ouvre la section des exemples
pyaedt doc github	Ouvre le dépôt GitHub
pyaedt doc user-guide	Ouvre le guide de l'utilisateur
pyaedt doc getting-started	Ouvre la documentation de démarrage
pyaedt doc installation	Ouvre la documentation d'installation
pyaedt doc api	Ouvre la référence API
pyaedt doc changelog [VERSION]	Ouvre le journal des modifications
pyaedt doc issues	Ouvre la page des problèmes
pyaedt doc search <mots-clés>	Recherche dans la documentation en ligne

Flux de travail courants

Flux de travail 1 : Découvrir ou démarrer AEDT

# Vérifier les instances en cours d'exécution
pyaedt --json session list

# Si aucune n'est en cours, en démarrer une
pyaedt --json session start --version 2026.1 --non-graphical

Règle de décision :

• Si session list ne renvoie aucun processus, démarrez AEDT.
• S'il renvoie un seul processus, réutilisez ce port.
• S'il renvoie plusieurs processus, demandez à l'utilisateur quel port utiliser.

Flux de travail 2 : Inspecter les projets sur un port

pyaedt --json project list --port 50051

Utilisez ceci en premier lorsque vous devez comprendre quels sélecteurs de projet et de conception sont requis.

Flux de travail 3 : Créer un projet ou une conception

# Créer un projet. Utilisez --name UNIQUEMENT (n'ajoutez PAS --design ou --type)
pyaedt --json project create --name "AntennePatch" --port 50051

# Créer une conception dans un projet existant. Utilisez --project + --design + --type UNIQUEMENT (n'ajoutez PAS --name)
pyaedt --json project create --project "AntennePatch" --design "ConceptionHFSS1" --type Hfss --port 50051

Flux de travail 4 : Exploration interactive avec session attach

Utilisez session attach comme premier choix lorsque l'utilisateur souhaite explorer, déboguer ou itérer sur une conception de manière interactive. Cela ouvre une console Python interactive déjà connectée à la session AEDT cible. desktop est pré-injecté, donc les commandes PyAEDT peuvent être émises une par une sans écrire un script complet.

# Attacher à une instance en cours d'exécution (port optionnel ; invite si omis)
pyaedt session attach --port 50051

# Dans la console Python interactive, la session est déjà active :
# >>> import ansys.aedt.core as aedt
# >>> hfss = aedt.Hfss(new_desktop=False, port=50051)
# >>> boite = hfss.modeler.create_box([0, 0, 0], [10, 10, 10], name="MaBoite")
# >>> hfss.modeler["MaBoite"].color = (255, 0, 0)

Envoi de code multiligne à la console Python interactive

Lorsque l'agent envoie du code à la console Python interactive qui s'étend sur plus d'une ligne (boucles, conditions, définitions de fonctions, etc.), le coller directement provoque une IndentationError ou une SyntaxError car la console traite chaque ligne comme une entrée distincte.

Enveloppez toujours les blocs multilignes dans exec(), en encodant tous les sauts de ligne sous forme de \n dans une seule chaîne :

# Échoue car la console s'arrête sur le corps de la boucle
for i in range(3):
    print(i)

# Correct : envoyez comme un seul appel exec()
exec("for i in range(3):\n    print(i)")

Règles :

• Utilisez exec() pour tout bloc contenant du code indenté (boucles, if, with, définitions de fonctions ou de classes).
• Les lignes à instruction unique (imports, affectations, appels de fonctions) n'ont pas besoin de exec().
• Échappez tous les guillemets doubles internes avec \" si le délimiteur externe est ", ou utilisez des littéraux de chaîne concaténés comme indiqué ci-dessus.
• Gardez les appels exec() aussi courts que possible ; si le bloc dépasse environ 10 lignes, préférez sauvegarder un script temporaire et utiliser run à la place.

Quand préférer la commande session attach à la commande run :

Situation	Approche préférée
Exploration de l'état d'une conception, objectif inconnu	session attach
Débogage interactif d'une étape qui échoue	session attach
Ajustements ponctuels de géométrie/paramètres	session attach
Itération rapide sur quelques commandes	session attach
Flux de travail défini, reproductible et en plusieurs étapes	run
Pipeline CI / sans tête / automatisé	run
Flux de travail comportant plus de 5 étapes	run
Traçabilité et journalisation requises	run

Préférez session attach en premier. Passez à run une fois que le flux de travail est connu et doit être reproductible ou automatisé.

Travailler avec plusieurs conceptions simultanément

Lorsque l'utilisateur doit travailler sur plus d'une conception en même temps, ouvrez une console Python interactive séparée pour chaque conception au lieu de basculer entre les conceptions dans une seule console. Cela maintient chaque conception active et modifiable sans fermer ni libérer aucune d'entre elles.

# Terminal 1 : console pour la Conception A
pyaedt session attach --port 50051 --project "ProjetA" --design "ConceptionA"

# Terminal 2 : console pour la Conception B (même projet ou projet différent)
pyaedt session attach --port 50051 --project "ProjetA" --design "ConceptionB"

# Terminal 3 : console pour une conception dans un projet différent
pyaedt session attach --port 50051 --project "ProjetB" --design "ConceptionC"

Règles :

• Chaque console possède son propre objet PyAEDT lié à une conception spécifique. Fermer une console ne ferme pas les autres.
• Toutes les consoles partagent la même instance AEDT (même --port), donc les modifications apportées dans l'une sont immédiatement visibles dans AEDT.
• N'appelez pas desktop.release_desktop() ou aedt_app.release_desktop() dans l'une de ces consoles, sauf si vous souhaitez intentionnellement arrêter AEDT pour toutes les consoles ouvertes.
• Si les conceptions se trouvent dans différentes instances AEDT, utilisez le --port correspondant pour chaque console.

Flux de travail 5 : Exécuter une automatisation

pyaedt --json run "<temp-dir>/configurer_antenne.py" --port 50051

Flux de travail 6 : Exécution d'un script généré

Utilisez ce flux de travail chaque fois qu'un script a été généré et doit être exécuté automatiquement.

# Étape 1 : découvrir les instances
pyaedt --json session list

# Étape 2 : si nécessaire, en démarrer une
pyaedt --json session start --version 2026.1 --non-graphical

# Étape 3 : exécuter le script sur le port choisi
pyaedt --json run "<temp-dir>/script_genere.py" --port 50051

Règles :

• Déterminez toujours le port cible en premier.
• Si plusieurs instances sont en cours d'exécution, présentez la liste complète et demandez quel port utiliser.
• Ne dites pas à l'utilisateur d'exécuter le script généré manuellement si le flux de travail nécessite une exécution automatique.
• Les scripts générés destinés à une instance AEDT existante doivent utiliser new_desktop=False.

Flux de travail 7 : Exporter les données de conception

# Si l'instance a exactement un projet et une conception, les sélecteurs peuvent être omis
pyaedt --json export screenshot --port 50051 --path "<temp-dir>/apercu.jpg"
pyaedt --json export config --port 50051 --output "<temp-dir>/config.json" --overwrite

# En cas d'ambiguïté, spécifiez le(s) sélecteur(s) manquant(s)
pyaedt --json export screenshot --port 50051 --project "AntennePatch" --design "ConceptionHFSS1" --path "<temp-dir>/apercu.jpg"
pyaedt --json export config --port 50051 --project "AntennePatch" --design "ConceptionHFSS1" --output "<temp-dir>/config.json" --overwrite

Bonnes pratiques

• Privilégiez toujours les répertoires temporaires pour les artefacts générés afin d'éviter d'encombrer l'espace de travail de l'utilisateur.
• Utilisez l'option --json pour automatiser l'analyse des résultats des commandes ; réservez le mode sans --json pour les sessions interactives (session attach).
• Lorsque vous utilisez session attach avec du code multiligne, encapsulez toujours les blocs indentés dans exec() pour éviter les erreurs de syntaxe.
• Pour les flux de travail en plusieurs étapes ou reproductibles, préférez la commande run à session attach.
• Ne présumez jamais de l'existence d'un projet ou d'une conception "actif" ; utilisez plutôt les règles de résolution explicites basées sur l'unicité.