SYMMIC Users Manual CapeSym

Command Line Utility

Simulations can be performed without the graphical user interface (GUI) by using the xSYMMIC command line utility. This console version of SYMMIC runs the simulation of a template file given as the next argument on the command line.


The above command performs the thermal simulation of the problem defined by the template file “FET.xml” and stores the solution in a file named “FET.rst”. The greater than sign (>) signifies the Windows command prompt. The command line only accepts template files that end with the .xml suffix.

Note: To use the above syntax you may need to modify the Path environment variable to include the directory where the SYMMIC program files are located.

> set Path=%Path%;C:\Program Files\SYMMIC

During normal (successful) execution the command line output is essentially the same as the messages that appear in the console when the GUI is used. When an error occurs during command line execution, a message will be displayed noting the nature of the error and the xSYMMIC command will return zero on Windows (1 signals failure on Linux). A non-zero value will be returned when the command line completes execution successfully on Windows (0 signals success on Linux).

Command line execution allows you to run a sequence of simulations on various template configurations and then examine the results later, after the simulations have all completed. Start by configuring templates with the GUI and saving them to template files with different names. Then create a Windows batch file to apply xSYMMIC to each template in turn. For example, the following batch file sets a local path variable and then uses this path to solve the problems defined by templates “FET1.xml” and “FET2.xml”.

> more FETs.bat
@echo off
:: An example batch file on multiple templates
set xpath="C:\Program Files\SYMMIC\xSYMMIC.exe"
echo Running Template #1 : FET1.xml
%xpath% FET1.xml > FETs_msgs.txt
echo Running Template #2 : FET2.xml
%xpath% FET2.xml >> FETs_msgs.txt

On line 6 it is important that the full path to the xSYMMIC executable be surrounded by quotes because of the space in the path string. Progress and error messages are written to the console during execution, but the messages can be redirected to a file if desired. The greater than sign (>) in line 10 of the batch file redirects the output from the first simulation run to a file named FETs_msgs.txt. The second simulation uses the symbols (>>) to append output to the end of the FETs_msgs.txt file created for the first simulation.

Command Line Options

If xSYMMIC is unable to parse the command line or recognize the input file type, then the only output displayed will be a message that explains the expected syntax and comand line options. This message can also be displayed by using the /h or -? flags.

> xSYMMIC -?

SYMMIC solves the non-linear heat conduction equation in parallel on template
input files using OpenMP, MPI and PETSc (if available, v. 3.9 or greater).

Non-MPI usage: xSYMMIC <templatefile.xml> [flags]
MPI usage: mpiexec -n <# of processes> -ppn <processes per node>
                        -hostfile <hostfile> xSYMMIC <templatefile.xml> [flags]
  -e : export instead of solving the layout
  -h : display this help message
  -i[=] <filename.csv> : CSV parameter import file name
  -i= : line number to read the parameters from in the CSV file
              (otherwise solve every line of the import file in sequence)
  -c[=i] <filename.htm> : save component temperatures to HTML file
  -c[=i] <filename.csv> : save component temperatures to CSV file
              (-c=i will append the line number from the import file)
  -o[=i] <filename.dat> : save solution in Tecplot format
  -o[=i] <filename.csv> : save solution in CSV format
  -o[=i] <filename.rst> : save solution in binary format
              (-o=i will append the line number from the import file)
  -p[=i] <filename.dat> : save max. temperature plot in Tecplot format
  -p[=i] <filename.csv> : save max. temperature plot in CSV format
              (-p=i will append the line number from the import file)
  -px=<double> : replace max. plot in -p file with temperature at x = 
  -py=<double> : replace max. plot in -p file with temperature at y = 
  -pz=<double> : replace max. plot in -p file with temperature at z = 
  -s=<int> : superposition parallelization level (1,2) (default is 1)
  -usePetsc : use the PETSc library if available (default is false)
              (Conjugate Gradient iterative solver is the default)
  -v : print version number of release
  -z : run steady then unsteady for thermal impedance

Parallel performance is generally optimum when all of the physical cores of
the CPU are used. SYMMIC uses a hybrid of MPI and OpenMP parallelism, and
each of its solvers has their own optimum parallel settings, as follows.
   Pardiso : mpiexec -n 1 (OMP_NUM_THREADS = max) -s=1
   Pardiso : mpiexec -n  (OMP_NUM_THREADS = 1) -s=2
   PETSc : mpiexec -n  (OMP_NUM_THREADS = 1) (-s=1 or 2) -usePetsc
Note that hyperthreaded CPUs have two threads per physical core, but
performance will suffer if these additional threads are assigned. The
environmental variable OMP_NUM_THREADS sets the number of OpenMP shared memory
threads used by each MPI process, and the variable MKL_NUM_THREADS sets the
number of shared memory threads for MKL, but it is best to leave both of these
undefined to give the most flexibility. OpenMP and MKL will use all of the
physical cores by default, or one can use a machine file (-machine ) to
specify core usage on each cluster node when running with MPI. Linux parallel
cluster runs need to be in an NFS (Network File System) directory and have
xSYMMIC installed on every node.

As the help message shows, the command line may include options for parameter input, alternative outputs, and parallel processing, to be discussed below and in the Parallel Computation section. Command line options are expected to appear after the template filename. Either the forward slash (/) or the hyphen (-) are accepted for all command line options on Windows. For Linux, only the hyphen is accepted. The -v flag may be used by itself to get the version of xSYMMIC without running a simulation.


SYMMIC 64-bit Version 3.0.2
Trademark (TM) 2008 CapeSym, Inc.
Copyright (C) 2007 - 2018 CapeSym, Inc.

/e for Export

The xSYMMIC utility always records temperature values (according to the specifications in the template) and always writes a solution file when a simulation is done. The solution file is automatically given the template name with a .rst file extension by default. If the /e flag is specified and the input file is a layout template, then the export operation specified by the <Export> tag in the template will be performed instead of computing a temperature solution. The export operation converts the layout into a device template, as detailed elsewhere. When the export operation is performed all of the other output flags are ignored. The only output is the device template file resulting from the export operation. The export tag may be added to the layout template by using the Create Device Template from Layout dialog in the GUI.

/i for Input

The input option allows a template's parameters to be modified from a spreadsheet that is stored in comma separated values format. Each line of the .csv file contains all of the parameter changes for a simulation. When the /i flag is used without a specific number, all of the simulations represented by individual lines of the file will be run in sequence. To run a single simulation using just one line of the file specify the line to run after the /i flag. For example

>xSYMMIC FET.xml -i=2 params.csv

will import parameters from line 2 of the params.csv file and then run a single simulation. Note that the first line of the file is number 1, but this line contains the header information describing the contents of the fields rather than the values of parameters. For a detailed example, see Using a Parameter Table below.

/o for Output of Solution

The /o flag can be used to save the solution in an alternative format with a different filename. The desired filename is given immediately after the flag. If this filename ends with a .dat extension, the file will be written in Tecplot format. A .csv extension would generate the comma separated values format. See Saving a Solution for details on these alternative formats. Any other file extension will result in the solution being saved in the default binary format used by SYMMIC.

If multiple cases are run using the /i option, the /o file will be rewritten after each case. Consequently, the output file will contain only the solution for the last case at the end. To save each case to a separate file use the /o=i option. This causes each solution filename to be given the number of the line in the input file to which it corresponds. For example

>xSYMMIC FET.xml -i=2 params.csv -o=i FETsolution.rst

causes the FET.xml template to be modified with the parameters from line 2 of params.csv, then solved and the solution stored in FETsolution_2.rst. When multiple solutions are generated by

>xSYMMIC FET.xml -i params.csv -o=i FETcase.dat

the solutions will be named FETcase_2.dat, FETcase_3.dat, FETcase_4.dat, and so on.

/p for Plot of Temperatures

When the /p option is specified, a 2D map of temperatures will be generated from the solution. These maps correspond to the plots available in the Results menu of the GUI. Option /p by itself generates a plot of the maximum temperatures across the x and y dimensions of the solution, same as generated by the Plot max. temperature item from the Results menu in the GUI. When the /p flag is followed by one of location specifiers (/px, /py, or /pz), a map is generated of the temperatures at a slice through that value. For example, /pz=670.5 would plot the temperatures over all x and y locations on the z=670.5 plane. This plot of temperatures at z=670.5 would replace the maximum temperature plot in file specified after the /p flag.

Plots can only be saved in .dat or .csv file formats. If the /p flag is followed by a filename with extension .dat, the plot is written as a TecPlot file. If the /p flag is followed by a .csv filename, the plot is written in comma separated values format. A filename with any other file extension, results in no plot file being written. Note that prior to version 3.0.0 the /p flag caused the plot to be written to the file specified by the /o flag. This is no longer the case, the files specified by the /o and /p flags are now independent.

If multiple cases are run using the /i option, the /p file will be rewritten after each case. Consequently, the plot file will contain only the solution for the last case at the end. To save each case to a separate file use the /p=i option. This causes each solution filename to be given the number of the line in the input file to which it corresponds. For example

>xSYMMIC FET.xml -i params.csv -p=i FETplot.dat -pz=670.5

will generate a plot at z=670.5 for each line of the input file. These plot files will be named FETplot_2.dat, FETplot_3.dat, FETplot_4.dat, and so on.

/c for Component Temperatures

The /c option specifies a file in which to save the component temperatures. This file may be written in the same HTML format used when component temperatures are viewed using a Snapshot... in the GUI, or in the comma separated values format viewed using Component temps... in the GUI. The component temperatures output includes the minimum, maximum, and average temperature of each distinct component in each device at every time point in the simulation, as detailed in the Component Temperatures section.

If multiple cases are run using the /i option, the /c file will be rewritten after each case. Consequently, the file will contain only the component temperatures for the last case. To save each case to a separate file use the /c=i option. This causes each solution filename to be given the number of the line in the input file to which it corresponds. For example

>xSYMMIC FET.xml -i params.csv -c=i FETtemps.htm

will generate an HTML file containing the component temperatures for each line of the input file. These HTML files will be named FETtemps_2.htm, FETtemps_3.htm, FETtemps_4.htm, and so on.

/s Superposition Parallelization Option

By default, solutions of layouts are by superposition of a solution for each device computed in sequence, but xSYMMIC now has a new option for running superposition in parallel. This option, called “Level 2”, is only appropriate (i.e. efficient) for certain types of layouts. It is designed for layouts of many small devices, such as is seen in mixed-signal and digital designs. The default (“Level 1”) superposition algorithm solves each device template in the layout sequentially, just as it would solve a single device template, using OpenMP to divide up the work over the CPU cores. In contrast, with Level 2 superposition a master-worker approach is implemented using MPI. The master core distributes templates to all of the other cores to solve, receives their results and hands out more work as needed, until the entire layout solution is completed. This approach works very well when there are many more templates in the layout than there are CPU cores, and each node has enough memory to solve a different template on every core. At a minimum, the number of device templates in the layout should not be less than the number of cores requested. Also, only 1 (OpenMP) thread is used for each solution with this algorithm.

Superposition Level 2 only works in conjunction with MPI, so xSYMMIC must be run with the mpiexec command. For example, if one wanted to run a layout over 16 cores, the command would be as follows.

>mpiexec -n 16 xSYMMIC layout.xml -s=2

The MPI command and options come first (mpiexec, -n, -ppn, -hostfile, etc.), then the executable (xSYMMIC) and finally the flags for that executable. The -s=2 option specifies Level 2 superposition. To use the default superposition no -s flag would be needed (or one could explicitly declare it with -s=1). For more information on parallel execution see the Parallel Computation section.

/z Thermal Impedance Option

Getting an equivalent RC network representation of a device or layout requires two back-to-back simulation runs. The first simulation solves for steady-state with constant ON power, from which the R values of the thermal resistance network are calculated. The second simulation solves for the transient with constant ON power, as the transient evolves from the environmental temperature to near steady-state. The transient simulation allows C values for the thermal capacitances in the network to be estimated.

The /z command line option causes xSYMMIC to first run a steady-state solution and then run a transient solution, using the simulation times and other parameters already setup in the template. Only outputs from the transient simulation are generated in response to the other flags. The steady-state result is deleted and forgotten immediately after calculating the thermal resistance values. No run values or other outputs are generated for the steady-state solution.

Note: The RC calculations must already be enabled in the template. The /z flag does not cause the RC calculations to become enabled if they were disabled when the template was opened. The /z option simply causes back-to-back steady and unsteady simulations to run. Prior to using the /z flag, enable RC calculations by setting the calculate="true" attribute in the <Impedance /> XML element of the device template. Or use the RC calculations... menu item to open the Thermal Impedance Calculations dialog and check the appropriate boxes.

Using a Parameter Table

The xSYMMIC command line includes an option for importing parameter values from a comma separated values file. The import file contains a header line of parameter names separated by commas, followed by rows of values for the parameters to be changed. When no file line is specified, a simulation will be performed for each row of parameter changes and the results of each run will be recorded to the recording file. The recorded results for a template can be viewed in the GUI using the Recorded values... menu item in the Results menu.

Study of Wilson (2002).

Results obtained with SYMMIC

To demonstrate how to use a parameter table on the command line, consider the study of Wilson J (2002) “Thermal Issues in GaAs Analog RF Devices” Electronics Cooling, Vol.8, No. 1, depicted in the left-hand figure. In this study, the peak temperature rise in a FET with a total gate length of 1250 µm is compared for three different configurations of finger width and number of gates. By modifying key parameters of a generic FET template to match the Wilson study design, the equivalent results shown in the right-hand figure can be obtained using a single xSYMMIC command line.

To setup the parameter table, it is first necessary to create a list of parameter names that will match the parameters in the template. Since parameter names must match exactly, it is best to generate the parameter names from the template using the GUI. First, open the generic FET template and configure it to match the requirements of the study. The initial parameter table will be created by recording parameters, and then the full parameter table will be produced by editing the initial table in a spreadsheet editor such as Excel.

To turn on recording for each parameter that will be varied during the simulations, check the Record box in the parameter value dialog. For example, selecting Number of Gates... from the Device menu and double-clicking on the parameter name opens the dialog box for modifying the number of gates. Checking the “Record this parameter with run values” box ensures that the number of gates will be recorded as simulations are run.

Once the appropriate parameters have been set for recording, it is only necessary to run a simulation to generate the initial parameter table. Run the first simulation by selecting Run simulation... from the Solve menu. When the simulation is complete the steady-state temperature solution will be displayed.

Open the recorded values file by selecting Recorded values... from the Results menu, as shown in the figure below. The table includes the device name, simulated time, and minimum and maximum temperatures over the device, in addition the set of parameters that were designated for recording. This initial parameter table gives the correct name strings for all of the parameters that need to be varied in the study.

To copy the parameter table from the Recorded Run Values dialog, highlight the two rows by clicking on the first row and then holding the Shift key down and clicking on the second row. Then press C while holding down the Ctrl key. This copies the data in comma separated values format onto the Windows clipboard. Open a blank spreadsheet and paste in the initial parameter table. (If using Excel, it may be necessary to open the .csv file directly rather than using Copy+Paste .) The first four columns can be deleted after pasting because these are simulation results rather than parameters.

Wilson's study used 6 different gate-to-gate spacings over 3 configurations of 1250 µm total gate length. The first configuration is 10 gates and 125 µm wide fingers. To set the different gate-to-gate spacings for this configuration, change all the source and drain lengths to the following values (in µm):

Gate-to-gate spacing

Source Lengths

Drain Lengths



















For the second configuration, change the Number of Gates to 6 (half of a 12-gate FET), and Finger Width to 104 µm. To compensate for the backside surface area loss due to the change in finger width, add a corresponding amount of material to the boundary beyond the gate bus by setting the Gate Bus to Boundary parameter to 121 µm from the default value of 100 µm. Again set the 6 gate-to-gate spacings using the source and drain length values in the above table.

The third configuration reported in Wilson's graph was a 16-gate FET with 75 µm fingers. A 1250 µm device would have a finger width of 78 µm if it is going to dissipate as much total power as the previous configuration. So for the third configuration, set the Number of Gates to 8 and Finger Width to 78 µm. To maintain the backside surface area, set the Drain Bus to Boundary to 126 µm from the default value of 100 µm. Repeating the gate-to-gate spacing parameter variation for the third configuration gives the final 6 rows of parameter values for this study. The final table in OpenOffice Calc is shown below.

Save the parameter table in CSV Text format from the spreadsheet to a file named BatchTable.csv. The .csv file can be tested in the GUI to verify it will work in batch mode by using the Import values from command on the File menu. Importing row 2 of the table should give the same peak temperature as in the initial simulation.

The entire trade-off study can be performed using the command line:

> xSYMMIC ExampleFET.xml /i BatchFile.csv

The resulting set of 18 simulation runs takes about 6 minutes (20 seconds per simulation) on a 64-bit Intel Xeon workstation and produces the following Recorded Run Values. The first simulation result appended to the recording file is the same as the initial result since the second row of the table has parameter values identical to the initial settings.

Note: When a parameter table is present, the command line executes a simulation run for each row of parameter values in the table. No simulation is run for the initial parameter settings in the template. When the parameter table has less than 2 rows (including the heading of parameter names), only a single simulation is performed using the initial parameters settings in the template.

CapeSym > SYMMIC > Users Manual
© Copyright 2007-2019 CapeSym, Inc. | 6 Huron Dr. Suite 1B, Natick, MA 01760, USA | +1 (508) 653-7100