2.3.6 The Scope Argument

Local and Global Subcircuit Definitions

In all the preceding examples, the top-level netlist is immediately followed by the definitions of the subcircuits referenced from within the netlist. These subcircuit definitions are local and volatile because they are neither visible outside the scope of the enclosing Circuit statement nor do they "survive" subcircuit expansion. When doing multiple circuit analyses with a number of frequently used device models it would be rather tedious if we always had to include all potentially selected models in the circuit description together with the top-level netlist. Therefore, we have the option to make any subcircuit definition permanent and accessible from within other netlists by providing an appropriate Scope argument (see Section 3.2.1). Scope has two possible values, Local and Global. To make a subcircuit available globally, we need to set the scope as follows:

Scope -> Global

By expanding a circuit which contains only model definitions with global scope we can implement a globally accessible model library in our current Mathematica environment. For example, let's set up a model library from the two NPN transistor models NPNTransistor/ACsimple and NPNTransistor/ACdynamic from Section 2.3.2 (see Figure 3.2).

In[15]:= Circuit[
Model[
Name -> NPNTransistor,
Selector -> ACsimple,
Scope -> Global,
Ports -> {"B", "C", "E"},
Parameters -> {RB, beta},
Definition ->
Netlist[
{RB, {"X", "E"}, RB},
{CC, {"B", "X", "C", "E"}, beta}
]
],

Model[
Name -> NPNTransistor,
Selector -> ACdynamic,
Scope -> Global,
Ports -> {"B", "C", "E"},
Parameters -> {RB, CM, beta, RO},
Definition ->
Netlist[
{RB, {"X", "E"}, RB},
{CM, {"B", "C"}, CM},
{CC, {"B", "X", "C", "E"}, beta},
{RO, {"C", "E"}, RO}
]
]
] // ExpandSubcircuits;

Both models are now stored in the global subcircuit database and can thus be referenced by any other netlist. Note that simply defining the models is not sufficient for storing them in the global database - we have to call ExpandSubcircuits in order to store them into the global database. If the Circuit object contains a top-level Netlist, a call to CircuitEquations stores the models in the global database, too. We can check the contents of the database using the command GlobalSubcircuits, which will return a list of the names and selectors of the global subcircuits.

In[16]:= GlobalSubcircuits[]

Out[20]=

The global definition of the transistor models allows us to write the circuit description of the Darlington amplifier from Section 2.3.5 (see Figure 3.3) without the Model commands. Then, during subcircuit expansion, the global database will be searched for models which are not defined locally.

In[17]:= darlWithoutModels =
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}
]
];

In[18]:= ExpandSubcircuits[darlWithoutModels] // DisplayForm

Out[22]//DisplayForm=

Redefining and Removing Global Subcircuits

If ExpandSubcircuits or CircuitEquations is called on a Circuit object containing a global model definition, any previously stored model in the global database with the same Name and Selector arguments is replaced by the new one. To remove a particular subcircuit from the global database we can use the command RemoveSubcircuit. Its arguments must be the name and the selector of the subcircuit definition to be deleted. The return value is a list of the names and selectors of the remaining subcircuit definitions. For example, let's remove the transistor model NPNTransistor/ACdynamic. The only remaining model is then NPNTransistor/ACsimple:

In[19]:= RemoveSubcircuit[NPNTransistor, ACdynamic]

Out[23]=

Locally Overriding Global Subcircuit Definitions

One further application of the Scope argument is that we can locally override a global subcircuit definition. Local subcircuits always take precedence over global definitions with the same name and selector without overwriting the global definition. To illustrate this, let's temporarily replace the NPNTransistor/ACsimple model with the subcircuit shown in Figure 3.4. The difference between the original implementation of NPNTransistor/ACsimple and this model is that the latter contains a voltage-controlled current source VCCSource instead of a current-controlled current source CCCSource.

Figure 3.4: Transistor model with voltage-controlled current source

Although the global subcircuit database still contains a definition of NPNTransistor/ACsimple we can safely use the same name and selector for a local subcircuit without changing the global definition, provided we specify Scope -> Local. Upon subcircuit expansion, Analog Insydes first looks for a local subcircuit with the requested name and selector. The global definition is retrieved only if no matching local definition is present.

In[20]:= darlWithLocalModel =
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,
Scope -> Local,
Ports -> {"B", "C", "E"},
Parameters -> {RB, gm},
Definition ->
Netlist[
{RB, {"B", "E"}, RB},
{VC, {"B", "E", "C", "E"}, gm}
]
]
];

Now, ExpandSubcircuits will use the local definition of NPNTransistor/ACsimple. The global definition has not been altered, as we can see by expanding the netlist of the Darlington amplifier from Section 2.3.5 (see Figure 3.3) without models again.

In[21]:= ExpandSubcircuits[darlWithLocalModel] // DisplayForm

Out[25]//DisplayForm=

In[22]:= ExpandSubcircuits[darlWithoutModels] // DisplayForm

Out[26]//DisplayForm=