Template Property
In this topic:
Overview
The Template property provides a method of customising the netlist entry for a schematic part. Normally a single line is created in the netlist for each schematic part (except 'F' and 'H' devices which are defined by two lines). The line is created according to the values of various properties most importantly the ref, model, and value properties. If, however, a Template property is specified this system is bypassed and the netlist entry is defined by the value of this property.
The Template property value can contain a number of special keywords and characters that will be substituted during the netlist creation. Values that can be substituted include node names, pin names and the value of any property.
There are three template keywords that define multiple lines to implement series or/and parallel combinations, ladder networks or arrays of devices.
Template Property Format
The netlist entry for a device with a Template property will be the literal text of the Template property's value with certain special characters and words substituted. Text enclosed by '<' and '>' are keywords and have a special meaning. Text enclosed with '%' is substituted with the value of the property whose name is enclosed by the '%' character. Finally text enclosed by curly braces, '{' and '}' will be treated as an expression and will be evaluated. Each of these is described in more detail in the following sections.
Property Substitution
Any text enclosed with '%' is substituted with the value of the property whose name is enclosed by the '%' character. So %REF% would be substituted with the value of the ref property.
Expressions
Text enclosed by curly braces, '{' and '}' will be treated as an expression and will be evaluated. Note that property substitutions are performed before expressions are evaluated, so the result of an expression can depend on any combination of property values.
If the attempt to evaluate the expression fails the result will be empty. No error message will be reported.
Keywords
Any text enclosed by '<' and '>' represents a keyword. The keyword along with the '<' and '>' will be substituted according to the keyword as defined in the following table. There are two types of keyword: simple and compound. Simple keywords are just a single word whereas compound keywords consist of sequence of names and values separated by colons (':'). Compound keywords are used to generate multiple netlist lines for applications such as creating series and parallel combinations.
How Template Properties are Evaluated
Template properties are processed in two passes. In the first pass the property names enclosed by '%' are substituted, while keywords and expressions pass through untouched. In the second pass, keywords and expressions are processed and the '%' character is treated literally.
This makes it possible to use property values in expressions and the control values for the multi line keywords. For example:
%MODEL%$%REF% <nodelist> %VALUE% L=%L% W=%W% AD={%W%*0.5u}
if L=1u, W=0.5u, MODEL=M, REF=Q23 and VALUE = N1, this would resolve to the following after the first pass:
M$Q23 <nodelist> N1 L=1u W=0.5u AD={0.5u*0.5u}
The second pass would then be able to evaluate the expression and resolve <nodelist> (see below). The value of AD will be calculated according to whatever W is set to. This is an alternative method of setting MOSFET area and perimeter values. (The method used with the standard symbols is different in order to remain compatible with earlier versions).
Note that if the property value contains any of the special characters ('<', '>', '{', '}', '%'), these will be treated literally. So if for example a property value was {tailres}, no attempt would be made to evaluate {tailres} in the second pass.
Keyword Summary
The keywords available are summarised in the following table and explained in detail below.
| Keyword | Description |
| BUS | Returns name of bus connected to the specified pin |
| FOREACHPIN | Repeats for each pin |
| IFD | Conditional on whether a property is defined |
| IF | Conditional on the result of an expression |
| INODE | Generates an internal node. |
| JOIN, JOIN_PIN, JOIN_NUM, JOIN_REF | Returns information about a connected device. Used for current probes. |
| MAPPEDNODE[n] | As 'node' but order defined by mapping property if present |
| MAPPEDPINNAMES | As pinnames but order is altered according to mapping property if present |
| NODELIST, NODELIST_H | Substituted with full list of nodes for device. |
| NODENAME | This is not replaced by any text but signifies that the item following is a node name. The netlist generator must be able to identify any text that is a node so that it can correctly substitute the name when required. |
| NODE[n] | Substituted for individual node |
| NUMPINS | Returns the number of pins on a symbol |
| PARALLEL | Start of compound keyword to create a parallel combination. |
| PARAMSVALUE | Returns passed parameters |
| PINLIST | Substituted with full list of pin names for symbol |
| PINNAMES | Equivalent to 'pinnames: <pinlist>' except that no substitution takes place if the /nopinnames switch is specified for the Netlist command. |
| PROBE | Similar to node but resolves mapped nodes in SIMPLIS mode |
| REF | SPICE compatible part reference |
| REPEAT | Start of compound keyword to create a general purpose repeating sequence |
| ROOTDIR | Root schematic directory in hierarchical design |
| ROOTPATH | Root schematic full path in hierarchical design |
| SCHEMDIR | This schematic directory |
| SCHEMPATH | This schematic full path |
| SEP | Returns separator character. (Usually '$') |
| SERIES | Start of compound keyword to create a series combination |
| STEP | Used by series and parallel to return sequence number. |
| T | Substitutes a property value treating it as a template |
| VALUE | Returns the resolved value |
BUS
<BUS[n]>
Returns the name of the bus connected to the n'th pin.
FOREACHPIN
<FOREACHPIN:var:<body>>
Repeats body for each pin on the symbol. var is a variable that will be assigned with the pin number being processed and may be used inside an expression.
body may also use keywords <node> and <pin> to access connected nodes and pin names respectively.
IFD
<IFD:propname:action1[:action2]>If propname is present and not blank, action1 will be substituted otherwise action2 will be substituted.
ifd:value:<%value%>:1>
In the above, if the property value is present it will be substituted otherwise the value '1' will be substituted.
IF
<IF:test:action1[:action2]>If test resolves to a non-zero value action1 will be substituted otherwise action2 will be substituted. Typically test would be an expression enclosed in curly braces. ('{' and '}').
<REPEAT:line:%SERIES%:<%REF%$R{line} <if:{line==
1}:<<NODE[1]>>:$%REF%${line}> <if:{line==
%SERIES%}:<<NODE[2]>>:$%REF%${line+1}> %VALUE%;>>
Note that usually each action should be enclosed with '<' and '>'. They can be omitted if the action does not contain any keywords. If in doubt, put them in.
INODE
<INODE:name>Resolves to a unique node number that is guaranteed not be used anywhere else. The value name may be used to identify the number for repeated use within the same TEMPLATE. For example <inode:a> will always resolve to the same node number if used more than once within the same TEMPLATE definition.
INODE is intended to be used to create devices that need multiple netlist lines with connected nodes. This can also be done using a subcircuit but for simple cases INODE may be more convenient.
JOIN
<JOIN:prop_name[:index]>
This can only be used with instances of symbols with one and only one pin. Returns the value of prop_name on an instance attached directly to the single pin of the device. For example in the following:
<JOIN:REF> on the probe (R1-P) would return R1 as this is the value of the REF property of the resistor. In situations where more than one instance is connected to the pin, index may be used to specify which one. index may have a value between 0 and 1 less than the number of devices connected. Use <join_num> to determine how many devices are connected.
Note that the pin of the device must be directly connected i.e. with pins superimposed and not by wires.
<JOIN> is intended to be used for current probes.
JOIN_REF
<JOIN_REF>Similar to <JOIN:REF> except that instead of the literal REF property, it returns how the connected instance is identified in the netlist. This takes account of any TEMPLATE property the connected instance possesses or the MODEL property prefix if it does not have a TEMPLATE property.
JOIN_NUM
<JOIN_NUM>Only valid for single pin instances. Returns number of joined devices. See <JOIN> for details.
JOIN_PIN
<JOIN_PIN[:index]>Only valid for single pin instances. Returns connected pin name for another device connected to this device's only pin. This can be used in conjunction with <JOIN> to return the current vector for a part. E.g.
<JOIN:REF>#<JOIN_PIN>
for the probe device in:
would return R1#p.
In situations where more than one instance is connected to the pin, index may be used to specify which one. index may have a value between 0 and 1 less than the number of devices connected. Use <join_num> to determine how many devices are connected.
MAPPEDNODE
<MAPPEDNODE[n]>Same as NODE except that the mapping property is applied. The mapping property is used to rearrange nodes in a different order than defined on the symbol. It is used by the model-symbol association system to allow a single symbol to be associated with multiple models that may not necessarily have the same terminal order.
MAPPEDPINNAMES
<MAPPEDPINNAMES>As PINNAMES but with the mapping property applied. See MAPPEDNODE above.
NODELIST, NODELIST_H
<NODELIST[:map[|nox]]> <NODELIST_H[:map[|nox]]>Replaced by the nodes connected to the device's pins. NODELIST_H includes hidden global pins (see Global Pins) used in hierarchical schematics whereas NODELIST omits these. Has two options:
| map | If present will order the nodes according to the MAPPING property. |
| nox | If present, will disable XSpice pin attributes. See Adding XSpice Pin Attributes for details. |
NODENAME
<NODENAME>
This is not replaced by any text but signifies that the item following is a node name. The netlist generator must be able to identify any text that is a node so that it can correctly substitute the name when required. For example, the following is the template definition of the N-channel MOSFET with bulk connected to VSS:
%model%$%ref% <nodelist> <nodename>vss %value%
If VSS were actually connected to ground, the netlist generator would replace all nodes called VSS with 0 (meaning ground). If the <nodename> keyword were not present in the above the netlist generator would not be able to determine that VSS is a node and the substitution would not take place.
NODE
<NODE[n]>Replaced by the individual node identified by n starting at 1. So node[1] is node name connected to the first pin on the symbol.
NUMPINS
<NUMPINS>
Returns the number of pins on the symbol owning the TEMPLATE property.
PARALLEL
<PARALLEL:num:<line>>
Creates a parallel combination of the device described in line. For example:
<parallel:%parallel%:<<ref> <nodelist> %VALUE%>>
creates a parallel combination of parts. The number in parallel is determined by the property PARALLEL. Note that the REF keyword returns the part reference appropriately modified by the MODEL property and appended with the sequence number. If PARALLEL=5, REF=R1, VALUE=1k, MODEL=R and the device is connected to external nodes R1_P and R1_N, this is the end result.
R1$1 R1_P R1_N 1k R1$2 R1_P R1_N 1k R1$3 R1_P R1_N 1k R1$4 R1_P R1_N 1k R1$5 R1_P R1_N 1k
If the num element is empty - e.g. in above example if PARALLEL property were empty or missing - then no output will be made at all.
The example above can be used for any two terminal part. There must however be a PARALLEL property present on the symbol.
PARAMSVALUE
<PARAMSVALUE>
Returns the instance's parameters. This is defined by the PARAMS property and will be prefixed with the parameter separator for subcircuit devices. This is params: for SIMetrix mode and vars: for SIMPLIS mode. This keyword will also include tolerance parameters defined by the properties LOT, TOL and MATCH if present.
PINLIST
<PINLIST>Replaced by the symbol's pin names.
PINNAMES
<PINNAMES>
Equivalent to 'PINNAMES: <PINLIST>' except that no substitution takes place if the /nopinnames switch is specified for the Netlist command.
PROBE
<PROBE[n]>
In SIMetrix mode, behaves identically to NODE. In SIMPLIS mode, will return the mapped node name if relevant. This will happen if the node has a name defined by a terminal symbol. Instead of the assigned node number this keyword will return the node name prefixed by a '#'. As the name implies, this is intended for use with probe symbols.
REF
<REF>
Returns the part reference of the device using the same rules that are used when the Template property is not present. The rules are:
IF MODEL property is blank OR MODEL is a single character AND first letter of REF property equals MODEL property
<REF> = %REF%
otherwise
<REF> = %MODEL%<SEP>%REF%
Where <SEP> is the separator character. This is usually '$' but can be changed at the netlist command line. See Netlist command syntax in the Script Reference Manual/Command Reference/Netlist.
If <REF> is used for a series or parallel repeat sequence, it will be appended with:
<SEP><STEP>
where <STEP> is the sequence number for the series/parallel function. See below.
REPEAT
Repeats line, num times. var_name is incremented on each step. var_name may be used in an expression to define device or node names.
The following example creates a subcircuit that define an RC ladder circuit with a variable number of sections defined by the property NUM. The resistance of each section is defined by the property RES and the capacitance by the property CAP. Note that, as explained above, templates are resolved in two passes. In the first pass the property names enclosed by '%' are substituted with their values while expressions and keywords are left untouched. In the second pass the keywords and expressions are processed.
.subckt ladder 1 {%NUM%+1} gnd
<repeat:idx:%NUM%:<X{idx} {idx} {idx+1} gnd section;>>
.subckt section in out gnd
R1 in out %RES%
C1 out gnd %CAP%
.ends
.ends
X{idx} {idx} {idx+1} gnd section;
would be repeated 10 times with idx incrementing by one each time. Note the semi-colon at the end of the line. This signifies that a new line must be created and is essential. The end result of the above with NUM=10, RES=1k and CAP=1n is:
.subckt ladder 1 11 gnd X1 1 2 gnd section X2 2 3 gnd section X3 3 4 gnd section X4 4 5 gnd section X5 5 6 gnd section X6 6 7 gnd section X7 7 8 gnd section X8 8 9 gnd section X9 9 10 gnd section X10 10 11 gnd section .subckt section in out gnd R1 in out 1k C1 out gnd 1n .ends .ends
Although it is legal to nest REPEAT keywords, we recommend avoiding doing so as it can lead to unexpected results. You can always use subcircuit definitions to each multi-dimensional repeats and these are usually easier to understand.
The above example has multiple lines. These can be entered using the Edit Properties dialog box. The best way to define multiple line templates is to first enter them in a text editor and then copy and paste to the Edit Properties dialog.
ROOTDIR
Returns the root directory in a hierarchical design. If the design is not hierarchical, returns the same value as <SCHEMDIR>.
ROOTPATH
Returns the full path of the root schematic in a hierarchical design. If the design is not hierarchical, returns the same value as <SCHEMPATH>.
SCHEMDIR
Returns the directory where the current schematic is located.
SCHEMPATH
Returns the full path of the current schematic.
SEP
<SEP>
Returns separator character used to separate the device letter and part reference. This defaults to '$' but can be changed at the Netlist command line. See Netlist command syntax in the Script Reference Manual/Command Reference.
SERIES
<SERIES:num:<line>>
Creates a series combination of the device described in line. For example:
<series:%series%:<<ref> <nodelist> %VALUE%>>
Creates a series combination of parts. The number in series is determined by the property SERIES. Note that the REF keyword returns the part reference appropriately modified by the MODEL property and appended with the sequence number. If SERIES=5, REF=R1, VALUE=1k and MODEL=R and the device is connected to external nodes R1_P and R1_N, this is the end result.
R1$1 R1_P 1 1k R1$2 1 2 1k R1$3 2 3 1k R1$4 3 4 1k R1$5 4 R1_N 1k
If the num element is empty - e.g. in above example if SERIES property were empty or missing - then no output will be made at all.
The example above can be used for any two terminal part. There must however be a SERIES property present on the symbol.
STEP
<STEP>Used with SERIES and PARALLEL keywords. Returns sequence number.
T
<T:prop_name>Does the same as %prop_name% except that the properties value is evaluated as if it were a template itself. With %prop_name% the literal value of the property is always used. Note that recursive properties will simply be substituted with nothing. E.g. <T:TEMPLATE> will return empty if used in a template property called TEMPLATE.
VALUE
<VALUE>Returns the VALUE property value unless the instance is a hierarchical block in which case it returns the name of the referenced subcircuit definition.
Further Information
To put a new line in the netlist entry you can use a ';'. Literal new lines are also accepted.
To put a literal < >; {} or % character in the text, use two of them. So '<<' will become '<'.
Template Scripts
It is also possible to write a script to compile the line generated by the netlist generator. Such scripts are called 'Template Scripts'. With this approach, you enjoy the full power of the scripting language and very complex devices can be created in this manner. For full details of this approach, please refer to the Script Reference Manual/Applications/Schematic Template Scripts.
| ◄ Properties | Load Component Values ▶ |