PromoteGraph()

The PromoteGraph() function places a copy of the specified graph on the overview report. You can add any number of graphs, define their order, and rename the graphs on the overview report.

In this topic:

PromoteGraph() Syntax

To implement this functionality, the PromoteGraph() function has four versions with one required argument and three optional arguments that provide flexibility.

  • PromoteGraph(graph_name)
  • PromoteGraph(graph_name, weight)
    • In both versions above, graph_name must exactly match the DVM-generated graph name. To find the graph_name, you need to run the testplan and then open report.txt to find the name of the graph you want to promote and then go back to your testplan and add the PromoteGraph() function. For example, the auto-generated Bode Plot graph is named "DVM Bode Plot#ac#log".
    • In the second version, weight is a number that indicates the order in which you want the graph to appear with the higher numbered graphs appearing first in the report.
  • PromoteGraph(graph_name, weight, use_approximate_name
    • Weight is a number that indicates the order in which you want the graph to appear with the higher numbered graphs appearing first in the report.
    • The use_approximate_name argument must be 1 to instruct the program to search for that phrase in the actual graph names in report.txt.
      Note: Using the approximate_graph_name argument may match multiple graphs. For example, if you have a converter with multiple outputs, PromoteGraph(LOAD,3,1) matches all load graphs, assuming the loads were automatically named by DVM as LOAD1, LOAD2, etc. To be certain which graph you are promoting, examine the report.txt file for the full name and then set use_approximate_name to 0.
  • PromoteGraph(graph_name, weight, use_approximate_name, overview_graph_name)
    • Weight is a number that indicates the order in which you want the graph to appear with the higher numbered graphs appearing first in the report.
    • The use_approximate_name argument must be 1 to instruct the program to search for that phrase in the actual graph names in report.txt.  
    • The overview_graph_name argument specifies an alternate graph name that you want to appear on the report.

Example

Assume that you have a graph named "Bode Plot" and you want a copy of this graph on the overview report with a weight of 100. The following call in the testplan promotes the graph to the overview report. 
PromoteGraph(DVM Bode Plot#ac#log, 100)

Using one of the alternate forms allows you to promote graphs by the short name:

PromoteGraph(DVM Bode Plot, 100, 1)

Finally, a graph can be renamed on the overview report using the fourth function definition. This example renames the graph to DVM Bode Plot (Max Vin).

PromoteGraph(DVM Bode Plot, 110, 1, DVM Bode Plot (Max Vin) )

▲ back to top

Weighting

The weighting system uses a numeric sorting routine to determine the display order of the overview graphs. The ordering of the overview graphs are as follows, starting at the top of the report:

  • Graphs with weighting are displayed with the highest numerical weight displayed first.
  • Graphs without a weight are displayed next.
  • Graphs with a weight of -1 are displayed last.

If, in any of these categories, more than one graph exists with the same weight, the graphs with identical weight are alphabetically sorted by graph name.

Using PromoteGraph() as a Script Function

PromoteGraph() also exists as a SIMetrix script function and can be called from a post-process or final-process script. The arguments for this function when called from a script are slightly different than the testplan version. The function name and arguments are: 

SimplisDVMAdvancedUtilMeasurementPromoteGraph(array, log_file)
  • array is a string array containing the normal arguments to the PromoteGraph() function.
  • log_file is the DVM log file, which is an argument passed into the post-process and final-process scripts.

The Bode Plot examples above could be generated in a post-process script with the following script function calls:

Let return = SimplisDVMAdvancedUtilMeasurementPromoteGraph([ 'DVM Bode Plot#ac#log', '100' ], log_file)
Let return = SimplisDVMAdvancedUtilMeasurementPromoteGraph([ 'DVM Bode Plot', '100', '1' ], log_file)
Let return = SimplisDVMAdvancedUtilMeasurementPromoteGraph([ 'DVM Bode Plot', '110', '1', 'DVM Bode Plot (Max Vin)' ], log_file)

The script function return value may be safely ignored.

▲ back to top