Advanced SIMPLIS Training

To download the examples for Module 5, click Module_5_Examples.zip

5.1 Passing Parameters into Subcircuits Using the SIMPLIS_TEMPLATE Property

In this Topic ShowHide

What You Will Learn

• How to store parameters on the symbol using symbol properties with each of the following:
  • Single-property method
  • Multi-property method

• How to use the SIMPLIS_TEMPLATE property, which defines the symbol-to-subcircuit interface, to pass parameters into subcircuits

Getting Started

In this topic, you will learn the single-property and multi-property methods for parameterizing a subcircuit symbol. Both methods use symbol properties to store model parameters. Each method passes symbol properties through the symbol-to-subcircuit interface where the symbol property values are used as model parameters. In general, the multi-property method is the recommended method; however, in some circumstances, the single-property method is a better choice. The methods are compared in the Advantages and Drawbacks to Each Method section.

In addition to using the SIMPLIS_TEMPLATE property, you can pass parameters into a subcircuit using the special PARAMS property. While this is not the preferred method, a number of symbols exist which use this method. Using the PARAMS property is covered in the Appendix - Passing Parameters into Subcircuits Using the PARAMS Property topic.

For the rest of Module 5, a single-pole filter is used as an example. The single pole filter uses three parameters to configure the filter:

Single-Property Method

The single property method stores all model parameters on a single property as a parameter string. The individual parameter names and values are concatenated with an equal sign, then the three name-value pairs are joined with a space. The final parameter string is FC=10k R_VAR=1k GAIN=1.

In the first exercise, you will store a parameter string on a single symbol property and pass it into the subcircuit using the SIMPLIS_TEMPLATE property. This is the single-property parameterization method.

Exercise #1: Parameterize Using the Single Property Method

To use the single property method, you will add a PARAMETERS property with the parameter string value: FC=10k R_VAR=1k GAIN=1 and then add a SIMPLIS_TEMPLATE property to pass the PARAMETERS property to the subcircuit as a set of parameters.

1. Open the schematic 5.3_parametrized_rc_filters_single_prop.sxsch.

2. To add the PARAMETERS property to the param_rc_single_prop.sxcmp symbol, follow these steps:

   1. Select U1, and then type the keyboard shortcut Shift+S to open the symbol.
      Result: The param_rc_single_prop schematic component symbol opens in the Symbol Editor.
      

   2. From the Symbol Editor menu, select Property/Pin ▶ Add Property...
      Result: The Add Property dialog opens.

   3. In the Name field, type PARAMETERS.

   4. In the Value field, type the following:
      FC=10k R_VAR=1k GAIN=1

   5. Check the Selectable and Show name check boxes.
      Result: The configured Add Property dialog should appear as shown below:
      

   6. Click Ok on the Add Property Dialog
      Result: The property named PARAMETERS is added to the symbol with the value FC=10k R_VAR=1k GAIN=1.
      

3. To add the SIMPLIS_TEMPLATE symbol property, follow these steps:

   1. From the Symbol editor menu, select: Property/Pin ▶ Add Property...
      Result: The Add Property dialog opens.

   2. In the Name field, type SIMPLIS_TEMPLATE.

   3. In the Value field, type the following:
      <ref> <nodelist> <value> vars: %PARAMETERS%

   4. Check the Hidden check box.
      Result: The configured Add Property dialog should appear as below:
      

   5. Click Ok on the Add Property Dialog.
      Result: The SIMPLIS_TEMPLATE property is added to the symbol with the value <ref> <nodelist> <value> vars: %PARAMETERS%.
      

4. From the Symbol Editor menu, select File ▶ Save...

5. Click Ok on the Save Symbol dialog to save the symbol to the component file, and then close the Symbol Editor window.

6. To update the instantiated symbols on the schematic, follow these steps:

   1. Select U1.

   2. Press and hold the Ctrl key while selecting U2.
      Result: Both symbols for U1 and U2 are selected:
      

   3. Right click to bring up the context menu, and select Restore Properties...
      Result: A dialog opens for you to confirm that you want to add the new properties to the instantiated symbols:
      
      

   4. Click Ok.
      Result: The schematic instances for U1 and U2 are updated with the new symbol property PARAMETERS:
      

7. Press F9 to run the simulation.
   Result: The design simulates in SIMPLIS and two gain curves are output, one for each of the two filters. The pole frequency is 10kHz for both filters since the passed parameters are identical for both U1 and U2.
   

Exercise #1: Discussion

Using the single property method, you have passed the PARAMETERS property value to the subcircuit using the SIMPLIS_TEMPLATE property. This explicit passing of parameters is a good design practice and makes symbols and models easier to understand.

Multi-Property Method

One problem with the single-property method is that you must edit the entire parameter string whenever you want to change a single parameter. The multi-property method solves this problem by using a dedicated symbol property for each parameter. In the next exercise, you will add properties using the multi-property method.

Exercise #2: Parameterize Using the Multi-Property Method

In this exercise, you will use the symbol editor to add symbol properties for each parameter. Although it is not strictly necessary, you will use the parameter name for the symbol property name. For example, the FC parameter will be saved on a symbol property named FC.

1. Open the schematic 5.4_parametrized_rc_filters_multi_prop.sxsch.

2. Select U2.

3. Right click to bring up the context menu, and then select Edit Symbol... to edit the symbol for the schematic component param_rc_multi_prop.sxcmp.

4. To add a symbol property for each name in the following table, follow the steps below:
   

   Symbol Property Name	Symbol Property Value
   FC	10k
   R_VAR	1k
   GAIN	1

   1. From the Symbol Editor menu, select Property/Pin ▶ Add Property..., and then add a symbol property with the name and value from the table above.

   2. To display the symbol property between the name of the schematic component and the symbol, select Auto Normal = Top  in Text Location group.

   3. Check the Show name and Selectable check boxes.
      Result: The configured dialog for the FC parameter is shown below:
      

   4. Click Ok to save the symbol property.

   5. Repeat steps a through d for the R_VAR and GAIN symbol properties.
      Result: The symbol with the added properties appears as follows:
      

5. To add the SIMPLIS_TEMPLATE property to pass the symbol properties FC, R_VAR, and GAIN through the symbol-to-subcircuit interface, follow these steps:

   1. From the Symbol Editor menu, select Property/Pin ▶ Add Property....

   2. Type SIMPLIS_TEMPLATE in the Name field, and add the following in the Value field:
      <ref> <nodelist> <value> vars: FC=%FC% R_VAR=%R_VAR% GAIN=%GAIN%

      Note: Unlike the single property method, you need to substitute all three literal symbol properties.

   3. In the Text Location group, select Auto Normal = Top for the symbol property.

   4. Check the Hidden check box on the Add Property Dialog.
      Result: The configured SIMPLIS_TEMPLATE add property dialog should appear as follows:
      

   5. Click Ok to add the SIMPLIS_TEMPLATE property.
      Result: You have now configured the symbol to use the multi-property method. The symbol editor should appear as follows:
      

6. From the Symbol Editor menu, select File ▶ Save..., and then click Ok on the Save Symbol dialog.

7. Close the Symbol Editor window.

8. To update the instantiated symbols on the schematic, follow these steps:

   1. Select U1.

   2. Press and hold the Ctrl key while selecting U2.
      Result: Both symbols for U1 and U2 are selected:
      

   3. Right click to bring up the context menu and select Restore Properties...
      Result: A dialog opens, for you to confirm that you want to add the new properties to the instantiated symbols:
      
      

   4. Click Ok.
      Result: The schematic instances for U1 and U2 are updated with the new symbol properties:
      

9. Press F9 to run the simulation.
   Result: The design simulates in SIMPLIS and two gain curves are output, one for each of the two filters. The pole frequency is 10kHz for both filters as the passed parameters are identical for both U1 and U2.
   

Exercise #2: Discussion

You can now double click on any of the symbol properties to edit the individual symbol properties. Since each symbol property is passed as a model parameter, you are directly editing the model parameters. This is one of the main advantages to the multi-property method. Unlike the single property method, you can choose which parameters to show and which to hide.

In the next section, you will learn about the other advantages and drawbacks of the single- and multi-property methods.

Advantages and Drawbacks to Each Method

The single-property and multi-property methods have several advantages and drawbacks as itemized below:

The multi-property method of parameterization is the recommended approach. Despite the extra work to define a multi-property symbol, the result provides a better user experience since individual symbol properties can be displayed or hidden.

When the number of parameters exceeds 50, the single-property method is recommended since the parameter-editing scripts can save the properties to the symbol faster after the you close the dialog.

Conclusions and Key Points to Remember

• The SIMPLIS_TEMPLATE symbol property defines the netlist entry; therefore, parameters are passed through the symbol-to-subcircuit interface with the SIMPLIS_TEMPLATE.

• Symbol property values can be literally substituted into the SIMPLIS_TEMPLATE by enclosing the property names with the percent symbol on the SIMPLIS_TEMPLATE property value. For example %FC% is replaced with the value of the symbol property FC.

  Note: This substitution is used only on the TEMPLATE and SIMPLIS_TEMPLATE properties.

© 2015 simplistechnologies.com | All Rights Reserved