7.0 Scripting

SIMetrix/SIMPLIS ships with a scripting language (script documentation) that allows users to specify pre- and post-process scripts to be run with a test.

Pre- and post-process scripts can be assigned either in a testplan (testplan syntax documentation) or through the DVM control that is supported by both the basic and Full Power Assist symbols. Scripts called from the testplan can be assigned on a test-by-test basis while scripts assigned in the DVM Control Symbol are called during every test. Pre- and post-process scripts are launched with the /quiet and /noerr flags to prevent script errors from halting DVM execution.

In this topic:

7.1 Debugging Scripts

Because the /noerr and /quiet flags suppress error generation, script debugging can be difficult; therefore, an unsupported option is available to execute the scripts without these flags.

To manage these flags options, follow these steps:

  1. To turn on the option for debugging, copy and paste the following into the SIMetrix/SIMPLIS Command Line
    Set SimplisDVMPostProcessDebug
  2. To suppress error generation after you debug a script, copy and paste the following into the command line:
    Unset SimplisDVMPostProcessDebug

A standard interface for both pre-process and post-process scripts is set with the following line that you can copy line and paste it into each script file you use for both pre- and post-processing:

Arguments @retval label report_dir log_file controlhandle

The above arguments are described in the following table.

Argument Description
retval Return value for the script:
  • For pre-process scripts, the return value at index=0 is logged in the test log file.
  • For post-process and final-process scripts, scalars, specifications, statistics and statistical specifications are returned on the indexes described in the following table.
    retval Description
    retval[0] Scalar values measured during the test
    retval[1] Specification values measured during the test
    retval[2] Statistical values measured during the test
    retval[3] Statistical specification values measured during the test

For additional information, see DVM Tutorial: 7.3 User-Defined Scalar and Spec Values.

label Label for the currently executing test. Since the label is passed to both the pre-process and post-process scripts, the script can decode the label and determine which test is currently executing. This allows the script to modify values or make measurements based on the currently executing test.
report_dir Base directory for simulation results
log_file Location of the overview log file
controlhandle Value of the Handle property for the DVM control symbol on the top-level schematic. The PropValues2() script function can read values from the DVM control symbol using the this value.

Multiple pre- and post-processing scripts can be assigned using the testplan headers Preprocess, PostProcess, and FinalProcess. If multiple scripts are assigned, the order of their execution is as follows:

  1. Scripts assigned in the testplan from left to right within the test definition row
  2. Scripts assigned in the control symbol (PreProcess and PostProcess only)

7.2 Pre-Process Scripts

Pre-process scripts are executed immediately before the simulation is launched. At this point, the simulation analysis has already been set in the F11 window of the schematic. This order of operations allows you to override any automatic DVM action with a pre-processing script.

7.2 Post-Process and Final-Process Scripts

Post-process scripts are executed after the simulation is complete and before any waveform processing is started. Final-process scripts are executed after DVM processes the waveforms; and in some test modes, before DVM creates new curves. If measurements on those curves are to be made, be certain your script is called from a FinalProcess testplan column.

7.3 User-Defined Scalar and Spec Values

The retval string vector is used to return both scalar and specification values from post-process and final-process scripts. In the case of pre-process scripts, there are no scalar values to return; however, the returned value, retval, is written to the log file. This allows a pass/fail status message to be sent the log file from the pre-process script. For example, a pre-process script which successfully executed might return the following, with commands in red and strings in green
Let retval = 'preprocess script executed properly'

To return scalar values from a post-process script, use the SimplisDVMAdvancedUtilCreateScalar function, which takes two required arguments and an optional third argument. All arguments are strings, which means that you should change your calculated scalar value to a string using the Str() or FormatNumber() SIMetrix script function. The two forms for the SimplisDVMAdvancedUtilCreateScalar function are:

  • SimplisDVMAdvancedUtilCreateScalar(scalar_name, scalar_value)
  • SimplisDVMAdvancedUtilCreateScalar(scalar_name, scalar_value, existing scalar_names )

    where

    • scalar_name is any string not containing spaces, equal signs, or tilde (~)
    • scalar_value is expected to be a string representation of the scalar value. For example, the following two command sequences return a single scalar with name my_pi and value 3.1415927 where both the name and value are enclosed in single quotes to denote a string:
      Let user_scalars = SimplisDVMAdvancedUtilCreateScalar 'my_pi', '3.1415927')
      Let retval = [user_scalars]
      Note: In certain text editors, the function is highlighted in blue, which, in the above instance, is not a hyperlink.

To return multiple scalar values,  pass the existing scalars as the third argument to the function:

Let user_scalars = SimplisDVMAdvancedUtilCreateScalar('my_pi', '3.1415927')
Let user_scalars = SimplisDVMAdvancedUtilCreateScalar('my_2pi','6.2831853', user_scalars)
Let retval = [user_scalars] 
This process can be repeated for each scalar value that is returned. The final command,
Let retval = [user_scalars],
assigns all the scalar values to the return value from the script. This line must come after all scalar values are assigned with the SimplisDVMAdvancedUtilCreateScalar function.

Returning specification values is similar to returning scalars. The

SimplisDVMAdvancedUtilCreateSpec

function creates the specification value and has three required arguments with an optional fourth argument. As with the scalar function, all arguments are strings. The two forms of the

SimplisDVMAdvancedUtilCreateSpec

function are as follows:

  • SimplisDVMAdvancedUtilCreateSpec(spec_name, status, description)
  • SimplisDVMAdvancedUtilCreateSpec(spec_name, status, description, existing specs)

    where

    • spec_name can be any string not containing spaces, equal signs, or tilde (~)
    • status can be either
      • 'PASS'
      • 'FAIL'
      • 'WARN'
      Note: Single quotes are required to denote these as strings.
    • description can be any string containing spaces that is displayed on the test report next to the scalar value and the pass/fail/warn status.

The following example creates a single specification value:

Let user_specs = SimplisDVMAdvancedUtilCreateSpec( 'is_value_pi', 'PASS', '3.1415927 is pi')
Let retval = [ '', user_specs ]

To return multiple spec values, follow the example below, passing the existing specs as the fourth argument:

Let user_specs = SimplisDVMAdvancedUtilCreateSpec('is_value_pi', 'PASS', '3.1415927 is pi')
Let user_specs = SimplisDVMAdvancedUtilCreateSpec('is_value_2pi', 'FAIL', '3.1415927 is not 2*pi', user_specs)
Let retval = ['', user_specs]

In these examples, only scalars or specs are returned using the two lines:

Let retval = [user_scalars]Let retval = ['', user_specs]

Of course, both scalars and specs can be returned by assigning both user_scalars and user_specs to the retval as follows:

Let retval = [user_scalars, user_specs]

A pre-prepared testplan which calls a pre- and post-process scripts is available from from   SIMPLIS_dvm_tutorial_examples.zip at this path: testplans/7.3_pre_and_post_process.testplan

This testplan contains six tests, calling the pre-process script in one test, and the post-process script in the other five. Notice the relative path to the scripts: up two directories and then down one into the scripts directory. Both scripts are available from   SIMPLIS_dvm_tutorial_examples.zip at the following paths: scripts/7.3_pre_process.sxscr: scripts/7.3_post_process.sxscr

The testplan is shown below:

***
*** 7.3_pre_and_post_process.testplan: pre and post process testplan for DVM tutorial section 7.3
***
*?@ Label Preprocess Postprocess
***
Pre-Process ../scripts/7.3_pre_process.sxscr  
Post-Process 1 Scalar   ../scripts/7.3_post_process.sxscr
Post-Process 2 Scalars   ../scripts/7.3_post_process.sxscr
Post-Process 1 Spec   ../scripts/7.3_post_process.sxscr
Post-Process 2 Specs   ../scripts/7.3_post_process.sxscr
Post-Process w 2 Scalars and 2 Specs   ../scripts/7.3_post_process.sxscr

7.4 Running the Testplan

This testplan can be run on any of the schematics in the LTC3406B\Test Ckts directory. Running the entire testplan on LTC3406B/6.3_LTC3406B-DVM-ADVANCED.sxsch produces the following overview report which has six tests with tests #5 and #6 failing. These tests fail because the post process script returned a specification value which was 'FAIL.'.