Running Ansys Electronics Desktop from a Command Line

Ansys Electronics Desktop includes line arguments that can be included when launching from a command line or terminal prompt. All command-line arguments are case-insensitive. The commands associated batch options can also be used with a Job Management Interface for submitting jobs to Ansys or RSM and other supported schedulers.

Command-line Syntax

ansysedt <options> <run command(s)> <project file/script file>

It is good practice to put quotation marks around the path to the solver executable, and around the full path to the project. This ensures that spaces in the path or project will not be an issue. The same is true of the design name, if there are spaces.

Run Commands

The following command line run commands are available for Ansys Electronics Desktop. Of the commands (BatchSave, BatchSolve, BatchExtract, RunScript, RunScriptandExit), one or none must be specified as arguments after the solver executable. When none is specified, you may specify a project or archive to open when Electronics Desktop launches, and can only use the -Iconic and -Help options. The commands are further described below:

• -BatchSave [options] <file or folder specifier>

  Saves a named project or folder containing one or more project files or folders to the current version. This can be helpful for the change from ACIS to Parasolid. The Parasolid migration of aedt projects does not overwrite the existing project. Instead a copy is created through save-as with _converted suffix and then that copy is migrated to Parasolid.You can run this command with the -Iconic, -Logfile, and -ng options.

  If migration from ACIS to Parasolid is needed, and –outputfolder is not specified, the original file will be saved in the AnsysEM_Backup subdirectory (located in the same directory as the project being opened). Then, the file being opened will be overwritten with the migrated file. (If –outputfolder is specified, the original files are not modified because the modified files would be written to the output folder.)

  If no migration is necessary (e.g. a project containing a circuit design). The original file will be overwritten with the new version, and no backup will be made.

  Special behavior when opening backed up files from the user interface. Files located in the AnsysEM_Backup directory would be the original non-migrated files that were backed up during an earlier –batchsave or open. Opening a file located in the AnsysEM_Backup directory via the open file dialog will invoke the Parasolid migration, and the migrated file will be saved in the parent folder of the AnsysEM_Backup folder with a unique name so as not to overwrite any existing files.

  If a file is given, -batchsave will run on the specified file.

  If a folder is given, -batchsave will run on all files underneath the specified folder.

  .aedt, .aedtz, and .a3dcomp files will be processed.

  Allowed options:

  norecurse: only process files in top level of input folder

  forcearchive: project files are converted, then saved as archive files.

  previewonly: don't perform actual conversion, instead write preview of filenames to batchlog.

  outputfolder=<outputfolder>: save converted files to <outputfolder>, preserving subfolder structure.

  preservehistory=<true or false>: preserve geometry history during migration.

• -BatchSolve <project file name>

  By default, this run command solves all adaptive setups, Optimetrics setups, and sweeps found in the project file. You can run this command with the -Iconic, -Logfile, -ng, and -WaitForLicense options. If parallel solve is possible, you can use the -Distribute option.

  If you wish to specify which setups -BatchSolve completes, you can use additional parameters:

  • [designName] – batch solve all setups for the specified design in the project file.
  • [designName]:Nominal – batch solve all nominal setups for the specified design in the project file.
  • [designName]:Optimetrics – batch solve all Optimetrics setups for the specified design in the project file.
  • [designName]:[Nominal/Optimetrics]:[SetupName] – batch solve the specified Nominal or Optimetrics setup in the specified design.

  If you wish to specify whether -BatchSolve setups are completed locally or remotely, you can use the following options:

  • -Local – performs the -batchsolve on the local machine.
  • -Remote -machineList – performs the -batchsolve on a remote machine. The <machineList> should provide a single hostname.
  • -Distributed -machineList – performs a distributed -batchsolve using a specified machine list.

    The -machineList parameter for a -Distributed setup can be formatted three ways:

    • -MachineList list= "<machine1>, <machine2>, ..." – machine names (either by IP address or hostname) are separated by commas. If the list contains any whitespace, it must be enclosed in quotation marks. The number of distributed COM engines run on each host is equal to the number of times the hostname appears in the list. That is, if host1 appears in the list once, and host2 appears twice, then one COM engine will run on host1 and two COM engines will run on host2.

      list= accepts the following additional modifiers:

      <MachineName>:<TasksOnMachine>:<CoresOnMachine>:<RAM Limit in %>:<GPUsOnMachine>

      Duplicate machine names are not permitted. The integer for <CoresOnMachine> must be greater than the integer for <TasksOnMachine>. RAM% must be of the form "<num>%" where num is an integer between 1 and 99. Please be sure to leave sufficient RAM for the operating system and applications. If -auto is specified with a machine list, the number of tasks for each machine must be -1.

      Example:

      list="Orion:4:8:90%:1, Aries:3:12, Pluto:6:12"

      Note:

      Duplicate machines are not allowed when specifying these additional modifiers. The number of cores must be greater than the number of tasks.

    • -MachineList file= "<machineListFilepath>" – machine names (either by IP address or hostname) are listed in a file (one per line), and you specify the filepath. The number of distributed COM engines run on each host is equal to the number of times the hostname appears in the file. That is, if host1 appears in the file once, and host2 appears twice, then one COM engine will run on host1 and two COM engines will run on host2.

      file= accepts the following additional modifiers, in the file itself:

      <MachineName>:<TasksOnMachine>:<CoresOnMachine>:<RAM Limit in %>:<GPUsOnMachine>

      Duplicate machine names are not permitted. The integer for <CoresOnMachine> must be greater than the integer for <TasksOnMachine>. RAM% must be of the form "<num>%" where num is an integer between 1 and 99. Please be sure to leave sufficient RAM for the operating system and applications. If -auto is specified with a machine list, the number of tasks for each machine must be -1.

      Example:

      "Orion:4:8:90%:1",

      "Aries:3:12",

      "Pluto:6:12",

      Note:

      Duplicate machines are not allowed when specifying these additional modifiers. The number of cores must be greater than the number of tasks.

    • -MachineList num= "<numberofDistributedEngines>" – This format is used when a scheduler (such as LSF, PBS, SGE or HPC) is used to manage the jobs sent to a cluster of hosts. In a scheduler environment, you can specify the number tasks for distributed processing. In this case, you do not specify the machine names after the flag because the names are provided by the scheduler. For example, in the Windows HPC environment, you can write the number of tasks as follows:

      -MachineList num=4

    Distributed setups can also take the following optional arguments. When these are not present, the behavior defaults to single-level distributed solutions with no change in order of precedence among possible distribution types.

    The arguments are:

    • includeTypes= <default>|<distribution type 1, distribution type 2, ...> – If included distribution types are specified, only the listed distribution types are enabled. If default is specified, the default set of enabled distribution types is used. To see valid distribution types for your design, click Simulation > Analysis Config to open the Analysis Configuration window and view the types on the Job Distribution tab.
      
      If the list contains any whitespace, it must be enclosed in quotation marks. For example:
      "includeTypes=Frequencies,Mesh Assembly"
      
    • excludeTypes= <default>|<distribution type 1, distribution type 2, ...> – If excluded distributed types are specified, all distribution types except those listed will be enabled. If default is specified, the default set of enabled distribution types is used. To see a valid distribution types for your design, click Simulation > Analysis Config to open the Analysis Configuration window and view the types on the Job Distribution tab.
      
      If the list contains any whitespace, it must be enclosed in quotation marks. For example:
      "excludeTypes=Frequencies,Mesh Assembly"
      
    • maxLevels= <1 | 2> – the maximum number of levels of job distribution (the current maximum is 2). See: Selecting Optimal Configurations for Distributed Analysis.
    • numLevel1= – when two-level distribution is selected (maxLevels=2), this specifies the number of level 1 tasks.

  -Auto [NumDistributedVariations=<num>]

  This flag enables automatic HPC settings and must be used with one of the following options:

  • -machinelist list=<machine list>, with tasks for each machine set to -1
  • -machinelist numcores=<num>, under a scheduler

  All design types being solved must support -auto or the solve will be aborted.

  The NumDistributedVariations option can be used to specify the number of optimetrics variations to solve simultaneously. The default is to solve optimetrics variations sequentially.

  Arguments with -auto in a scheduler environment:

  • numcores=<total number of cores>

    Total number of cores, and can be used only with -auto and in a scheduler environment.

  • file="<tmachine list file path>"

    The specified file can contain line delimited machine specifiers as described above.

  • num=<tnum distributed tasks>

    This is the total number of tasks and used only in a scheduler environment.

  • numgpus=<tnumber of GPUs to use>

    This is the total number of GPUs and used only in a scheduler environment. numgpus must be combined with either num= or numcores=.

    You can also specify how a -BatchSolve distributes Optimetrics variations:

  • -auto – Without additional parameters, the batch log file will specify that Optimetrics variations be solved sequentially. If -auto is specified with a machine list, the number of tasks for each machine must be -1.
  • -auto NumDistributedVariations=<num> – You can specify an integer value greater than 1. This is the number of variations that will be solved in parallel.
• -BatchExtract <BatchExtract script file name> <project file name> – allows the following commands to be executed non-graphically via script and without checking out any GUI licenses:
  • ExportProfile
  • ExportConvergence
  • ExportMeshStats
  • ExportNetworkData
  • ExportNMFData
  • ExportEigenmodes
  • ExportTransientData
  • Update Reports
  • ExportToFile

  A project file must be specified when -BatchExtract is used. Commands in the script file will only be executed in the specified project.

  Important:

  • -ng must be used with -BatchExtract, or it will fail.
  • Only the scripts listed above are supported for -BatchExtract. Including unsupported script commands will terminate script execution.
• -RunScript <script file name> – runs the specified script. You can use the -ScriptArgs option to add one or more arguments to this command, and the -Iconic option.
• -RunScriptAndExit <script file name> – runs the specified script and exits Electronics Desktop. You can use the -ScriptArgs option to add one or more arguments to this command. You can also use -Iconic, -Logfile, and -WaitForLicense.
  Note:

  -BatchSolve <DesignName> is mutually exclusive with -RunScriptAndExit <ScriptName>.

• -monitor – during non-graphical analysis, you can monitor progress and messages. Progress, warning and info messages are logged to the standard output stream. Error and fatal messages are logged to the standard error stream. Schedulers intercept these streams and provide commands for display of this output. See individual scheduler documentation for specifics.

• -grpcsrv – For external cpython scripting support. If not specified with ansysedt.exe, the Start GRPV server listens on a port in the default range 50051:51051. If specified, Start GRPV server listening on the the specified port number. An error is issued if the port is already used. For example:

ansysedt.exe // Start GRPV server listening on a port in the default range 50051:51051.

ansysedt.exe -grpcsrv portnumber // Start GRPV server listening on the the port number. error if the port already used.

ansysedt.exe -grpcsrv 50051:50150 // Start GRPV server listening on a port range 50051:50150.

ansysedt.exe -grpcsrv 50051:100 // Start GRPV server listening on a port range 50051:50151.

Job Management from the Command Line

• -showmonitorjob – Launch the monitor job dialog.
• -showsubmitjob – Launch the submit job dialog.
• -showselectscheduler – Launch the select scheduler dialog.

Run Command Examples

A distributed -BatchSolve of a specified design's Optimetrics setups, with a specified machine list:

C:\Program Files\AnsysEM\v242\Win64\ansysedt -distributed -machinelist list="255.255.1.1,255.255.1.2" -batchsolve myDesign:Optimetrics "C:\myProject.aedt"

A -BatchExtract operation using paths to a script file and a project file:

ansysedt -ng -batchextract exportToFile.py "C:\Program Files\AnsysEM\v242\Win64\Examples\ElectronicsDesktop\HFSS\RF Microwave\OptimTee.aedt"

Where exportToFile.py contains:

oDesktop.RestoreWindow()

oProject = oDesktop.SetActiveProject("OptimTee")

oDesign = oProject.SetActiveDesign("HFSSDesign1")

oModule = oDesign.GetModule("ReportSetup")

oModule.UpdateReports(["XY Plot 1"])

oModule.ExportToFile("XY Plot 1", "exportToFilePy.csv")

A -BatchSolve of a specified design's nominal setups, run in a minimized window, with a specified log file:

ansysedt -Iconic -LogFile "H:\Logs\mylog.log" -BatchSolve myDesign:Nominal "H:\Projects\MyProject.aedt"

Specifying Project Files

Specifying a project file opens that project when Electronics Desktop launches. If -BatchSolve is set, the project will also be solved.

You can specify an archive file instead of a project file. If -Batchsolve is set, the project will be automatically restored and solved. Otherwise, you are prompted for a restore location, and the project will be restored and opened.

When a -Batchsolve is being performed on an archive file, you may also specify -archiveoptions:

• overwritefiles – allows non-project/results-extracted files to overwrite existing files.
• path= <projectFilepath> – extracts the project file and associated files to the specified path. If not specified, the archive will be extracted into the same directory as the archive file.
• repackageresults – Add batchsolve results back to archive file.
• winpath= <windowsProjectFilepath> – specifies the Windows-specific path to the extracted project file. This is used when a batch job is to be run on a Linux system, but monitored on Windows.

Options

The following options can be associated with one or more of the run commands:

• -autoextract – exports profile (as text), convergence (as text), and report data (as CSV) for the requested project/design/setup in a batch job. Once the solve is complete, an export directory is created (for example, "Project1.aedtexport" for a project named "Project1.aedt") that contains a sub-directory for each design name. You can also specify -autoextract “reports, fieldplots” to also generate *.aedtplt files for each field plot and possible *.avz file (for import and display in Ensight) for all valid field plots. Export files reside within each design-name directory, and include setup name, design variation, job ID, and problem type, as applicable.
  Note:

  • The -autoextract option is only valid when used with -BatchSolve
  • The -autoextract option is automatically added for all Ansys Cloud Direct jobs submitted from Electronics Desktop. There is also an additional "reports" and/or "fieldplots" option that immediately follow "-autoextract". This causes all reports to be exported as CSV files at the end of the batch solve, after the profile and convergence have been exported.
  • For example, you can specify -autoextract “reports, fieldplots” to also generate *.aedtplt files for each field plot and possible *.avz file for all valid field plots.
• -batchoptions – for batch jobs, specifies any of the options in Tools > Options. See additional information.
• -batchoptionhelp – opens a window showing -batchoptions help. The paths shown in this window can be used with batchoptions and the Update Registry Get and Set commands. See: Setting or Removing Option Values in Configuration Files: UpdateRegistry Command.
• -distribute – distributes a batch solve to multiple machines. This option must be combined with the -BatchSolve run command. See: Distributed Analysis.
• -help – opens a window displaying command line options. This can only be used without a run command.
• -iconic – runs Electronics Desktop with the window iconified (minimized).
• -logfile <filePath> – specifies a log file. If none is specified, <project_name>.log will be written to the <project_name>.batchinfo directory.
• -monitor – enables batch job output to standard output and standard error streams.
• -ng – runs Electronics Desktop in non-graphical mode. This must be used with the -BatchExtract command.
• -validateonly – If true, validation will be performed, but none of the setup will be solved. Allowed values: true, "= 1", false, "= 0".
• -waitforlicense – directs Electronics Desktop to wait for unavailable licenses.
• -scriptargs – used in conjunction with -RunScript or -RunScriptAndExit, adds arguments to the specified script. You can pass multiple arguments to -scriptargs by surrounding the arguments in quotation marks. For example:

  ansysedt.exe -scriptargs "Design1 Setup1" -RunScriptAndExit C:\temp\test.py

  In Python, the command line parameter following -scriptargs is passed without modification as a single string in the ScriptArgument python variable.

  In VBscript, the command line parameter following -scriptargs is split into multiple strings and converted to a VBscript collection which is accessible via the AnsoftScript.Arguments collection. To access these arguments, for example:

  msgbox AnsoftScript.Arguments(0) // Returns Design1

  msgbox AnsoftScript.Arguments(1) // Returns Setup1

  In either case, Design1 is taken into Electronics Desktop as the first argument, and Setup1 as the second argument. If you failed to use quotation marks, Design1 would be taken as the first argument and Setup1 would not be understood by Electronics Desktop.

-Batchoptions

All options that are specified through Tools > Options go into the user-level registry.

You can override the option registry entries via the -batchoptions command line. These overrides apply only to the current Desktop session. The registry setting overrides may be specified on the command line, or may be in a file with the file pathname specified on the command line. Batch jobs can be submitted from the command line or through Electronics Desktop's job submission window.

Large Scale DSO offers two new batchoptions related to the redistribution ability.

• LargeScaleDSO/VarRedistribution, where 0 disables redistribution (default), and 1 enables it.
• LargeScaleDSO/RedistributionLimit, is a positive integer specifying the minimum estimated remaining time (in minutes) for variations to redistribute to another task. The default is 3.​

-Batchoptions Examples

The batchoption CreateStartingMesh is available for the following products:

HFSS, HFSS-3DLayout, Icepak, Q3D, Q2D, Maxwell3D, Maxwell2D, and Mechanical.

When this option is set, only the initial mesh and manual mesh operations are completed for the batch solution.

This example enables CreateStartingMesh for HFSS, and runs a batch solution of the specified project:

ansysedt -batchoptions "'HFSS/CreateStartingMesh'=1" -batchsolve "D:\projects\MyProject.aedt"

See: Additional Examples of -Batchoptions Use.

Export Options Files

The Tools > Options > Export Options Files command writes XML files containing the options settings at all levels to the specified directory. This feature is intended to make it easier for different users to use Ansys Electromagnetics Suite 2024 R2 installed on shared directories or network drives. See: Example Uses for Export Options Features.