Running Maxwell 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. For more information, see the following:

RSM Integration with Job Management UI

Integration with Microsoft Windows® HPC Scheduler

Integration with Platform's Load Sharing Facility (LSF)

Integration with Grid Engine (GE)

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.

• -BatchSolve <project filename>

  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 batch solve on the local machine.
  • -Remote -machineList – performs the batch solve 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>:<NumTasks>:<NumCores>:<RAM Limit in %>:<Number of GPU>

      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>:<NumTasks>:<NumCores>:<RAM Limit in %>:<Number of GPU>

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

  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.
  • -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 filename><project filename> – 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
  • UpdateReports
  • ExportToFile

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

  Note:

  • -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 filename> – 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 filename> – 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.

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 "%UserProfile%\Documents\Ansoft\myProject.aedt"

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

ansysedt -ng -batchextract exportToFile.py "C:\Program Files\AnsysEM\AnsysEM24.2\Win64\Examples\ElectronicsDesktop\Maxwell\Actuators\Solenoid.aedt"

Where exportToFile.py contains:

oDesktop.RestoreWindow()

oProject = oDesktop.SetActiveProject("Solenoid")

oDesign = oProject.SetActiveDesign("MaxwellDesign1")

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.
• 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.
• >-useElectronicsPPE – selects Electronics Pro/Premium/Enterprise licensing. Allowed values: <none>, true, "= 1", "=0", false.
• -validateonly – If true, validation will be performed, but none of the setup will be solved. Allowed values: 0 (false), 1 (true).
• -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 "MaxwellDesign1 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 MaxwellDesign1

  msgbox AnsoftScript.Arguments(1) // Returns Setup1

  In either case, Design1 is taken into Maxwell 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 Maxwell.

-Batchoptions

All options that are specified through Tools > Options go into the user-level registry. You can override these 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 all 3D products (HFSS, HFSS-3DLayout, Q3D, Q2D, Maxwell 3D, and Maxwell 2D). When this option is set, only the initial mesh and manual mesh operation making portion of the setup are completed for the batch solve.

This example enables CreateStartingMesh for HFSS, and runs a batch solve on 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.

Related Topics 

Running a Script