6.1.3 Constant Voltage Subcircuit

Part #1: Change PWL Resistor Type and Rename Constant Current Load File

You will start the model by opening the constant_current_load.sxcmp file you created in the 6.1.2 Constant Current Subcircuit topic. You will then learn a clever trick to modify the PWL resistor type to a Current controlled PWL resistor (IPWL) and save this schematic component to a new file.

1. Open the constant_current_load.sxcmp schematic component created during the 6.1.2 Constant Current Subcircuit topic. If you haven't created this file, open the "answer" file : 6.1.1_constant_current_load_answer.sxcmp.
2. Select R1, the Voltage controlled PWL resistor.
3. Right click and select the Edit/Add Properties... menu option.
   Result: The Edit Properties dialog appears.
4. Double click on the SIMPLIS_TEMPLATE property.
   Result: The Edit Property dialog for the SIMPLIS_TEMPLATE opens:
   
5. Carefully edit the SIMPLIS_TEMPLATE, changing the V PWLR text to I PWLR.
   Note: This text is at the end of the SIMPLIS_TEMPLATE property value, just before the %VALUE% text.
   Result: The changed SIMPLIS_TEMPLATE value appears as below.
   
6. Click Ok on the Edit Property and then click Ok on the Edit Properties dialog to save your changes.
7. Double click on the R1 resistor symbol to open the parameter editing dialog. Note the caption should read Define IPWL Resistor: R1.
8. Click Cancel on the dialog.
9. From the Schematic Editor menu, select File ▶ Save As...
10. Enter constant_voltage_load.sxcmp in the File name field and click Save to save the schematic component.

Part #2: Parametrize the PWL Resistor

In this part, you will define the PWL resistor points using parameter values. The constant voltage load requires three parameters which the user will enter on the parameter editing dialog. These parameter names and the default values are shown in the table below:

Parameters Passed via Symbol

There are several ways to add these parameters to the actual PWL resistor. For this model you will define parameters calculated in the F11 window in addition to the parameters passed into the subcircuit through the symbol. In addition to the three parameters passed into the subcircuit through the symbol, the following three calculated parameters will be used:

Calculated Parameters Defined in the F11 Window

The resulting V-I curve for the load with the parameters annotated is shown below. Each voltage-current pair is annotated in (x,y) format. How the four additional parameters are calculated will be covered in Part 3: Define Calculated Parameters.

Notice the last segment in the resistor has a positive, but not infinite slope. SIMPLIS requires all PWL resistors to have positive slope for both the first and last PWL segment, and this model allows users to define the load as a ideal voltage source. If you did not add this third segment, the model would produce an error message because the slope of the last segment would be zero. This segment is placed at a voltage which is well beyond the operating voltage range of the load, preventing the final segment from effecting the normal operation of the load.

To parameterize the PWL resistor,

1. Double click on the PWL resistor R1.
   Result: The Define VPWL Resistor: R1 dialog opens:
   
2. Stretch the Voltage and Voltage columns to approximately twice the default width.
   1. Position the mouse between the Voltage and Current Columns on the title bar row.
      Result: The mouse cursor changes to two vertical bars, indicating the columns are ready to be resized.
      
   2. Press and hold the left mouse button and drag the column to resize.
   3. Repeat for the Current column by moving the mouse cursor to the right of the Current column, and repeating step B.
3. Edit the second data point:
   1. Replace {SAT_VOLTAGE} with {DC_VOLTAGE}.
   2. Replace {DC_CURRENT} with {CURRENT_2}.
      Result: The dialog should appear as follows:
      
      CAUTION:
      Spelling errors here will have disastrous consequences later on. Whenever you enter text by hand, double check the spelling. A good way to avoid spelling errors is to copy and paste the text from this document.
4. To delete the fourth row:
   1. In Row 4, select either the Voltage or Current cell.
   2. Press the Delete key to remove the data point.
      Result: The final dialog should appear as follows:
      
5. Click Ok to save the changes.

At this point, the PWL resistor uses four parameters - one is passed in from the symbol, and the other three are calculated from the passed-in parameters. In the next part, you will define the four calculated parameters in the F11 window of the constant_voltage_load.sxcmp schematic component.

Part #3: Define Calculated Parameters

Both the second and third points are calculated from the parameters passed into the subcircuit. In this part, you will define these parameters in the F11 window of the schematic component.

The constant current load designed in topic 6.1.2 Constant Current Subcircuit, has an infinite output impedance when the USE_RSHUNT parameter is false. As a result, the PWL resistor definition required a third segment to guarantee the last segment has a positive, but finite slope. The constant voltage load design has a finite, non-zero series resistance. Although this resistance is not required, the simulator will produce errors when an ideal voltage source is placed across an ideal capacitor. An ideal voltage controlled PWL resistor has an ideal voltage source behavior, and therefore adding a small series resistance will make the model easier to use. Because the last segment is a finite resistance, the PWL resistor definition requires two segments - the leakage segment and the voltage-clamping segment.

To assign values for these segments:

1. Press F11 to open the command (F11) window.
2. Select all text in the F11 window and delete it.
3. The second current point is set by parameter CURRENT_2 and is simply the ratio of the DC_VOLTAGE over the RLEAKAGE. Enter the following text in the F11 window of the schematic:

   .VAR CURRENT_2 = { DC_VOLTAGE / RLEAKAGE }

   Notice: The final segment is defined by the slope of the resistance RSERIES. SIMPLIS views PWL resistors as a series of slopes - when the simulation voltage or current exceeds the last numerical voltage or current point defined by the resistor, SIMPLIS assumes the resistance is unchanged from the last segment. This means that you can very simply define the CURRENT_3 parameter to be one amp greater than the CURRENT_2 parameter, and the VOLTAGE_3 parameter to be RSERIES volts greater than the DC_VOLTAGE parameter. When the load current exceeds the CURRENT_3 parameter, SIMPLIS will continue to use the RSERIES resistance defined for the resistor.
4. Enter the following text in the F11 window of the schematic:

   .VAR CURRENT_3 = { CURRENT_2 + 1 }
   .VAR VOLTAGE_3 = { DC_VOLTAGE + 1 * RSERIES }

At this point, all PWL resistor points are defined, but no error checking has been added. In the next step, Part_4:_Check_Passed_Parameter_Values_With_dot_error, you will add error checking for the parameter values.

Part #4: Check Passed Parameter Values With .ERROR

In this part you will use the .IF/.ENDIF and .ERROR constructs to check if the parameter values are within the ranges allowed by the model.

1. Each error message tests the passed parameters are greater than zero. Copy the following three error messages and paste into the F11 window.

   .IF { DC_VOLTAGE <= 0 }
       .ERROR "The dc load voltage parameter (DC_VOLTAGE) for the constant_voltage_load subcircuit must be greater than 0."
   .ENDIF
   
   .IF { RSERIES <= 0 }
       .ERROR "The series resistance parameter (RSERIES) for the constant_Voltage_load subcircuit must be greater than 0."
   .ENDIF
   
   .IF { RLEAKAGE <= 0 }
       .ERROR "The leakage resistance parameter (RLEAKAGE) for the constant_Voltage_load subcircuit must be greater than 0."
    .ENDIF

Part #1: Assign and Edit a Symbol

At this point, the constant voltage load has a complete schematic but no symbol. Since the load is essentially a high impedance until the voltage limit is reached, it behaves as a Zener diode, and this will be the symbol assigned to the load. The simplest way to do this is to copy the global symbol for the Zener diode to the schematic component. You will then modify the graphical elements of the symbol to indicate that the underlying model is not the built-in Zener diode.

1. Press Z to place a Zener diode on the schematic. Click the Ok button to extract the parameters.
2. Select D1, the Zener diode symbol you just placed.
3. Right click and select Edit Symbol...
   Result: The global symbol for the Zener diode opens in the symbol editor:
   
   Important: It is very important to save this symbol to your schematic component file before you start to edit it. If you make edits to this symbol and inadvertently save them, those changes would be applied to the global current souce symbol used by other schematics. This could have disastrous effects in other schematics.
4. To save the symbol to your schematic component file,
   1. Select the Symbol Editor menu File ▶ Save...
      Result: The Save Symbol dialog opens
   2. In the Save to radio button group, select Component file.
   3. Click the Browse... button to navigate the file system and select the schematic component file for the constant_voltage_load.sxcmp. The configured dialog will appear as follows:
5. To delete unneeded symbol properties INITSCRIPT and VALUE:
   1. Position the mouse over the *ic_parameterised_subckt text and left click once. This text is the property value of the INITSCRIPT property.
      Result: The text changes color from black to blue, indicating the property is selected.
      
   2. Press the Delete key to delete the property.
   3. Repeat for the text BZX79-4V7 which represents the VALUE symbol property.
      Result: At this point the symbol editor should appear as follows:
      
6. To change the REF property to LOAD?:
   1. Select the D? text and Press F7 to edit the REF property.
   2. Enter a Value of LOAD? in the In the Edit Property dialog.
      Result: The symbol now appears as follows:
      
7. To add a SIMULATOR property and set value to SIMPLIS:
   1. From the Symbol Editor window select the menu item Property/Pin ▶ Add Property...
      Result: The Add Property dialog opens
   2. In the Name field, enter SIMULATOR.
   3. In the Value field, enter SIMPLIS.
   4. Check the Protected and Hidden check boxes.
      Result: The configured Add Property dialog appears as follows:
      
8. Click Ok to add the symbol property.
9. Next, to modify the graphical representation so users will know this symbol does not represent the built-in current source model, follow these steps:
   1. Position the mouse over the N pin, then press and hold the mouse button while dragging the pin downwards two major grid ticks.
      Result: The N pin is now two grid ticks down from the original position.
      
   2. Repeat for the P pin, moving the pin up three grid ticks. Unlike the current source symbol you modified in the last topic, the pins on the zener symbol are two grid ticks closer.
      Result: The P pin is now three grid ticks up from the original location.
      
10. To rotate the zener portion of the symbol and move it up 1/2 a major grid tick to center the zener portion vertically between the pins:
    1. Press and hold the left mouse button and drag the mouse to draw a selection box over the zener portion in the middle of the symbol:
    2. Release the mouse butto.
       Result: The zener graphical elements are selected.
    3. Press F5 twice to rotate the selected graphical elements. Click on the selected items and drag the selected items up approximately 1/2 a major grid tick. Note - you may need to zoom in to center the graphical elements.
       Result: The zener graphical elements are centered between the two pins.
       
11. To connect the pins to the zener and add a graphical box around the zener:
    1. Double click to start a graphical "wire" segment.
    2. Left click once to define a corner or end point.
    3. Right click to stop wiring.
    4. If you make a mistake, right click to stop wiring and press Ctrl-Z to undo.
       Result: The symbol should appear approximately as follows:
       
12. Select the Symbol Editor menu File ▶ Save... to save the symbol to the schematic component file.
13. Navigate to the SIMetrix/SIMPLIS Schematic Editor window. Select and delete the Zener diode D1.

You now have a symbol which will call the subcircuit based constant voltage load model. The functionality of the underlying subcircuit is implied by the Zener diode symbol, and the box around the Zener diode source suggests to the user that this is not a normal Zener diode. At this point the symbol doesn't pass parameters to the underlying subcircuit, nor does the symbol have a parameter editing dialog. In the next part, Part_2:_Add_Parameters_and_Dialog_Properties, you will use a spreadsheet to add the required symbol properties.

Part #2: Add Parameters and Dialog Properties

Included in the Module_6_Examples.zip file is a pre-prepared dialog definition spreadsheet similar to the one used in the previous module. Like the spreadsheet used in 6.1.1 Constant Resistance Subcircuit, this spreadsheet contains all script commands to add the properties to the symbol. The extracted file is located at: C:\Training\Module_6_Examples\6.1.3_constant_voltage_load_dialog_definition_worksheet.xlsx. The dialog definition creates the following dialog for the constant voltage load:

To add the symbol properties,

1. Open the 6.1.3_constant_voltage_load_dialog_definition_worksheet.xlsx excel spreadsheet.
2. Copy the 7 cells: B23-B31 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. Select the Symbol Editor menu File ▶ Save... to save the symbol to the schematic component file.

The model and symbol are now complete and ready for testing.

Experiment #1: Test Dialog and Change Parameter Values

Whenever you pass parameters to subcircuits, it is important to test that the parameters are being passed properly and the simulation results reflect the actual parameter value. In this experiment, you will change the load parameters and verify the value changes in the simulation.

1. Navigate to the Schematic Editor window.
2. Double click on the subcircuit load symbol to edit the resistance parameter.
   Result: The parameter editing dialog opens.
3. To change the parameters:
   1. Change the DC Voltage value to 500m.
   2. Change the Series Resistance parameter to 10m.
   3. Change the Leakage Resistance to 2Meg.
      Result: The dialog should appear as follows.
      Click Ok to accept the dialog.
4. Press F9 to run the simulation.
   Result: The green V-I curve for the load is generated with the new parameters.
   

The output curves clearly reflect the changed parameter values.

Experiment #2: Test .ERROR Message

Testing the .ERROR message is slightly more difficult because the parameter editing dialog will not allow you to enter an invalid value. Instead you will manually edit the value using the Edit Properties dialog.

1. Select the LOAD1 symbol.
2. Right click and select the Edit/Add Properties... menu option.
   Result: The Edit Properties dialog opens.
3. To change the DC_VOLTAGE, RSERIES, and RLEAKAGE properties to 0:
   1. Double click on each property. On the Edit Property dialog, change each property Value to 0, and click Ok on the Edit Property dialog to accept the changes.
   2. Repeat for each property.
   3. Click Ok on the Edit Properties dialog.
4. Press F9 to run the simulation.
   Result: All three parameters are less than the minimum limit specified in the F11 window of the constant_voltage_load.sxcmp schematic, and each .ERROR statement is output to the command shell:

   *** ERROR *** (6.3_test_constant_voltage.net): Subckt def constant_voltage_load used by X$LOAD1:
   The leakage resistance parameter (RLEAKAGE) for the constant_Voltage_load subcircuit must be greater than 0.
   *** ERROR *** (6.3_test_constant_voltage.net): Subckt def constant_voltage_load used by X$LOAD1:
   The series resistance parameter (RSERIES) for the constant_Voltage_load subcircuit must be greater than 0.
   *** ERROR *** (6.3_test_constant_voltage.net): Subckt def constant_voltage_load used by X$LOAD1:
   The dc load voltage parameter (DC_VOLTAGE) for the constant_voltage_load subcircuit must be greater than 0.
   *** ERROR *** (6.3_test_constant_voltage.net): Could not evaluate "CURRENT_3= CURRENT_2 + 1 "
   Cannot find vector of name 'CURRENT_2'
   *** ERROR *** (6.3_test_constant_voltage.net): Could not evaluate "CURRENT_2= DC_VOLTAGE/RLEAKAGE "
   Arguments out of range for operator '/'
   

Experiment #3: Test Minimum Values Allowed by Dialog

In the previous experiment you set the load parameters to values less than the minimum allowed by the parameter editing dialog. In this short experiment you will verify the dialog prevents users from entering values less than the specified minimum value.

1. Double click on the LOAD1 symbol to open the parameter editing dialog.
   Result: Although the three parameters were set to 0 in the last exercise, the dialog automatically changes the values to the minimum values allowed for each parameter. Each minimum value is defined in the excel spreadsheet for this dialog definition.
   
2. Press the up arrow button on the DC Voltage spinner control.
   Result: The DC Current value changes from 1p to 2p .
3. Press the down arrow button twice on the DC Voltage spinner control.
   Result: The DC Current value changes from 2p to 1p , and on the second click, the minimum value of 1p is enforced.