Symbols are one of the most complicated parts of SIMetrix/SIMPLIS. In this topic, you will learn what constitutes a symbol, how they are used, how they are updated on schematics, and how they are stored. Many misconceptions about symbols are covered and explained.
To download the examples for Module 4, click Module_4_Examples.zip
In this topic:
This topic addresses the following key concepts:
Symbols have three primary functions:
Symbols are made up of three components:
Symbols are typically stored in one of four locations:
In this topic, you will learn the following:
Some common misconceptions about symbols:
A few details for working with symbols:
Symbols and Models are often confused. In this topic you will learn the ins and outs of symbols, what symbols do in SIMetrix/SIMPLIS, and how to manage symbols.
In this section you will run a simulation on the User-defined diode used as a synchronous rectifier in the SIMPLIS tutorial. The underlying model used by this diode symbol is a Piecewise Linear (PWL) resistor with two segments. In the following exercise, you will learn more about user-defined diodes and how these diodes might not conform to the graphical representation of a diode symbol.
We have all been trained that all diodes have some finite, positive forward voltage drop. Mentally, a user sees the diode symbol and thinks "diodes have a forward drop and an exponential forward transfer characteristic." This example circuit was purposefully designed to show that user-defined diodes can have a zero-volt forward drop. Why would you want to have a zero-volt forward drop? Because this user-defined diode makes an ideal synchronous rectifier, which behaves just like a MOSFET with the "perfect" gate drive timing waveforms. Whenever the circuit connected to the diode attempts to force forward current through the diode, the diode behaves like a 10mΩ resistor. When the diode is in a blocking state, the resistance is 100MegΩ.
All semiconductor symbols used in SIMPLIS schematics call a electrical model which has PWL transfer characteristics. The model parameter extraction algorithms execute SIMetrix SPICE simulations on the SPICE model and curve fit a PWL model to the SPICE simulation curves. In contrast to the user-defined model in this exercise, a parameter extracted diode would have a forward voltage drop and three PWL segments, as opposed to the two segment model used in the user-defined diodes.
Symbols are made up of pins, which connect the symbol to the underlying model, graphical elements such as lines, arcs, and so on which describe the function of the underlying model, and of properties. Properties can be protected or unprotected, unprotected properties can be edited on a schematic, while protected properties cannot. Other common symbol attributes are:
The primary purpose of symbols is to connect models to wires, which, in turn, connect to other symbols. A good model designer would also design the graphical representation of the symbol to depict the underlying electrical model. While this seems obvious, consider a common item in power electronics - the capacitor. Capacitors often include equivalent series resistance and equivalent series inductance, yet the graphical representation of the capacitor symbol is often no different than the primitive capacitor which models a pure capacitance. Because symbols primarily define connectivity, and a capacitor is a two terminal device, a common symbol is often used. This often, and rightfully, confuses users. In section 3.0.2 What Actual Device is Simulated in SIMPLIS? you learned how to find exactly what device model is used in the simulation.
Symbols are not models and models are not symbols. At SIMPLIS, we often hear users say "I placed this model on the schematic." In 99% of the cases, this is not true, as the getting started example demonstrated. You place symbols on the schematic and those symbols call electrical models, defined as a Schematic Component, as a ASCII text model from a library file, or defined with a script. Compared to models, symbols have a rather simple job to accomplish - to interconnect other symbols and as you will see, to pass parameters to the underlying electrical model.
In section 3.0.2 What Actual Device is Simulated in SIMPLIS?, you learned how parameters stored on a symbol property were passed through to the electrical model using the SIMPLIS_TEMPLATE property. In the 5.1 Passing Parameters into Subcircuits Using the SIMPLIS_TEMPLATE Property topic, you will learn how to pass parameters to a subcircuit model. At this point, just remember that symbol properties store model parameters . Those symbol properties are passed to the model as model parameters via the SIMPLIS_TEMPLATE property.
The VALUESCRIPT and PARAMSCRIPT properties define the scripts which are called when a user interacts with the symbol. The VALUESCRIPT is called when the user double clicks on the symbol. If the user right clicks and executes the Edit Additional Properties... context menu, the PARAMSCRIPT is called. Adding parameter editing dialogs is covered in the 5.2 Parameter-Editing Dialogs topic.
Symbols can be stored in several locations:
When you place a symbol on the schematic, a copy of the library version is created and saved to the schematic file. This copy is called the instantiation and now resides in the schematic file. Because the symbols are copied to the schematic file, you can share a design with a colleague by sharing the schematic file alone. You can also add, modify, and delete symbol properties on the instantiated symbol without modifying the library version. This is important because the values for many symbol properties will be different than the default values saved in the library copy of the symbol. Consider the case of a large converter which might have 25 resistors, all with different values. The library version of the resistor symbol will have the default value of 1k, while each instantiation will have it's own local value for the resistance.
Symbols placed for hierarchical Schematic Component Files are treated differently. These symbols are read from the schematic component file and placed on the schematic. No local copy is saved.
A few examples will help demonstrate the difference between the instantiated symbol and the library version.
The User-defined diode is good example if the difference between instantiated the library versions of symbols. When you place a diode on a SIMPLIS schematic, the program adds several properties to the symbol. In this exercise you will examine the difference between the library symbol and the instantiated symbol. To get started, follow these steps:
As you can see, the instantiated version of the symbol contains many more properties than the library version of the Junction Diode symbol. The additional properties re-purpose the Junction Diode symbol for use with the SIMPLIS simulator. In this case, the symbol is modified to call a subcircuit model and to pass parameters into that model.
In the 4.2 What is a Schematic Component File? topic, you will learn that schematic component files contain both a schematic and the symbol for the schematic. When you place a symbol for a schematic component, you are essentially telling the program "Go to this file named xxx and find the symbol and put it on the schematic here." Because you are referencing the file by name, there two ways to do this:
We cannot overemphasize the importance of using a relative path instead of a full path. When you use a full path, the design looses it's portability, as there are full path references to schematic component files. When the files are archived and opened from a different root directory, the schematic will not simulate because the referenced path doesn't exist.
In this exercise you will examine the difference between instantiated and library versions of the schematic component files. To get started, follow these steps:
As with the Junction Diode, the instantiated symbol has additional properties, and some properties common to the both the library and instantiated symbols have different values. In particular, the deadtime parameter for the modulator is 100n in the library, but is parameterized on the instantiated symbol.
In the previous two exercises you learned that an instantiated symbol is a copy of the library symbol, but with modified and possibly additional symbol properties. The natural question arises: "What determines which properties are updated if the library version of the symbol changes?" The answer is fairly simple. Every property, pin, and graphical portion of the symbol is updated from the library excpet unprotected symbol properties. The unprotected symbol properties are typically used to store parameter information, such as the Deadtime property used in the LLC Modulator example. If you changed the Deadtime value on the symbol contained in the schematic component file, that change will not be reflected on the schematic.
A list of installed libraries can be found by opening the Symbol Manager. The SIMetrix/SIMPLIS menu bar:opens the following dialog:
With this dialog, you can determine which libraries contain which symbols and add, remove, or create symbol libraries. The Help button links to a comprehensive help topic on the use of the Symbol Manager.
You can also install symbol libraries by the "drag-and-drop" method. Simply open a Windows Explorer window to the location of the symbol library file, and drag-and-drop the file to the SIMetrix/SIMPLIS command shell window. No message is given after you drop the symbol library file, the symbol library is installed quietly. You can always check the installed symbol libraries with the Symbol Manager.
The netlisting process was described in section 3.0.1 What Happens When You Press F9?. In that topic, the REF, MODEL, TEMPLATE and SIMPLIS_TEMPLATE properties were covered in some detail. The SIMPLIS_TEMPLATE property was covered in detail in the 3.0.2 What Actual Device is Simulated in SIMPLIS? topic. Several other special symbol properties exist:
|Symbol Property Name||Function|
|VALUESCRIPT||The script name which is called when a user double clicks on the symbol or presses F7. This usually opens a dialog to edit parameter values. The parameter values are saved to the symbol as symbol properties.|
|PARAMSCRIPT||The script name which is called when the user right clicks and executes the Edit Additional Parameters... context menu option or presses the keyboard shortcut Ctrl+Alt+F7.|
|TEMPLATESCRIPT||Defines the script name to be executed to modify the symbol template value during netlist generation.|
|INITSCRIPT||The script name used to back annotate the initial conditions for this symbol.|
|PARAMS||Passes parameters to the subcircuit. This is the shortcut method and is not the preferred method.|
|LABELS||Reserved for parameter editing dialogs.|
|PARAMETERS||Reserved for parameter editing dialogs.|
|TABS||Reserved for parameter editing dialogs.|
|GROUPS||Reserved for parameter editing dialogs.|
|DESCRIPTIONS||Reserved for parameter editing dialogs.|
|SIMULATOR||Determines the symbol's compatibility with the SIMetrix or SIMPLIS simulators.|
|schematic_path||The full or relative path to the underlying schematic. Used for Schematic Component files.|
You should avoid using the special symbol properties for purposes other than their designated function. A full listing of special symbol properties can be found in the User's manual at: What is a Property?