Spice OPUS homepage

CACD Group
updated 2000.03.30
Author Arpad Buermen

XSPICE Extensions

Selecting How SPICE OPUS Expands Subcircuits

SPICE OPUS uses by default the new (XSPICE) style subcircuit expansion. In case you want the simulator to expand subcircuits the old (SPICE3) way, enter the following command in Nutmeg prompt or spinit file:

  set oldsubcktexp

To switch back to the new style subcircuit expansion (XSPICE), enter:

  unset oldsubcktexp

In case you never access subcircuit nodes, elements or models in your Nutmeg scripts, it doesn't matter which type of subcircuit expansion you are using. The type of subcircuit expansion used at parse time for a specific circuit predetermines the manner in which you can access subcircuit nodes, elements and models for that circuit.
To put it in short: in case you have a Nutmeg .control block in a netlist and you get messages that some nodes/devices/models can't be found when the .control block is executed, try switching to old (SPICE3) subcircuit parsing and reload the circuit.

Global nodes

In version 2.02 .global HSPICE option was introduced. This option makes certain nodes global thus preventing their expansion when they are found in subcircuits. Ground node (0) is global by default. To make nodes global, enter the following option in your netlist:

  .global node1 [node2 [node3 ...]]

To make nodes vdd and vss global enter the following option in your netlist:

  .global vss vdd

Now all nodes named vdd and vss are no longer expanded when they are inside subcircuits.

Introduction to Subcircuits

A subcircuit can be declared using the following syntax:

 
 .subckt subckt_name node1 node2 node3 ...
 subckt netlist
 .ends

Nodes node1, node2, ... are the interface to the outside world. Node 0 inside a subcircuit has the same meaning as everywhere else (ground node). A subcircuit can be used in your netlist:

  x1 node1 node2 node3 ... subckt_name

The above statement puts subcircuit named subckt_name as subcircuit instance x1 in your circuit and connects it to nodes node1, node2, node3, ...
Let's take a look at an example:

  .subckt attenuator in out comm
  r1 in  int  16.67 rmod1
  r2 int out  16.67 rmod1
  r3 int comm 66.67 rmod1
  .model rmod1 r tc1=0.001 tc2=0.0001
  .ends

The subcircuit defined above is a 6dB attenuator with temperature dependence caused by the temperature dependence of resistors (see resistor model rmod1). Model rmod1, devices r1, r2 and r3 and node names in, out, comm and int are valid only inside this subcircuit. You can reuse these names somewhere else in the netlist without worrying about name conflicts.
In order to use this subcircuit in a netlist the x element must be used:

  xexample1 6 7 0 attenuator

This places subcircuit attenuator as subcircuit instance xexample1 in your circuit and connects nodes in, out and comm of the subcircuit to nodes 6, 7 and 0 of the circuit.
Subcircuits can be used also in higher level subcircuits. As an example let's build a 12dB attenuator from two 6dB attenuators:

  .subckt bigatten in out
  xnested1 in int 0 attenuator
  xnested2 int out 0 attenuator
  .ends

To use subcircuit bigatten, insert the following line in the netlist:

  xexample2 7 8 bigatten

The depth of nested subcircuits (like the one above) is not limited.

Subcircuit Expansion

In order to refer to internal nodes, devices and models inside subcircuits you must know how the names are expanded before the netlist is parsed. Generally there are two different ways. The old way is used in SPICE3 simulators and the new way is used in simulators based on XSPICE. Many people will find the old way less intuitive than the new one. We incorporated a mechanism in SPICE that enables you to switch between both types of subcircuit expansion.
What is subcircuit expansion? Before SPICE actually parses the circuit, it makes two passes through the netlist. During the first pass subcircuit definitions are collected. During second pass SPICE actually replaces each subcircuit reference ('x' element) with the actual subcircuit. This is not as trivial as it may seem. Generally two things need to be done:

Replace subcircuit nodes that represent its interface with the nodes specified in the subcircuit reference
Rename all internal subcircuit nodes, devices and models so name conflicts can't occur. Subsequently all references to these nodes, devices and models inside the subcircuit must also be renamed

The Old Way (SPICE3)

Let's explain this using an example circuit:

  v1 int1 0 1
  rin int1 1 50
  xsub1 1 2 100 attenuator
  xsub2 2 3 100 attenuator
  xsub3 3 4 bigatten
  rx1 100 0 1m
  rout 4 0 50

This netlist expands to:

   v1 int1 0 1
   rin int1 1 50

This is the expansion of subcircuit instance xsub1 (attenuator):

   r:sub1:1 1 sub1:int 16.67 sub1:rmod1 
   r:sub1:2 sub1:int 2 16.67 sub1:rmod1 
   r:sub1:3 sub1:int 100 66.67 sub1:rmod1 
   .model sub1:rmod1 r rc1=0.001 tc2=0.0001

This is the expansion of subcircuit instance xsub2 (attenuator):

   r:sub2:1 2 sub2:int 16.67 sub2:rmod1 
   r:sub2:2 sub2:int 3 16.67 sub2:rmod1 
   r:sub2:3 sub2:int 100 66.67 sub2:rmod1 
   .model sub2:rmod1 r tc1=0.001 tc2=0.0001

And now the expansion of subcircuit instance xsub3 (bigatten):
First the expansion of nested subcircuit xnested1 in xsub3 (attenuator):

   r:sub3:nested1:1 3 sub3:nested1:int 16.67 sub3:nested1:rmod1 
   r:sub3:nested1:2 sub3:nested1:int sub3:int 16.67 sub3:nested1:rmod1 
   r:sub3:nested1:3 sub3:nested1:int 0 66.67 sub3:nested1:rmod1 
   .model sub3:nested1:rmod1 r tc1=0.001 tc2=0.0001

And finally the expansion of nested subcircuit xnested2 in xsub3 (attenuator):

   r:sub3:nested2:1 sub3:int sub3:nested2:int 16.67 sub3:nested2:rmod1 
   r:sub3:nested2:2 sub3:nested2:int 4 16.67 sub3:nested2:rmod1 
   r:sub3:nested2:3 sub3:nested2:int 0 66.67 sub3:nested2:rmod1 
   .model sub3:nested2:rmod1 r tc1=0.001 tc2=0.0001

And finally the last two resistances from the original netlist.

   rx1 100 0 1m
   rout 4 0 50

Full instance name consists of a device letter and instance name. An example is rin10: r is the device letter telling the parser that it is dealing with a resistor and in10 is the instance name if this resistor.
Another example is xinner1: x is the device letter that tells the parser it is dealing with a subcircuit and inner1 is the instance name of this subcircuit.

Expansion rules are:
For node names:

  top_subckt_instance_name:subckt_instance_name1:subckt_instance_name2:...:node_name

Example:

   sub3:nested1:int

This means: node int inside subcircuit instance xnested1 that resides inside subcircuit instance xsub3.

For instance names:

  reference_designator:top_subckt_instance_name:subckt_instance_name1:
      subckt_instance_name2:...:device_instance_name

Example:

   r:sub3:nested1:1

This means: resistor instance r1 (instance name 1) inside subcircuit instance xnested1 that resides inside subcircuit instance xsub3.

For model names:

  top_subckt_instance_name:subckt_instance_name1:subckt_instance_name2:...:model_name

Example:

   sub3:nested2:rmod1

This means: model named rmod1 inside subcircuit instance xnested2 that resides inside subcircuit instance xsub3.

Let's say you want to plot the voltage of internal subcircuit node int that resides inside subcircuit instance xnested1 that resides inside subcircuit instance xsub3. Simply type:

  plot v(sub3:nested1:int)

To alter device instance parameter resistance to 20 for resistor r3 inside subcircuit instance xnested1 that resides inside subcircuit instance xsub3 type:

  alter r:sub3:nested1:3 resistance=20

To alter a model parameter tc1 to 0.002 for model rmod1 inside subcircuit instance xnested1 that resides inside subcircuit instance xsub3 type:

  alter #sub3:nested1:rmod1 tc1=0.002

The New Way (XSPICE) - (default)

The netlist from previous example expands to:

   v1 int1 0 1
   rin int1 1 50

This is the expansion of subcircuit instance xsub1 (attenuator):

   r1:xsub1 1 int:xsub1 16.67 rmod1:xsub1 
   r2:xsub1 int:xsub1 2 16.67 rmod1:xsub1 
   r3:xsub1 int:xsub1 100 66.67 rmod1:xsub1 
   .model rmod1:xsub1 r tc1=0.001 tc2=0.0001

This is the expansion of subcircuit instance xsub2 (attenuator):

   r1:xsub2 2 int:xsub2 16.67 rmod1:xsub2 
   r2:xsub2 int:xsub2 3 16.67 rmod1:xsub2 
   r3:xsub2 int:xsub2 100 66.67 rmod1:xsub2 
   .model rmod1:xsub2 r tc1=0.001 tc2=0.0001

And now the expansion of subcircuit instance xsub3 (bigatten):
First the expansion of nested subcircuit xnested1 in xsub3 (attenuator):

   r1:xnested1:xsub3 3 int:xnested1:xsub3 16.67 rmod1:xnested1:xsub3 
   r2:xnested1:xsub3 int:xnested1:xsub3 int:xsub3 16.67 rmod1:xnested1:xsub3 
   r3:xnested1:xsub3 int:xnested1:xsub3 0 66.67 rmod1:xnested1:xsub3 
   .model rmod1:xnested1:xsub3 r tc1=0.001 tc2=0.0001

And finally the expansion of nested subcircuit xnested2 in xsub3 (attenuator):

   r1:xnested2:xsub3 int:xsub3 int:xnested2:xsub3 16.67 rmod1:xnested2:xsub3 
   r2:xnested2:xsub3 int:xnested2:xsub3 4 16.67 rmod1:xnested2:xsub3 
   r3:xnested2:xsub3 int:xnested2:xsub3 0 66.67 rmod1:xnested2:xsub3 
   .model rmod1:xnested2:xsub3 r tc1=0.001 tc2=0.0001

And finally the last two resistances from the original netlist.

   rx1 100 0 1m
   rout 4 0 50

Expansion rules are:
For node names:

  node_name:lowest_level_full_subcircuit_instance_name:....

Example:

   int:xnested1:xsub3

This means: node int inside subcircuit instance xnested1 that resides inside subcircuit instance xsub3.

For instance names:

  full_device_instance_name:lowest_level_full_subcircuit_instance_name:....

Example:

   r1:xnested1:xsub3

This means: resistor instance r1 (instance name 1) inside subcircuit instance xnested1 that resides inside subcircuit instance xsub3.

For model names:

  model_name:lowest_level_full_subcircuit_instance_name:....

Example:

   rmod1:xnested2:xsub3

This means: model named rmod1 inside subcircuit instance xnested2 that resides inside subcircuit instance xsub3.

To plot the voltage of internal subcircuit node int that resides inside subcircuit instance xnested1 that resides inside subcircuit instance xsub3.

  plot v(int:xnested1:xsub3)

To alter the resistance instance parameter to 20 for resistor r3 inside subcircuit instance xnested1 that resides inside subcircuit instance xsub3 type:

  alter r3:xnested1:xsub3 resistance=20

To alter the tc1 model parameter to 0.002 for model rmod1 inside subcircuit instance xnested1 that resides inside subcircuit instance xsub3 type:

  alter #rmod1:xnested1:xsub3 tc1=0.002

previous | back | home | next