2.3.5 Subcircuit Parameters

Instantiating Element Values in Subcircuit Definitions

Although reference designators and internal node identifiers in subcircuit netlists are always uniquely instantiated we still have to cope with one difficulty that arises when working with multiple references to the same model definition. Consider the following small-signal equivalent circuit of a Darlington amplifier (see Figure 3.3) for which we shall have to compute the overall current gain as a function of the individual current gains of the two transistors Q1 and Q2. The gain can be obtained by calculating the output response to a unit current applied at the input.

Figure 3.3: Darlington amplifier (small-signal equivalent circuit)

Let's decide to use the transistor model NPNTransistor/ACsimple from Section 2.3.2 (see Figure 3.2) for both transistors. We would then write the circuit description and expand the model references as follows.

Remember that the Pattern option in the value field of the netlist entry Load causes the current through the load resistor to be introduced into the modified nodal equations, allowing us to compute the current directly. Alternatively, we could have inserted a short circuit in between RL and node 2 for measuring the current.

In[9]:= Circuit[
Netlist[
{I1, {0, 1}, 1},
{Q1, {1 -> "B", 2 -> "C", 3 -> "E"},
Model -> NPNTransistor, Selector -> ACsimple},
{Q2, {3 -> "B", 2 -> "C", 0 -> "E"},
Model -> NPNTransistor, Selector -> ACsimple},
{Load, {0, 2}, Type -> Resistor, Value -> RL,
Pattern -> Impedance}
],

Model[
Name -> NPNTransistor,
Selector -> ACsimple,
Ports -> {"B", "C", "E"},
Definition ->
Netlist[
{RB, {"X", "E"}, RB},
{CC, {"B", "X", "C", "E"}, beta}
]
]
] // ExpandSubcircuits // DisplayForm

Out[12]//DisplayForm=

While ExpandSubcircuits has generated unique identifiers for the base resistor RB and the current-controlled current source CC for each instance of the transistor model, it has not made any changes to the associated symbolic element values RB and beta. Obviously, these have been regarded as global symbols, resulting in identical base resistances and current gains of both transistors. This is certainly not the result we wanted because the individual current gains of the transistors in a Darlington stage may be quite different. Instead, ExpandSubcircuits should instantiate the element values as well, and thus generate the symbols RB$Q1, RB$Q2, beta$Q1, and beta$Q2 for the two resistors and the two current gains respectively.

The reason behind the unwanted behavior exhibited here is that ExpandSubcircuits has not been explicitly instructed to treat RB and beta as what they really are, namely as parameters of the model. We can solve this problem by adding the parameter declaration

Parameters -> {RB, beta}

to our Model definition, which instructs ExpandSubcircuits to replace all occurrences of these symbols in the value fields of the subcircuit netlist by different identifiers for each subcircuit instance.

In[10]:= darlington =
Circuit[
Netlist[
{I1, {0, 1}, 1},
{Q1, {1 -> "B", 2 -> "C", 3 -> "E"},
Model -> NPNTransistor, Selector -> ACsimple},
{Q2, {3 -> "B", 2 -> "C", 0 -> "E"},
Model -> NPNTransistor, Selector -> ACsimple},
{Load, {0, 2}, Type -> Resistor, Value -> RL,
Pattern -> Impedance}
],

Model[
Name -> NPNTransistor,
Selector -> ACsimple,
Ports -> {"B", "C", "E"},
Parameters -> {RB, beta},
Definition ->
Netlist[
{RB, {"X", "E"}, RB},
{CC, {"B", "X", "C", "E"}, beta}
]
]
]

Out[13]=

In[11]:= ExpandSubcircuits[darlington] // DisplayForm

Out[14]//DisplayForm=

After having been defined as parameters, the base resistances and current gains appear properly instantiated in the flat netlist. We can now complete our analysis of the Darlington amplifier by solving the MNA equations for the load current I$Load.

In[12]:= eqDarlington = CircuitEquations[darlington];
DisplayForm[eqDarlington]

Out[16]//DisplayForm=

In[13]:= Solve[eqDarlington, I$Load]

Out[17]=

For large current gains beta$Q1 and beta$Q2, the contribution of the product dominates this sum, resulting in the known current-gain formula for a Darlington stage. Later, in Chapter 2.8, we will learn how to let Analog Insydes extract such dominant contributions automatically in order to provide compact and interpretable symbolic analysis results.

A Remark on Local and Global Symbols

Critical reading of the preceding text may give rise to the following question: Why are identifiers of internal nodes always instantiated even though they are not explicitly declared as local symbols while symbolic element values are assumed to be global symbols unless they are explicitly declared as parameters? The logic behind this behavior is that it hardly makes sense to regard any internal node identifier in a generic subcircuit definition as a global symbol - except for rare cases in which the global ground node is involved. Whenever we need to connect a subcircuit to a global node we must make the connection via a port node. Otherwise, from the point of view of the subcircuit definition, we would have to exploit bottom-up knowledge about the set of node names in the top-level netlist, either to be sure that a certain global node is present or in order to prevent name clashes. Consequently, the only reasonable option is that all nodes which are not ports must be local, hence they are instantiated individually.

On the other hand, there are some applications where the element values of multiple subcircuit instances are supposed to be identical, for example in repetitive circuit structures like RLC ladder networks. If the element values in the subcircuit definition were generally treated as local parameters then, after subcircuit expansion, we would have to go through the tedium of manually assigning the same global symbols to all instances of the corresponding subcircuit element values. This would not be very convenient as it would require typing something along the line of for every group of identical elements. By explicitly declaring which symbols in a subcircuit denote parameters and quietly assuming all others to be global quantities, cases like that of the Darlington amplifier as well as that of the ladder circuit are both dealt with most easily. However, Analog Insydes provides the command MatchSymbols which applies matching information on a DAEObject. Thus, you can decide which parameters to match even after setting up the equation system.

Passing Parameter Values to Subcircuit Instances

Though intentional and useful, the automatic instantiation of symbolic subcircuit parameters is only a side effect of the parameter declaration. The original purpose of the Parameters argument in a Model definition is to declare the set of local model variables which can be replaced by instance-specific values given in the value fields of subcircuit references (see Section 3.1.8). In other words, we can pass parameter values to a subcircuit in a similar way as we can pass arguments to a function defined in Mathematica. Since we do not have to specify values for model parameters, automatic instantiation comes into effect whenever a default value is needed for a parameter which has not been assigned a value.

If we need to pass parameter values to instances of subcircuit objects we must append a sequence of replacement rules of the form

parameter symbol -> value

to the value field of the corresponding subcircuit references. The full netlist format of a subcircuit reference is thus

subcircuit instance name, port connections,

Model -> subcircuit class name, Selector -> selector,

-> , -> ,

To illustrate the possible cases consider the netlist of the Darlington amplifier from Section 2.3.5 (see Figure 3.3) once again. Let's assign the symbolic value RB1 and a numerical value of to the parameters RB and beta of Q1, respectively. In the case of Q2, we assign the symbol beta2 to the current gain whereas we leave the parameter RB unspecified.

In[14]:= Circuit[
Netlist[
{I1, {0, 1}, 1},
{Q1, {1 -> "B", 2 -> "C", 3 -> "E"},
Model -> NPNTransistor, Selector -> ACsimple,
RB -> RB1, beta -> 150},
{Q2, {3 -> "B", 2 -> "C", 0 -> "E"},
Model -> NPNTransistor, Selector -> ACsimple,
beta -> beta2},
{Load, {0, 2}, Type -> Resistor, Value -> RL,
Pattern -> Impedance}
],

Model[
Name -> NPNTransistor,
Selector -> ACsimple,
Ports -> {"B", "C", "E"},
Parameters -> {RB, beta},
Definition ->
Netlist[
{RB, {"X", "E"}, RB},
{CC, {"B", "X", "C", "E"}, beta}
]
]
] // ExpandSubcircuits // DisplayForm

Out[18]//DisplayForm=

During subcircuit expansion, the model parameters have now been replaced by the values from the top-level netlist. As we did not assign a value to the base resistor of Q2, the automatic instantiation mechanism has created the symbol RB$Q2 in order to provide a default value for RB.