4.1 What is a Model?

Models in SIMPLIS are typically ASCII text and collected together in model files. These model files can be installed into SIMetrix/SIMPLIS, or the individual model text can be included in the schematic's F11 window. In this topic you will install a subcircuit capacitor model into the library system and verify it works by simulating the design.

To download the examples for Module 4, click Module_4_Examples.zip

In this topic:

Key Concepts

This topic addresses the following key concepts:

  • Models can be primitive models, such as resistors, capacitors etc. or can be subcircuits saved in Model Library Files. Individual models in a library file can be saved as plain ASCII text or as encrypted ASCII text.
  • Model Libraries can be installed in SIMetrix/SIMPLIS with a context menu option in the File View, or by dragging the file from a Windows Explorer window and dropping the file in  the SIMetrix/SIMPLIS Main Window.
  • Models can also be saved in the command (F11) window of the schematic.
  • There are two Model Library Catalogs - one for SIMetrix models, and one for SIMPLIS models.
  • The .SIMULATOR control determines which Model Library, SIMetrix or SIMPLIS, to catalog the model.

What You Will Learn

In this topic, you will learn the following:

  • How to install model libraries into SIMetrix/SIMPLIS.
  • How to change which library, SIMetrix or SIMPLIS, the models are available in.
  • How to include a model in the F11 window.

Getting Started

  1. Open the schematic 4.2_LLC_Closed_Loop.sxsch.
  2. On the lower left hand side of the schematic, select U1, the LLC_Modulator_Closed_Loop hierarchical block.
  3. Press Ctrl+E to descend into the LLC_Modulator_Closed_Loop schematic component.
  4. On the lower left hand side of the schematic, select X1, the POP Trigger schematic device.
  5. Right click and execute the schematic context menu: View Model.
    Result: A copy of the built-in POP Trigger schematic device model is made and this file is opened in the netlist editor:
    Note: The definition of the PERIODIC_OP subcircuit starts on line 1 with the .SUBCKT statement, and ends on line 21 with the .ENDS statement.

It is important to note that multiple models can be saved in a single file, hence the term model library file. The POP Trigger model is stored in the simplis_param.lb model file which contains several other models including the Electrolytic Capacitor model you viewed in section 3.0.2 What Actual Device is Simulated in SIMPLIS?

Determining Which Model Libraries are Installed

Models like the PERIODIC_OP subcircuit are stored in model files, and in the getting started example, the model library file name is simplis_param.lb. Model files must be installed in SIMetrix/SIMPLIS for the program to find the subcircuit models contained in the files. To view the model libraries which are currently installed, execute the SIMetrix/SIMPLIS menu bar: File > Model Library > View/Remove Libraries....

This dialog shows that two "libraries" are installed. Each library path includes the asterisk wildcard character (*), indicating that all files ending with a .lb extension located in the directory are installed. As these two entries include all built-in model libraries, we strongly suggest you not remove either one.

Exercise #1: Install a Model Library

In this exercise you will install a subcircuit capacitor model into the library system. Using the open schematic, 4.2_LLC_Closed_Loop.sxsch, you will change the output capacitor from an ideal primitive capacitor to use this subcircuit capacitor, and note the change in output voltage waveforms.

The subcircuit capacitor was taken from the OS-CON website. This is a ladder model with 5 capacitors, 3 inductors, and 8 resistors. The model text is:

*1 SVPC-Series
*$
.SUBCKT 2R5SVPC2700M 1 2
C_C1         6 7  2682.6u  
C_C2         1 4  1765.9u
C_C3         1 3  900u
C_C4         1 9  5000u
C_C5         1 10 12000u
L_L1         8 2  5.63n   
L_L2         4 6  0.88n
L_L3         4 5  1.14n
R_R1         7 8  4.4m 
R_R2         1 7  1900
R_R3         1 4  14.2m
R_R4         4 6  107m
R_R5         3 4  1.5m
R_R6         9 3  5m
R_R7         5 6  18m
R_R8        10 9  25m
.ENDS
  1. If you have closed the 4.2_LLC_Closed_Loop.sxsch schematic, reopen it.
  2. Close the waveform viewer.
  3. Press Ctrl+Space to open the SIMPLIS Status window. Click on the Clear Messages button to clear the messages.
  4. Press F9 to run a baseline simulation using the built-in primitive capacitor.
    Result: The waveform viewer shows the secondary side waveforms including the output voltage.
  5. On the file view, open the Module_4_Examples directory and select the 2R5SVPC2700M.lb file and right click to bring up the context menu.
    Result: The context menu has an option to install the model file.
  6. Select Install Model.
    Result: SIMetrix/SIMPLIS installs the model file. The following message is output to the command shell.
    Installing D:/Training/Module_4_Examples/2R5SVPC2700M.lb
Model library changed. Rebuilding catalogs, please wait...
Completed
  7. At this point, the model library is installed. You can confirm this by selecting the SIMetrix/SIMPLIS menu item: File > Model Library > View/Remove Libraries....
    Result: The Select Libraries dialog opens with your recently installed model library listed.

SIMetrix/SIMPLIS installed the model file. This process includes scanning the model file, identifying which models are present, and building an index of these models. The index is used when SIMetrix/SIMPLIS netlists and preprocesses the netlist to speed up the model inclusion process.

Exercise #2: Change Schematic to use a Subcircuit Capacitor Model.

With the model installed, you will now change the schematic to use a subcircuit capacitor model. To modify the schematic, follow these steps:
  1. Delete the output capacitor. Select the output capacitor Co, and press Delete.
  2. From the parts selector, open the Passives category. Select the Capacitor - Subcircuit w/Quantity.
  3. Place the capacitor where the output capacitor was located.
  4. Double click on the output Subcircuit Capacitor and enter the subcircuit name in the dialog: 2R5SVPC2700M.

The schematic is now configured to use the subcircuit capacitor defined in a model file. In the next exercise you will attempt to simulate the design.

Exercise #3: Attempt to Simulate the Installed Model Library

In section 3.0.1 What Happens When You Press F9? you learned the netlist preprocessor searches for subcircuit models not found in the netlist or include files. The models can be located in:
  • The schematic's F11 window
  • A text file included in the simulation with a .INCLUDE or .INC statement.
  • Installed in the global model library.

In this exercise you will attempt to simulate the design using the installed model library file.

  1. Run the simulation.
    Result: The simulation errors. The error messages output to the command shell are:
    *** ERRORS REPORTED BY SIMPLIS ***
****************************************
<<<<<<<< Error Message ID: 1023 >>>>>>>>

input file D:\Training\Module_4_Examples\SIMPLIS_Data/4.2_LLC_Closed_Loop.deck, line 8:
    X$C3 19 39 2R5SVPC2700M

Unable to locate the definition
of `subcircuit 2R5SVPC2700M' in the
input, include, or library file(s).



*** END SIMPLIS ERROR REPORT ***

What happened? The circuit is properly configured to use a subcircuit model for C3. But the model cannot be found. The reason is the model is installed in the SIMetrix library and not the SIMPLIS one.

The .SIMULATOR Control

This common error is caused by the model being installed in the wrong library. The .SIMULATOR control tells SIMetrix/SIMPLIS to include the model in either the SIMetrix, SIMPLIS or both libraries. Without a .SIMULATOR SIMPLIS statement, models are installed in the SIMetrix library, and therefore cannot be found when the netlist preprocessor searches the SIMPLIS library to include the models.

In the next exercise you will add a .SIMULATOR SIMPLIS directive to the model library file.

Exercise #4: Editing the Model File

  1. In the File View, double click on the 2R5SVPC2700M.LB model file.
    Result: The model file opens in the netlist editor.
  2. Insert the text .SIMULATOR SIMPLIS at the first line. The file should appear as follows:
  3. Press Ctrl+S to save the model file.

Rebuilding Model Library Catalogs

When you added the .SIMULATOR statement to the library file, you told SIMetrix/SIMPLIS to include the 2R5SVPC2700M subcircuit in the SIMPLIS library. You now need to tell SIMetrix/SIMPLIS to rebuild the library catalogs so the model is included in the SIMPLIS catalog. You do this by executing the SIMetrix/SIMPLIS menu: File > Model Library > Re-build Catalog. This opens the following dialog:

After clicking on the Ok button, you will see the following message in the command shell:

Model library changed. Rebuilding catalogs, please wait... 
Completed
Important: Whenever you modify an installed model library file, you need to rebuild the catalogs.

Exercise #5: Run the Simulation

After you have rebuilt the model library catalogs, you are ready to run the simulation.

  1. Press F9 to run the simulation.
    Result: The model is included from the SIMPLIS model library and the simulation completes as expected. The output voltage for the second simulation has significantly larger ripple due to the additional parasitics introduced by the capacitor ladder network.

Including Models in the Command (F11) Window

Models can also be included in the simulation deck by entering the model text in the Command (F11) window. In the next exercise, you will copy the text from the model file and paste it into the schematic's command (F11) window.

  1. To uninstall the 2R5SVPC2700M.LB file, follow these steps:
    1. From the menu bar, select File > Model Library > View/Remove Libraries....
      Result: The Select Libraries dialog opens:
    2. Select the 2R5SVPC2700M.LB entry.
    3. Click on the down arrow button:
      Result: The 2R5SVPC2700M.LB entry is moved to the Available Libraries box.
    4. Click Ok.
      Result: The library is removed, and the catalogs are automatically rebuilt.
  2. To copy the model text from the text editor:
    1. Navigate to the text editor window. You can always double click on the file in the File View to open or bring the file into focus.
    2. Select the model definition. The model starts on line 4 and continues through line 21:
    3. Press Ctrl+C to copy the text to the Windows clipboard.
  3. To paste the text into the schematic's command (F11) window:
    1. Navigate to the SIMetrix/SIMPLIS schematic window where the schematic 4.2_LLC_Closed_Loop.sxsch should be open.
    2. Press F11 to open the command (F11) window.
      Result: The current text in the window is:
    3. Paste the model definition after the last line in the F11 window. The final command (F11) window will appear as follows:
  4. Press F9 to run the simulation.
    Result: The simulation runs as expected.

Exercise #6: The .INCLUDE Statement

The .INCLUDE statement can be used to include text files in the simulation deck file. The include statement inserts an exact copy of the entire referenced file at the location of the .INCLUDE statement. This makes the .INCLUDE statement an easy way to include the model file in the deck.

  1. Press F11 to open the command window.
  2. Delete the entire subcircuit capacitor model starting at the .SUBCKT statement and ending with the .ENDS statement. You can select the entire text and press Delete.
  3. Add the following .INCLUDE statement where the .SUBCKT statement was located:
    .INCLUDE 2R5SVPC2700M.LB
    Result: The F11 window should appear as follows:
  4. Run the simulation.
    Result: The simulation runs exactly as it did in the previous exercise where the model was entered directly in the F11 window.

Conclusions and Key Points to Remember

  • Models can be primitive models, or a subcircuit model saved in Model Library Files. Individual models in a library file can be saved as plain ASCII text or as encrypted ASCII text.
  • Model Libraries can be installed in SIMetrix/SIMPLIS with a context menu option in the File View, or by dragging the file from a Windows Explorer window and dropping the file in  the SIMetrix/SIMPLIS Main Window.
  • Models can also be saved in the command (F11) window of the schematic.
  • There are two Model Library Catalogs - one for SIMetrix models, and one for SIMPLIS models.
  • The .SIMULATOR control determines which Model Library, SIMetrix or SIMPLIS, to catalog the model.