6.2 Assembling the Subcircuit Load

Exercise #1: Edit the Constant Resistance Load SIMPLIS_TEMPLATE Property

Before you get started, a note on the .IF/.ENDIF syntax when used on a template property. When a simulation is run, the SIMPLIS_TEMPLATE property is evaluated, and in that process, expressions enclosed in curly braces are evaluated, and special template keywords are resolved to text values. Because of this evaluation, the curly braces need to be doubled up when a logical test is placed on the template property. The outer-most curly braces are evaluated during the netlist process, leaving the logical test expression inside single curly braces. The syntax for using .IF/.ENDIF on the SIMPLIS_TEMPLATE property is:

.IF {{ logical_test }}
   normal_symbolic_template_property
.ENDIF

It is also important to remember that the SIMPLIS_TEMPLATE literally defines the netlist entry for a symbol. As such, you need to be very careful when editing the SIMPLIS_TEMPLATE property. In the above example, the SIMPLIS_TEMPLATE is spread out on three lines, and this is critical to the conditional expression evaluating correctly.

To edit the constant resistance load SIMPLIS_TEMPLATE property:

1. Select the constant resistance load symbol.
2. Press 5 to open the Edit Properties dialog.
3. Double click on the SIMPLIS_TEMPLATE property.
   Result: The Edit Property dialog opens:
   
4. To edit the SIMPLIS_TEMPLATE property:
   1. With the cursor at the beginning of the first line (this is the default cursor position when the dialog is opened), press Enter to insert a new line.
      Result: the SIMPLIS_TEMPLATE has a blank first line:
      
   2. On the first line, enter .IF {{ LOAD_TYPE == 'Constant\sResistance' }}
      Result: the SIMPLIS_TEMPLATE now appears as:
      
   3. Position the cursor at the end of the template, that is, to the right of the %RESISTANCE% text.
   4. Press Enter to add a new line.
   5. On the new line, enter: .ENDIF
      Result: The final SIMPLIS_TEMPLATE property should appear as follows:
      
5. To review the SIMPLIS_TEMPLATE property value carefully, notice the following in particular:
   • The Value should have three lines.
   • The first line should start with a .IF
   • The first line must have two opening curly braces {{ and two closing curly braces }} around the conditional expression.
   • The third line should start with a .ENDIF
6. Click Ok to save the SIMPLIS_TEMPLATE property.
7. Click Ok on the Edit Properties dialog.

The LOAD_TYPE parameter is a string, and will be passed into the schematic through the symbol. Consider the condition expression:

.IF {{ LOAD_TYPE == 'Constant\sResistance' }}

This conditional expression compares the string value of the LOAD_TYPE parameter to the literal string 'Constant\sResistance'. In SIMetrix/SIMPLIS, strings are enclosed in single quotes. This is an important distinction in parameter types. In all previous topics, parameters were real values, such as 1MegΩ for a resistance value. You can also define parameter values as strings; however, it is difficult to pass strings with spaces through the symbol-subcircuit interface. In this example we "escape" the space character with the character sequence \s. You will see that the dialog function automatically converts \s to a space before displaying the parameter.

The conditional expression will either return the original SIMPLIS_TEMPLATE, or an empty string, based on the string comparison. Clearly the empty string is electrically inactive and the original SIMPLIS_TEMPLATE will include the model for the constant resistance subcircuit.

Exercise #2: Edit Constant Current and Constant Voltage SIMPLIS_TEMPLATE Properties

In this exercise, you will repeat each step from exercise #1. When you get to step #4a, you will use different conditional expressions for the two loads.

1. For the Constant Current Load, use

   .IF {{ LOAD_TYPE == 'Constant\sCurrent' }}

2. For the Constant Voltage Load, use

   .IF {{ LOAD_TYPE == 'Constant\sVoltage' }}

After making the changes to each SIMPLIS_TEMPLATE, double check that the syntax is correct:

• The Value should have three lines.
• The first line should start with a .IF.
• The first line must have two opening curly braces {{ and two closing curly braces }} around the conditional expression.
• The third line should start with a .ENDIF.

Exercise #3: Add .ERROR checking on the LOAD_TYPE parameter

Each subcircuit load has built-in error checking, but the new parameter LOAD_TYPE needs to be checked to ensure the string value is one of the three valid string values:

• 'Constant\sResistance'
• 'Constant\sCurrent'
• 'Constant\sVoltage'

The following conditional expression uses the logical AND operator "&&" and the logical NOT EQUAL TO inequality "!=" to check if the LOAD_TYPE parameter is not one of the three defined parameters:

.IF { LOAD_TYPE != 'Constant\sResistance' && LOAD_TYPE != 'Constant\sCurrent' && LOAD_TYPE != 'Constant\sVoltage' }
   .ERROR "The load type parameter (LOAD_TYPE={LOAD_TYPE}) for the subcircuit_load subcircuit must be one of 'Constant\sResistance', 'Constant\sCurrent', or 'Constant\sVoltage'."
.ENDIF

Copy this error message to the F11 window. and save the schematic.

Exercise #4: Add Dialog Properties to the Symbol

Included in the Module_6_Examples.zip file is a pre-prepared dialog definition spreadsheet similar to the one used in the previous three topics. Like the spreadsheets used in 6.1.1, 6.1.2, and 6.1.3, this spreadsheet contains all script commands required to add the dialog and parameter properties to the symbol. The extracted file is located at: C:\Training\Module_6_Examples\6.2_subcircuit_load_dialog_definition_worksheet.xlsx. The dialog definition creates the following dialog for the load:

To add the symbol properties:

1. Open the 6.2_subcircuit_load_dialog_definition_worksheet.xlsx excel spreadsheet.
2. Copy the 16 cells: B46-B61 to the windows clipboard.
3. Navigate to the SIMetrix/SIMPLIS command shell window.
4. Click the mouse in the command line entry located at the top of the command shell window:
5. Press Ctrl+V to paste the commands in the command line.
   Result: the last command is partially visible in the command line.
6. Press Enter or click the Ok Button on the command line.
   Result: The commands are executed in SIMetrix/SIMPLIS. Each AddSymbolProperty command adds a single symbol property to the symbol. As in previous exercises, the dialog definition properties are protected. All properties are hidden from view when the symbol is placed on the parent schematic.
7. Save the schematic component file.

Unlike the other models, this subcircuit load has hierarchy, and the parameters must be passed down through the hierarchy from the top level schematic component 6.2_subcircuit_load.sxcmp to the individual loads. In the next exercise you will pass the parameters from the 6.2_subcircuit_load.sxcmp schematic component to the individual loads.

Exercise #5: Pass Parameters Through Hierarchy

As discussed in topic 5.3 Passing Parameters Through Multiple Hierarchy Levels, parameters passed in through a symbol are only available at that level of hierarchy. To use these parameters in lower levels of hierarchy, such as in the three loads, you have to pass the parameters down through the hierarchy.

Start with the constant resistance load symbol:

1. Double click on the constant resistance symbol to edit the Resistance parameter. Enter {RESISTANCE} in the Resistance field. This is the parameter name defined on the 6.2_subcircuit_load.sxcmp symbol.
   Result: The constant resistance load dialog should appear as follows:
   
2. Click Ok to save your changes.
3. Next double click on the constant current load symbol and then enter the following parameters in the dialog:
   1. In the DC Current field, enter {DC_CURRENT}.
   2. In the Saturation Voltage field, enter {SAT_VOLTAGE}.
   3. In the Shunt Resistance field, enter {RSHUNT}.
      Result: The constant current load dialog should appear as follows:
      
   4. Click Ok to save your changes.
4. Because the USE_RSHUNT parameter editing control is a check box, the parameter value {USE_RSHUNT} cannot be entered on the parameter editing dialog. Instead, follow these steps to manually enter the {USE_RSHUNT} property value in the Edit/Add Properties... dialog:
   1. Select the constant current load.
   2. Right click and select the Edit/Add Properties... menu option.
   3. Double click on the USE_RSHUNT property.
      Result: The Edit Property dialog opens:
      
   4. Change the Value to {USE_RSHUNT}.
      Result: The Edit Property dialog should appear exactly as follows:
      
   5. Click Ok on the Edit Property dialog to save the changes.
   6. Click Ok on the Edit Properties dialog.
5. Finally double click on the constant voltage load symbol. Enter the following parameters in the dialog.
   1. In the DC Voltage field, enter {DC_VOLTAGE}.
   2. In the Series Resistance field, enter {RSERIES}.
   3. In the Leakage Resistance field, enter {RLEAKAGE}.
      Result: The constant voltage load dialog should appear as follows:
      
   4. Click Ok to save your changes.
6. Save the 6.2_subcircuit_load.sxcmp schematic.

The model is now complete and ready for testing.

Test the Model

Now that the model and associated symbol are completed, its time to start testing. A testbench schematic for the complete subcircuit load is located in the Module_6_Examples directory. The testbench has test circuitry for each load type, so you will need to place three loads on the testbench schematic. After you place each load you should configure each of the three symbols to use one of each load type. The testbench schematic is located at: C:\Training\Module_6_Examples\6.4_test_subcircuit_load.sxsch.

This section is left as a self-study exercise. You should run the same experiments as you ran in the previous three topics:

• 6.1.1 - Test the Model
• 6.1.2 - Test the Model
• 6.1.3 - Test the Model