Subcircuits

In this topic:

Overview

Subcircuits are a method of defining a circuit block which can be referenced any number of times by a single netlist line or schematic device. Subcircuits are the method used to define many device models such as op-amps.

Subcircuit Definition

Subcircuits begin with the .SUBCKT statement and end with .ENDS. A subcircuit definition is of the form:

.SUBCKT subcircuit_name nodelist [[params:] default_parameter_list]
definition_lines
.ENDS
subcircuit_name Name of the subcircuit and is used to reference it in the main netlist.
nodelist Any number of node names and are used for external connections. The subcircuit call (using an 'X' device) would use a matching number of nodes in the same order.
default_parameter_list List of parameters and their default values in the form name=value. Subcircuit parameters are explained in Using Expressions.
definition_lines List of valid device and model lines. In addition, .NODESET, .IC and .KEEP lines may also be placed in a subcircuit.

Example

This is an example of an opamp subcircuit called SXOA1000. VINP, VINN VOUT VCC and VEE are its external connections. The three .model lines define devices that are local, that is, they are only accessible within the subcircuit definition.

.subckt SXOA1000 VINP VINN VOUT VCC VEE
I2 D2_N VEE 100u
I1 Q3_E VEE 100u
C1 VOUT R1_P 10p
D1 Q7_C D1_N D1
D2 D1_N D2_N D1
D3 VEE Q3_E D1
Q2 VEE D2_N VOUT 0 P1
Q3 Q3_C R3_P Q3_E 0 N1
Q1 VCC Q7_C VOUT 0 N1
Q6 Q3_C Q3_C VCC 0 P1
Q7 Q7_C Q5_C VCC 0 P1
R1 R1_P Q5_C 100
Q4 Q5_C R2_N Q3_E 0 N1
R2 VINP R2_N 1K
Q5 Q5_C Q3_C VCC 0 P1
R3 R3_P VINN 1K

.model N1 NPN VA=100 TF=1e-9
.model P1 PNP VA=100 TF=1e-9
.model D1 D

.ends

Where to Place Subcircuit Definition

Subcircuit definitions may be placed in a number of locations.

Subcircuit Instance

Once a subcircuit has been defined, any number of instances of it may be created. These are of the form:

Xxxxx nodelist sub_circuitname [ [params:|:] parameters]
nodelist List of nodes, each of which will connect to its corresponding node in the subcircuit's definition. The number of nodes in the instance must exactly match the number of nodes in the definition.
sub_circuitname Name of the subcircuit definition.
parameters List of parameter names and their values in the form name=value. These may be referenced in the subcircuit definition. Subcircuit parameters are explained below.

Passing Parameters to Subcircuits

You can pass parameters to a subcircuit. Consider the filter example provided in Using Expressions. Supposing we wanted to define several filters with different characteristics. We could use a subcircuit to define the filter but the values of the components in the filter need to be different for each instance. This can be achieved by passing the parameter values to each instance of the subcircuit.

So:

** Definition
.SUBCKT Filter IN OUT params: C1=1n alpha=1 f0=1k
C2 0 R1_P {C1*alpha*alpha/4}
C1 OUT R1_N {C1}
E1 OUT 0 R1_P 0 1
R1 R1_P R1_N {2/(2*pi*f0*C1*alpha)}
R2 R1_N IN {2/(2*pi*f0*C1*alpha)}
.ENDS

** Subcircuit instance
X1 V1_P VOUT Filter : C1=10n alpha=1 f0=10k

** AC source
V1 V1_P 0 AC 1 0

In the above example the parameters after params: in the .subckt line define default values should any parameters be omitted from the subcircuit instance line. It is not compulsory to define defaults but is generally recommended.

Note

In the syntax definition for both subcircuit definitions and subcircuit instances, the params: specifier is shown as optional. If params: is included the '=' separating the parameter names and their values becomes optional.

Nesting Subcircuits

Subcircuit definitions may contain both calls to other subcircuits and local subcircuit definitions.

If a subcircuit definition is placed within another subcircuit definition, it becomes local. That is, it is only available to its host subcircuit.

Calls to subcircuits may not be recursive. A subcircuit may not directly or indirectly call its own definition.

Global Nodes

Sometimes it is desirable to refer to a node at the circuit's top level from within a subcircuit without having to explicitly pass it. This is sometimes useful for supply rails.

SIMetrix provides three methods.

  • '#' prefix. Any node within a subcircuit prefixed with '#' will connect to a top level node of the same name without the '#' prefix.
  • '$g_' prefix. Any node in the circuit prefixed '$g_' will be treated as global.
  • Using .GLOBAL.

The second approach is compatible with PSpice®. The third approach is compatible with Hspice®

Note the first two approaches are subtly different. In the second approach the '$g_' prefix must be applied to all connected nodes, whereas in the first approach the '#' prefix must be applied only to subcircuit nodes.

Subcircuit Preprocessing

SIMetrix features a netlist preprocessor that is usually used for SIMPLIS simulations and was developed for that purpose. The preprocessor has some features that aren't available in the native simulator and for this reason it would be useful to be able to use the preprocessor for SIMetrix simulations.

It is not necessary to apply the preprocessor to the entire netlist. Any subcircuit call that defines preprocessor variables using the 'vars:' specifier will be passed to the preprocessor. For example:

X$C1 R1_P 0 ELEC_CAP_L13 vars: LEVEL=3 CC=1m
+ RSH_CC=1Meg IC=0 RESR=10m LESL=100n USEIC=1

calls the ELEC_CAP_L13 subcircuit but passes it through the preprocessor first. This model is a model for an electrolytic capacitor and uses a number of .IF statements to select model features according to the LEVEL parameter.

The preprocessor also provides a means of generating multiple devices using .WHILE. For information on the preprocessor, see the SIMPLIS Reference Manual/Running SIMPLIS/Netlist Preprocessor.