Design Verification Module: DVM Testplan Syntax

TITLE SIMetrix/SIMPLIS DVM Testplan Syntax Documentation
APPLIES TO SIMetrix/SIMPLIS DVM v6.20
KEYWORDS dvm, testplan, test, plan, syntax
DESCRIPTION Covers the syntax used in the SIMetrix/SIMPLIS Design Verification Module Testplans.

Testplan Files

Testplan files are merely tab-separated text files with a .testplan extension.

Blank lines are ignored.

Lines starting with the * character are considered comment lines and are ignored.

Inline comments are not supported, that is, one can comment out a line, but not a single field or a portion of a line.

All non-blank, non-comment lines will be interpreted as a testplan entry, that is a test to be run.

Testplan Content

There are two ways of detailing a testplan entry: with and without a header row.

Without a Header Row (a.k.a. Quick and Dirty)

When not using a header row, each field must include a prefix to indicate the desired action. For example:

simulator: simetrix include: include1.txt
simulator: simplis include: include2.txt
With a Header Row

By including a specially formatted comment line, one can avoid prefixing each field.

The following testplan file:

*?@ prefix1 prefix2 prefix3 prefix4
value1 value2 value3 value4
value5 value6 value7 value8

is equivalent to:

prefix1: value1 prefix2: value2 prefix3: value3 prefix4: value4
prefix1: value5 prefix2: value6 prefix3: value7 prefix4: value8

Syntax

The following prefixes are supported:

simulator generateinitfile source VAR()
analysis includeinitfile load GLOBALVAR()
objective preprocess label CHANGE()
include postprocess TEMP()

simulator

Allows the user to select which simulator to use for simulation.

Case-insensitive.

Defaults to the currently assigned simulator for the current root schematic.

Acceptable values:

  • simetrix
  • simplis

Can be left blank.

analysis

Allows the user to specify an analysis statement for the simulator.

If the specified analysis starts with a recognized simulator analysis statement, then the value of the field is assumed to be an explicit simulator analysis statement, and will be added to the appropriate section of the F11 window for simulation. Recognized simulator analysis statements begin with one of the following directives:

  • .AC
  • .TRAN
  • .POP
  • .OP
  • .DC
  • .TF
  • .NOISE

Multiple line analyses are supported through the use of \n to represent a new line. The following entry:

analysis: .AC DEC 20 1k 1Meg\n.POP TRIG_GATE={TRIG_GATE} TRIG_COND=0_TO_1 MAX_PERIOD=1u

will be added to the F11 window as:

.AC DEC 20 1k 1Meg
.POP TRIG_GATE={TRIG_GATE} TRIG_COND=0_TO_1 MAX_PERIOD=1u

If the specified analysis does not start with a recognized simulator analysis statement, it should be paired with an objective statement, and the value for analysis must be one of the following:

  • AC
  • TRAN
  • POP
  • Transient
  • Steady-State
  • NoSimulation

If the specified analysis is not a recognized simulator analysis statement and is not paired with an objective statement, no changes will be made to the analysis directives in the F11 window.

If either analysis or objective is set to "NoSimulation", then no simulation will be run. Otherwise, the analysis should match up with the objective entry.

Can be left blank.

objective

Allows the user to specify a test objective for the testplan entry. Acceptable analysis/objective combinations for are as follows:

DC/DC Test Objectives:
Analysis Objective Source/Load Configuration of refdes Other Source(s) Other Load(s)
AC BodePlot(refdes) BODE (3-Term. or 4-Term. Load) DC RES (2-Term., 3-Term. or 4-Term.)
AC Impedance(refdes) * IMPEDANCE (Source or 2-Term., 3-Term. or 4-Term. Load) DC RES (2-Term., 3-Term. or 4-Term.)
* DVM will measure Input Impedance or Output Impedance depending on whether refdes is a DVM source or load.
AC ConductedSusceptibility(refdes) * SUSCEPTIBILITY DC RES (2-Term., 3-Term. or 4-Term.)
* DVM will automatically connect a special circuit between refdes and each managed DVM load to measure the conducted susceptibility between the selected source and each output.
AC NoSimulation N/A N/A N/A
Analysis Objective Source/Load Configuration of refdes Other Source(s) Other Load(s)
Transient StepLine(refdes, VSTART, VFINAL) RAMP DC RES (2-Term., 3-Term. or 4-Term.)
Transient StepLoad(refdes, ISTART, IFINAL) * RAMP (2-Term., 3-Term. or 4-Term.) DC RES (2-Term., 3-Term. or 4-Term.)
* ISTART will be modeled as a resisitive load while the PWL current source models the ramp. DVM automatically calculates the load resistor value for managed loads and adjusts the PWL steps accordingly.
Transient Startup(refdes, VFINAL) RAMP DC RES (2-Term., 3-Term. or 4-Term.)
Transient ShortCkt(refdes, ISTART, recover?) * SHORTCKT (2-Term., 3-Term. or 4-Term.) DC RES (2-Term., 3-Term. or 4-Term.)
* If the third argument is present and set to the string 'Recover', then DVM will lift the short and allow the circuit to perform recovery.
Transient NoSimulation N/A N/A N/A
Analysis Objective Source/Load Configuration of refdes Other Source(s) Other Load(s)
Steady-State Steady-State N/A DC RES (2-Term., 3-Term. or 4-Term.)
Steady-State NoSimulation N/A N/A N/A

Note that many test objective definitions support additional optional parameters.

AC/DC Test Objectives:

Analysis Objective Source/Load Configuration of refdes Other Source(s) Other Load(s)
Transient FindACSteadyState(refdes, line, VNORMAL, frequency, enabled/disabled)
AC_FIXED DC RES (2-Term., 3-Term. or 4-Term.)
* refdes should be a DVM Source w/ AC Support enabled.
Transient ACSteadyState(refdes, line, VNORMAL, frequency)
AC_FIXED DC RES (2-Term., 3-Term. or 4-Term.)
* refdes should be a DVM Source w/ AC Support enabled.
Transient ControlStartup(refdes, line, VNORMAL, frequency)
AC_FIXED RAMP RES (2-Term., 3-Term. or 4-Term.)
* refdes should be a DVM Source w/ AC Support enabled.
Transient LineStartup(refdes, line, VNORMAL, frequency)
AC_STARTUP DC RES (2-Term., 3-Term. or 4-Term.)
* refdes should be a DVM Source w/ AC Support enabled.
Transient LineDropout(refdes, line, VNORMAL, frequency, number of cycles)
AC_DROPOUT DC RES (2-Term., 3-Term. or 4-Term.)
* refdes should be a DVM Source w/ AC Support enabled.
Transient LineSag(refdes, line, VNORMAL, VSAG, frequency)
AC_SURGESAG DC RES (2-Term., 3-Term. or 4-Term.)
* refdes should be a DVM Source w/ AC Support enabled.
Transient LineSurge(refdes, line, VNORMAL, VSURGE, frequency)
AC_SURGESAG DC RES (2-Term., 3-Term. or 4-Term.)
* refdes should be a DVM Source w/ AC Support enabled.
Transient LoadTrAC(refdes, ISTART, IPULSE, IFINAL, frequency)
AC_FIXED DC PULSE (2-Term., 3-Term. or 4-Term.)

Note that many test objective definitions support additional optional parameters.

The value for refdes can either be the actual reference designator of the DVM Source or DVM Load or it can use the more generic syntax of INPUT:n or OUTPUT:n where n is an integer indicating a position in the list of Managed DVM sources or loads. To configure managed sources and loads, right click on the DVM Control Symbol and choose "Edit Additional Parameters". From the resulting menu, choose "Configure Sources and Loads".

The refdes specified must correspond to a DVM Input Source or DVM Output Load. For AC test objectives (except LoadTrAC), refdes should be a DVM Source with AC Support enabled. DVM Aux. Sources may not be used in an objective definition.

The values for VSTART, VFINAL, ISTART and IFINAL can be entered as:

  • a number representing Volts or Amps
  • a percentage of either nominal voltage or maximum current (only with Full PowerAssist)
  • a symbolic name (Min/Minimum, Nom/Nominal, Max/Maximum for voltages or No, Light, Max/Maximum for currents) (only with Full PowerAssist)

The values for line can only be ll or hl, this is used for simulation timing and sets the input RMS voltage in combination with the voltage value.

The voltage values for VNORMAL/VSAG/VSURGE can be entered as:

  • a number representing the RMS Voltage
  • a percentage of either nominal voltage (only with Full PowerAssist)
  • a symbolic name (Min/Minimum, Nom/Nominal, Max/Maximum, LL_Sag, HL_Sag, LL_Surge, HL_Surge) (only with Full PowerAssist)

The frequency can be entered as:

  • a number representing the frequency of the source
  • a symbolic name (F_Low or F_High) which are symbolic names for values entered in the DVM Control Symbol (only with Full PowerAssist)

The FindACSteadyState test objective has a special parameter, enabled/disabled, the value of which may only be Enabled or Disabled

The LineDropout test objective has a special parameter, "number of cycles". The value may be entered as:

  • a number representing the number of whole line cycles to dropout for, non-integers are allowed
  • the symbolic name custom, which is the symbolic name for a value entered in the DVM Control Symbol

Can be left blank.

label

Allows the user to specify a test's "hierarchical location".

The label is a | separated string that determines how a test is named in the test report and how it appears in the test selection GUI. Both files and directories are created based on the label value, so users should avoid characters deemed "illegal" for use in filenames by the operating system. In general, it is safe to use A-Z, a-z, 0-9, percent (%), dash (-), underscore(_), comma (,) and period (.).

Tests are grouped together and sorted alphabetically by label in the test selection GUI, however the order of execution is determined by its position in the testplan file.

Can be left blank.

If no label is specified, the test will be labeled as "Test n" where n is its numerical position in the testplan.

generateinitfile

Allows the user to save the SIMPLIS .init file resulting from a simulation to a filename generated from the identifier given as an argument.

Note that the user is not responsible for worrying about directory structure or the like. Instead, the identifier is combined with the filename and path of the schematic and saved in a sub-directory of the folder containing the schematic.

To make sure that the resulting filename is safe, the identifier is transformed to lowercase, spaces are replaced with underscores and all other non-alphanumeric characters are removed. This is done automatically, and the same process is applied to the identifiers for the includeinitfile directives.

Can be left blank.

includeinitfile

Allows a user to include a previously generated SIMPLIS .init file into a simulation deck using the same identifier as that of a previous generateinitfile directive.

The identifier is transformed to lowercase, spaces are replaced with underscores and all other non-alphanumeric characters are removed. This is done automatically, and the process is the same as applied to the identifiers for the generateinitfile directives.

In a testplan, every identifier used in an includeinitfile statement must have a corresponding generateinitfile statement.

Can be left blank.

include

Allows the user to specify a file to be included with a .INCLUDE statement.

Can be left blank.

preprocess

Allows the user to specify a SIMetrix script to be run immediately before the execution of a test.

Pre-process scripts are executed after normal DVM circuit configuration, but before any pre-process script specified in the DVM Control.

Can be left blank.

postprocess

Allows the user to specify a SIMetrix script to be run immediately after the execution of a test.

Post-process scripts are executed before normal DVM results processing, but after any post-process script specified in the DVM Control.

Can be left blank.

source

Allows the user to specify the configuration of a DVM source. Acceptable configurations are:

Source Configuration Description Info
DC(refdes, VDC) (docs)
Configures refdes as a DC source with the specified DC voltage.
RAMP(refdes, VSTART, VFINAL) (docs)
Configures refdes as a PWL source with the specified voltage levels.
PULSE(refdes, VSTART, VPULSE, VFINAL) (docs)
Configures refdes as a PWL source with the specified voltage levels.
AC_FIXED(refdes, line, VRMS, frequency) (docs)
Configures refdes as a standard sine wave input voltage source with the specified RMS voltage and frequency.
AC_DROPOUT(refdes, line, VRMS, frequency) (docs)
Configures refdes as an AC source with line dropout starting from and returning to the specified RMS voltage and frequency.
AC_STARTUP(refdes, line, VRMS, frequency) (docs)
Configures refdes as an AC source which starts at 0 volts and turns into an AC voltage source with specified RMS voltage and frequency.
AC_SURGESAG(refdes, line, VSURGE or SAG, frequency) (docs)
Configures refdes as an AC source which starts at the normal RMS voltage and steps to the RMS sag or surge voltage before returning to the normal RMS voltage.
AC_QSW(refdes, line, VPEAK, frequency, pulse width, rise time) (docs)
Configures refdes as a Quasi-Square-Wave source with specified pulse parameters.
AC_GLITCH(refdes, line, VNORMAL, VGLITCH, frequency, phase angle, pulse width, rise time) (docs)
Configures refdes as an AC source with specified RMS voltage and frequency. A 'glitch' abnormality ocours at the specified phase angle (0 to 180 degrees). During the specified pulse width, the source voltage is equal to the glitch voltage if the source voltage is positive, and equal to (-1) * glitch voltage if the source voltage is negative. The maximum rise/fall time of the glitch can be set with the slew rate parameter described below. Also the rise time of the underlying square wave voltage source is set with the rise time parameter. This source can be configured to simultate a broad range of abnormal AC Line voltage conditions.
SUBCKT(refdes, SUBCKT_NAME) N/A
Configures refdes to use the subcircuit definition SUBCKT_NAME.
SOURCE(refdes, VDC) * N/A
Configures refdes to use the specified DC voltage but does not change the subcircuit definition.
* Most often used with Full PowerAssist to change input voltage levels without overriding configuration changes resulting from the use of an analysis/objective specification.
AC_SOURCE(refdes, optional parameters) * N/A
Changes parameters for refdes but does not change the subcircuit definition.
* Most often used with Full PowerAssist to change input voltage levels without overriding configuration changes resulting from the use of an analysis/objective specification.

Note that many source definitions support additional optional parameters.

The value for refdes can either be the actual reference designator of the DVM Source or DVM Load or it can use the more generic syntax of INPUT:n where n is an integer indicating a position in the list of Managed DVM sources. To configure managed sources, right click on the DVM Control Symbol and choose "Edit Additional Parameters". From the resulting menu, choose "Configure Sources".

Subcircuit definitions for the various source configurations are available at the following URL:

http://simplistechnologies.com/documentation/simplis/dvm/symbols

Can be left blank.

load

Allows the user to specify the configuration of a DVM load. Acceptable configurations are:

Load Configuration Description Info
DC(refdes, IDC) Configures refdes as a DC load with the specified DC Current. (docs: 2-Term., 3-Term. or 4-Term.)
RES(refdes, RLOAD) Configures refdes as a resistor with the specified load resistance. (docs: 2-Term., 3-Term. or 4-Term.)
IRES(refdes, IDC) With Full PowerAssist, configures refdes as a resistor with the resistance calculated from the nominal output voltage and the specified DC current. (docs: 2-Term., 3-Term. or 4-Term.)
RAMP(refdes, ISTART, IFINAL) * Configures refdes as a PWL source with the specified current levels. (docs: 2-Term., 3-Term. or 4-Term.)
* If refdes is a managed load, ISTART will be modeled as a resisitive load while the PWL current source models the ramp. If refdes is not a managed load, only the PWL current source is used to model the load.
PULSE(refdes, ISTART, IPULSE, IFINAL) * Configures refdes as a PWL source with the specified current levels. (docs: 2-Term., 3-Term. or 4-Term.)
* If refdes is a managed load, ISTART will be modeled as a resisitive load while the PWL current source models the pulse. If refdes is not a managed load, only the PWL current source is used to model the load.
SUBCKT(refdes, SUBCKT_NAME) Configures refdes to use the subcircuit definition SUBCKT_NAME. N/A
LOAD(refdes, IDC) * Configures refdes to use the specified DC current but does not change the subcircuit definition. If refdes is a managed load, DVM will automatically configure the load resistance to the appropriate value. N/A
* Most often used with Full PowerAssist to change output current levels without overriding configuration changes resulting from the use of an analysis/objective specification.

Note that many load definitions support additional optional parameters.

The value for refdes can either be the actual reference designator of the DVM Load or it can use the more generic syntax of OUTPUT:n where n is an integer indicating a position in the list of Managed DVM loads. To configure managed loads, right click on the DVM Control Symbol and choose "Edit Additional Parameters". From the resulting menu, choose "Configure Loads".

Subcircuit definitions for the various load configurations are available at the following URL:

http://simplistechnologies.com/documentation/simplis/dvm/symbols

Can be left blank.

VAR( variablename, value )

In SIMPLIS mode, automatically inserts the following into the F11 window:

.VAR variablename value

In SIMetrix mode, automatically inserts the following into the F11 window:

.PARAM variablename value

GLOBALVAR( variablename, value )

In both SIMetrix and SIMPLIS mode, automatically inserts the following into the F11 window:

.GLOBALVAR variablename value

CHANGE( propertyaddress, value )

Attempts to change the component property identified by propertyaddress. The propertyaddress is a . separated string that reflects the path to the property that should be changed.

Please note that this will make a change to the schematic, and is therefore not without risk. Avoid use when possible.

Example:

CHANGE(U1.U3.GAIN,1)

This will attempt to locate a component U1, open its subschematic, locate a component U3 in that subschematic, then set its GAIN property to 1.

TEMP( value )

In SIMetrix mode, automatically inserts the following into the F11 window:

.TEMP value

SIMPLIS does not support a temperature specification.

Notes on VAR(), GLOBALVAR(), CHANGE() and TEMP()

The VAR(), GLOBALVAR(), CHANGE() and TEMP() directives behave differently depending on whether or not they are used inline or in a header row.

When used inline, VAR(), GLOBALVAR(), TEMP() and CHANGE() will perform the actions listed above. When used in a header row, value is interpreted to be the default, used if the a test fails to specify a value in its column.

Example:

*?@ VAR(MAX_Q,1n) CHANGE(U1.U3.GAIN,1)
2n
0.5

The first test will set the variable MAX_Q to 2n and change U1.U3's GAIN property to 1. The second test will set the variable MAX_Q to 1n and change U1.U3's GAIN property to 0.5.

Optional Parameters

Many of the objective, source and load definitions support an additional specially-formatted parameter string that can be used to override the values set in or derived from the DVM Control Symbol. The general syntax is as follows:

TestObjective( refdes, arg 1, ..., arg n, OPTIONAL_PARAMETER_STRING )

or

SourceType( refdes, arg 1, ..., arg n, OPTIONAL_PARAMETER_STRING )

...where OPTIONAL_PARAMETER_STRING is a space-separated set of KEY=VALUE pairs.

Optional Parameters for AC Input Sources and AC Test Objectives:

A number of optional parameters can be set in an objective or source definition. For AC objectives, these parameters will override the values set in or derived from the DVM Control Symbol. For AC Sources, these values will override the default values specified below.

LINE_PHASEANGLE: Sets the source phase angle at time=0. Most often used in three phase systems to set the phase angle of each phase. Valid values are 0 to 360 degrees, default is 0.

SOURCE_INDUCTANCE: Sets the Inductance of the source. Default is 795.4uH which represents a complex impedance of 0.25 ohms at 50 Hz. If set to zero, the inductor is replaced by a voltage source with a zero value.

SOURCE_RESISTANCE: Sets the source resistance of the source, default value is 0.4 ohms. Zero ohms is allowed.

F_CORNER: Sets the common corner frequency of the input source low pass filter. Each AC source has a filter with 1 to 3 poles set at this common frequency.

N_ORDER: Number of poles present in the input low pass filter. If set to zero, the filter is removed and all frequencies from the source are output to the circuit. Default value is 0.

SLEW_RATE: The maximum slew rate at which a source voltage is allowed to change in volts/second. If the slew rate is set to zero, there will be no practicable limit to the slew rate. Default value is 1MEG.

Examples:

To set the slew rate, filter order and corner frequency for a LineDropout Objective:

LineDropout(INPUT:1, LL, Nominal, F_Low, Custom, SLEW_RATE=100k N_ORDER=2 F_CORNER=150k)

When the next test is executed, the values for the slew rate, corner frequency and filter order will be reset to the DVM Control Symbol values.

To set the slew rate and source resistance of a AC_GLITCH source:

AC_GLITCH(INPUT:1, LL, Nominal, 81.31, F_LOW, 30, 2.15m, 100U, SLEW_RATE=500k SOURCE_RESISTANCE=0)

Changing the subcircuit for a test objective:

Each Objective has a default AC source which is configured specifically for that Objective. There are cases where a user may want to substitute a different source than the default source. This is done using the optional parameter SUBCKT. A good example shows how a user may simulate their circuit with a ACSteadyState test, but use a Quasi-Square-Wave source. The following example will do this:

ACSteadyState(INPUT:1, LL, Nominal, F_Low, SUBCKT=AC_QSW PULSE_WIDTH=5m RISE_TIME=100u)

And at the same time, the pulse width and rise times of the source are set.

A special note about permanancy of these parameters: For managed sources, the values for these parameters will be reset every test run, while for unmanaged sources, the changed parameters will remain until modified with another optional parameter call in either an objective or a source definition.

Timing for AC Test Objectives:

Optional parameters can also be used to customize the simulation timing for the AC Test Objectives:

FindACSteadyState:

  • NCYCLES_STOP: In combination with Frequency, Sets the simulation stop time: TStop = NCYCLES_STOP / FREQUENCY.
  • NCYCLES_CAPTURE: Determines how many Line Cycles of waveform data are captured: DataStartTime = (NCYCLES_STOP - NCYCLES_CAPTURE) / FREQUENCY.

ACSteadyState:

  • NCYCLES_STOP: In combination with Frequency, Sets the simulation stop time: TStop = NCYCLES_STOP / FREQUENCY.
  • NCYCLES_DELAY: Directly sets the time to when data collection starts: TStart = NCYCLES_DELAY / FREQUENCY.

LineStartup & ControlStartup:

  • NCYCLES_STOP: In combination with Frequency, Sets the simulation stop time: TStop = NCYCLES_STOP / FREQUENCY.
  • NCYCLES_DELAY: Sets the number of full line cycles before the Line or Control source turns on.
  • PHASE_ANGLE: Sets the Phase Angle at which the source turns on.

The combination of NCYCLES_DELAY and PHASE_ANGLE determine the source TIME_DELAY parameter with the following formula:

if LINE_PHASEANGLE > 0:

Otherwise:

LineDropout:

  • NCYCLES1: Number of full line cycles before dropout initiation.
  • NCYCLES2: Duration of Line Dropout, in Line Cycles.
  • NCYCLES3: Number of line cycles to simulate after the line returns to normal.
  • PHASE_ANGLE: The phase angle when the Line Dropout starts, in degrees.

LineSurge and LineSag:

  • NCYCLES1: Number of full line cycles to simulate before initiating line surge or line sag.
  • NCYCLES2: Duration of surge or sag, in line cycles.
  • NCYCLES3: Number of line cycles to simulate after the line returns to normal.
  • PHASE_ANGLE: The phase angle at which line surge or sag is initiated.

LoadTrAC:

  • NCYCLES1: Number of full line cycles to simulate before initiating the load pulse.
  • NCYCLES2: Duration of the load pulse, in line cycles.
  • NCYCLES3: Number of line cycles to simulate after the load returns to the non-pulse amplitude.
  • PHASE_ANGLE: Line phase angle at which the load pulse is initiated.
  • RISE_TIME: Sets the rise time of the load current pulse.
  • FALL_TIME: Sets the fall time of the load current pulse.

The combination of NCYCLES1, NCYCLES2 and PHASE_ANGLE determine the AC source or Load TIME_DELAY and PULSE_WIDTH parameters with the following formula:

if LINE_PHASEANGLE > 0:

Otherwise:

For the LineDropout, LineSag, LineSurge, and LoadTrAC Objectives, the simulation stop time is set to: TStop = (NCYCLES1 + NCYCLES2 + NCYCLES3) / FREQUENCY.

Other Optional Parameters for AC Test Objectives:

RESET_TO_STEADY_STATE: At the start of each test run each managed source will have the optional parameters reset to the default values set in the DVM Control Symbol, and the source type will be set to AC_FIXED. This can be disabled by setting this parameter to the string FALSE. The following example using this parameter is taken from the second phase of a three phase line dropout test. By including this optional parameter in the second Objective prevents the resetting of the source(s) set in eariler Objectives.

LineDropout(INPUT:2, LL, Nominal, F_Low, 0.5, PHASE_ANGLE=120 RESET_TO_STEADY_STATE=FALSE)

OVERWRITE_ANALYSIS: During a normal test execution, each objective will write a transient analysis statement calculated from the values in the DVM Control Symbol. When a testplan has multiple Objective columns, each one will write a new analysis statement. Setting this to the string FALSE will prevent the Objective from writing the analysis statement. By setting this parameter for all but one test Objective, the user can select which Objective writes the analysis statement.