Advanced SIMPLIS Training

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

4.1 What is a Model?

In this Topic Hide

What You Will Learn

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

  2. Model Libraries can be installed in SIMetrix/SIMPLIS by dragging the file from a Windows Explorer window and dropping the file in  the SIMetrix/SIMPLIS command shell window.

  3. Models can also be saved in the command (F11) window of the schematic.

  4. There are two Model Library Catalogs - one for SIMetrix models, and one for SIMPLIS models.

  5. The .SIMULATOR control determines which Model Library, SIMetrix or SIMPLIS, to catalog the model.

  6. How templatescripts can create models when the circuit is netlisted.

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 in Notepad++.
    Result: The ASCII text model file simplis_param.lb opens in Notepad++ to line 26 where the subcircuit definition of the POP Trigger device is located:

  6. The definition of the PERIODIC_OP subcircuit starts on line 26 with the .SUBCKT statement, and ends on line 53 with the .ENDS statement. The entire POP Trigger schematic device model is:

    .SUBCKT PERIODIC_OP  1 3 vars:
    + VREF=2.5 VOL=0 VOH=5 HYSTWD=0.002 DIVIDE_BY_2=0 IC=0 DELAY=0.0 TRIG_COND='0_TO_1'
    *#LABELS ,Ref. Voltage:REAL,Output Low Voltage,Output High Voltage,Hysteresis::1e-12,Divide By Two:BOOL,Initial Condition of Output (used in Divide by Two):LIST:0|1,Delay::0,Input Trigger Condition (Used in Divide by Two):LIST:'0_TO_1'|'1_TO_0'
    *#ICDEFS,!D_CYCLE:IC

     .NODE_MAP IN 1
     .NODE_MAP OUT 3

    .if {DIVIDE_BY_2 == 0} then
         * Normal usage, use a comparator
      !D_CYCLE 3 0 1 302 M1M IC={IC}
      VREF 302 0 DC {VREF}
      .MODEL M1M COMP RIN=10MEG ROUT=50 VOL={VOL} VOH={VOH}  HYSTWD={HYSTWD} DELAY={DELAY}

    .else
         * Divide by 2, use a Toggle-FF
      .var VTH_PLUS={VREF+5*HYSTWD}
      .if {TRIG_COND != '1_TO_0'} then
        .var TRIG_COND = '0_TO_1'
      .endif
      !D_CYCLE 3 204 0 303 1 M1M IC={IC}
      VREF 303 0 DC {VTH_PLUS}
      .MODEL M1M CLK_TFF RIN=10MEG ROUT=50 LOGIC=POS TRIG_COND={TRIG_COND}
      + TH={VREF} HYSTWD={HYSTWD} VOL={VOL} VOH={VOH} DELAY={DELAY}

    .endif

    .ENDS PERIODIC_OPs

Its important to note that multiple models can be saved in a single file, hence the term model library file. The simplis_param.lb file 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 command shell menu: 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 section 4.0 What is a Symbol?, you learned that the model used by the symbol doesn't always reflect the symbol itself. In that extreme example, the capacitor symbol was modified to use a subcircuit capacitor model. To simplify the example, the actual model file was included in the netlist with a .INCLUDE statement. Using a .INCLUDE statement allows the schematic to be run without installing the model file. In this example, you will install the model file used in the 4.1_symbols_may_not_represent_what_you_think.sxsch schematic.

  1. Open the schematic 4.1_symbols_may_not_represent_what_you_think.sxsch.

  2. Right click on the schematic tab:

  3. Select the Open Containing Folder menu option.
    Result: a Windows Explorer window opens to the schematic directory.

  4. Select the model library file 4.1_myCapacitor_model.lb file, then drag and drop it into the SIMetrix/SIMPLIS command shell window.
    Result: a dialog asks you to confirm that you want to install the model library file:

  5. Click OK.
    Result: SIMetrix/SIMPLIS registers the file path to the model file and builds a catalog of all subcircuit models in the file. A message is output to the command shell:

    Model library changed. Rebuilding catalogs, please wait...
    Completed

  6. At this point, the model library is installed. You can confirm this by executing the SIMetrix/SIMPLIS command shell menu: File ▶ Model Library ▶ View/Remove Libraries...
    Result: The Select Libraries dialog opens with your recently installed model library listed.

Exercise #2: Attempt to use 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. In this exercise you will comment out the include statement and attempt to use the myCapacitor subcircuit model contained in the 4.1_myCapacitor_model.lb model library file.

  1. Press F11 to open the command (F11) window.
    Result: The command (F11) window opens, displaying the analysis directives and the .include statement:

  2. Type an asterisk in front of the .include 4.1_myCapacitor_model.lb.
    Result: The command (F11) window appears as follows:

  3. Press F9 to run the simulation.
    Result: The simulation runs with errors. The following error message indicates the model for the myCapacitor subcircuit cannot be found in the netlist, include, and library files.

    ****************************************
    <<<<<<<< Error Message ID: 1023 >>>>>>>>

    input file C:\Training\Module_4_Examples\SIMPLIS_Data/4.1_symbols_may_not_represent_what_you_think.deck, line 4:
        X$C1 10 0 myCapacitor

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


The .SIMULATOR Control

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

Why is this not a problem for the original example which uses a .INCLUDE statement? Quite simply because the .INCLUDE statement includes the entire file's text in the netlist. As a result, the model library is not searched for the model.

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

  1. Right click on the schematic tab:

  2. Select the Open Containing Folder menu option.
    Result: a Windows Explorer window opens to the schematic directory.

  3. Open the 4.1_myCapacitor_model.lb file in Notepad++.

  4. On Line 5, type the following .SIMULATOR control:

    .SIMULATOR SIMPLIS

    Result: The final file should appear as follows:

  5. Press Ctrl+S to save the file.
    Result: The file icon turns from red to light blue, indicating the file is saved.

Rebuilding Model Library Catalogs

When you added the .SIMULATOR statement to the library file, you told SIMetrix/SIMPLIS to include the myCapacitor subcircuit in the SIMPLIS library. You now need to tell SIMetrix/SIMPLIS to rebuild the catalogs so the model is included in the SIMPLIS catalog. You do this by executing the SIMetrix/SIMPLIS command shell 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 catalog.

Exercise #3: 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 pulled in from the SIMPLIS model library and the simulation completes as expected.

Including Models in the Command (F11) Window

Models can also be included in the simulation deck by entering the 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. Uninstall the 4.1_myCapacitor_model.lb file.

    1. From the command shell menu, select File ▶ Model Library ▶ View/Remove Libraries..
      Result: The Select Libraries dialog appears:

    2. Select the 4.1_myCapacitor_model.lb entry.

    3. Click on the Remove button:
      Result: The 4.1_myCapacitor_model.lb entry is moved to the Available Libraries box.

    4. Click on the Ok Button.
      Result: The Library is removed, and the catalogs are automatically rebuilt.

  2. Copy the model text from the Notepad++ window.

    1. Navigate to the Notepad++ window.

    2. Select the model definition. The model starts on line 7 and continues through line 17:

    3. Press Ctrl+C to copy the text to the Windows clipboard.

  3. Paste the text into the schematic's command (F11) window.

    1. Navigate to the SIMetrix/SIMPLIS schematic window. The schematic 4.1_symbols_may_not_represent_what_you_think.sxsch should be open.

    2. Press F11 to open the command (F11) window.
      Result: The current text in the window is:

    3. Below the commented out .include line, paste the model definition. The final command (F11) window will appear as follows:

  4. Press F9 to run the simulation.
    Result: The myCapacitor model defined in the F11 window is used in the simulation.

Model Generation Using TEMPLATESCRIPTS

The model used by the resistor in the 4.1_symbols_may_not_represent_what_you_think.sxsch schematic was created with a template script. The script file is located in the schematic's working directory: C:/Training/Module_4_Examples/4.1_make_phony_resistor.sxscr. Creating models with templatescripts is outside the scope of this training course and only a brief introduction will be covered. The Script Reference Schematic Template Scripts has detailed instructions on how to create models using the templatescript method.

The template script used to create the model used by the resistor is:

The script works as follows:

  1. Line 4 passes two string arguments into the script - that is the reference designator and the current template. The resistor has no template, so the template passed into the script is an empty string.

  2. Line 7 defines a variable nl as the ASCII character for a new line.

  3. Line 11 starts the new template definition with a new line followed by a comment line, then another new line.

  4. Lines 12 through 20 concatenate a new template, each line in the script creates a new line in the model.

  5. Lines 22 and 23 show the template values in the command shell. This is only for debug purposes - most template scripts would not include these debug statements.

  6. Line 25 is the business end of the script. Without setting the template value, the existing template value is unchanged. This line sets the schematic template to the newtemplate variable.

The very first bullet in the What You Will Learn section defined a model as a primitive or a subcircuit model. The model created by the templatescript is a primitive model - that is, the reference designator begins with a character other than X. The capacitor model used in this topic is a subcircuit model as the reference designator begins with X.

Exercise #4: Verify the Resistor Model in the Netlist

In section 3.0.1 What Happens When You Press F9? you learned the templatescripts are executed during the netlist process. The netlister then evaluates the template as if the template was a static, fixed value, with the result being placed in the netlist. In this exercise you will verify the resistor model is placed in the netlist.

  1. From the command shell menu, select SIMPLIS ▶ Edit Netlist (before preprocess).
    Result: The netlist opens in Notepad++. The model generated is shown in the image below:

Conclusions and Key Points to Remember

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

  2. Model Libraries can be installed in SIMetrix/SIMPLIS by dragging the file from a Windows Explorer window and dropping the file in  the SIMetrix/SIMPLIS command shell window.

  3. Models can also be saved in the command (F11) window of the schematic.

  4. There are two Model Library Catalogs - one for SIMetrix models, and one for SIMPLIS models.

  5. The .SIMULATOR control determines which Model Library, SIMetrix or SIMPLIS, to catalog the model.

  6. How templatescripts can create models when the circuit is netlisted.

◀ 4.0 What is a Symbol?

  

4.2 What is a Schematic Component File? ▶

© 2015 simplistechnologies.com | All Rights Reserved