| 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 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.
There are two ways of detailing a testplan entry: with and without a header row.
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 |
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 |
The following prefixes are supported:
| simulator | generateinitfile | source | VAR() | |
| analysis | includeinitfile | load | GLOBALVAR() | |
| objective | preprocess | label | CHANGE() | |
| include | postprocess | TEMP() |
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:
Can be left blank.
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:
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:
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.
Allows the user to specify a test objective for the testplan entry. Acceptable analysis/objective combinations for are as follows:
| 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.
| 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:
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:
Min/Minimum, Nom/Nominal, Max/Maximum, LL_Sag, HL_Sag, LL_Surge, HL_Surge) (only with Full PowerAssist)The frequency can be entered as:
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:
custom, which is the symbolic name for a value entered in the DVM Control SymbolCan be left blank.
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.
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.
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.
Allows the user to specify a file to be included with a .INCLUDE statement.
Can be left blank.
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.
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.
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.
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.
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
In both SIMetrix and SIMPLIS mode, automatically inserts the following into the F11 window:
.GLOBALVAR variablename 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.
In SIMetrix mode, automatically inserts the following into the F11 window:
.TEMP value
SIMPLIS does not support a temperature specification.
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.
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.
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.
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)
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.
Optional parameters can also be used to customize the simulation timing for the AC Test Objectives:
The combination of NCYCLES_DELAY and PHASE_ANGLE determine the source TIME_DELAY parameter with the following formula:
if LINE_PHASEANGLE > 0:

Otherwise:

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