Running Ansys Electronics Desktop from a Command Line (Nongraphical) Beta

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

ansysedtng <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. BatchSolve 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 -Help option. The commands are further described below:

• -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:

  • Only the scripts listed above are supported for -BatchExtract. Including unsupported script commands will terminate script execution.
• -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 -Logfile 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>:<GPUsOnMachine>

      Duplicate machine names are not permitted. The integer for <CoresOnMachine> must be greater than the integer for <TasksOnMachine>. 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>:<GPUsOnMachine>

      Duplicate machine names are not permitted. The integer for <CoresOnMachine> must be greater than the integer for <TasksOnMachine>. 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.
• -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.

Run Command Examples

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

C:\Program Files\ANSYS Inc\v252\AnsysEM\ansysedtng -distributed -machinelist list="255.255.1.1,255.255.1.2" -batchsolve myDesign:Optimetrics "C:\myProject.aedt"

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

ansysedtng -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 Burst Computing 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.
• -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.
• -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.
• -waitforlicense – directs Electronics Desktop to wait for unavailable licenses.

-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.

-Batchoptions Examples

The batchoption CreateStartingMesh is available for the following products:

HFSS, 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:

ansysedtng -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 2025 R2 installed on shared directories or network drives. See: Example Uses for Export Options Features.