+
+
+ + +
+
+ +
+ +
+
+ +
+
+
+

Good Things Come In Packages!

+

+ by Dave Vandenbout — + + + +

+ + + + +
+
+
+
+ + +
+ +

Up to now, SKiDL supported hierarchy by applying the @subcircuit decorator to a Python function:

+ +
@subcircuit
+def analog_average(in1, in2, avg):
+    """Output the average of the two inputs."""
+    
+    # Create two 1K resistors.
+    r1, r2 = 2 * Part('Device', 'R', value='1K', dest=TEMPLATE)
+   
+    # Each input connects thru a resistor to the avg output.
+    r1[1,2] += in1, avg
+    r2[1,2] += in2, avg
+
+ +

Then this subcircuit is instantiated by calling the function with nets +passed as arguments:

+ +
in1, in2, in3, in4, out1, out2 = Net()*6  # Make some I/O nets.
+
+analog_average(in1, in2, out1)  # One instantiation of the averager.
+
+... Some more code ...
+
+analog_average(in3, in4, out2)  # A second instantiation.
+
+ +

It was pointed out that this method +of instantiating subcircuits is quite different from what is used for parts. +Unlike the connections to a subcircuit that are all made at a single place when the +function is called, the connections to a part can be placed +at various, non-contiguous locations in the code:

+ +
q_npn = Part("Device", "Q_NPN_BCE")  # Instantiate a transistor.
+
+...
+
+q_npn['E'] += Net('GND')  # Connect the emitter to ground.
+
+...
+
+q_npn['B'] += in1  # Connect an input to the base.
+
+...
+
+q_npn['C'] += out1  # Connect the output to the collector.
+
+ +

Another issue is that you can pass a part instance as an argument to a subcircuit that +connects it to the internal circuitry. +But you can’t do the same thing with a subcircuit function without making changes to the +code because of the syntactic differences in how connections are made:

+ +
@subcircuit
+def analog_average(in1, in2, avg, r):
+    """Output the average of the two inputs."""
+
+    r1, r2 = r(num_copies=2)  # Create two copies of the resistor part.
+    r1[1,2] += in1, avg
+    r2[1,2] += in2, avg
+
+    # If r was a subcircuit function, this would have to be written as:
+    # r(in1, avg)
+    # r(in2, avg)
+
+ +

To make subcircuits act more like parts, the @package decorator has been introduced. +Just replace the @subcircuit decorator while keeping everything else the same:

+ +
@package
+def analog_average(in1, in2, avg):
+    r1, r2 = 2 * Part('Device', 'R', value='1K', dest=TEMPLATE)
+    r1[1,2] += in1, avg
+    r2[1,2] += in2, avg
+
+ +

Instantiating the subcircuit now occurs in two phases. +First, create instances of the subcircuit wherever they are needed:

+ +
avg1 = analog_average()
+
+...
+
+avg2 = analog_average()
+
+ +

In the second phase, make connections to these subcircuits as if they were parts +with the names of the function parameters serving as pin names:

+ +
in1, in2, in3, in4, out1, out2 = Net()*6
+
+# Make connections. You can use either [] or . to reference the I/O.
+avg1['in1'] += in1
+avg1.in2    += in2
+avg1['avg'] += out1
+
+...
+
+avg2['in1'] += in3
+avg2['in2'] += in4
+avg2.avg    += out2
+
+ +

In addition to nets, pins, and buses, you can pass any other type of +parameter to subcircuits. +For example, analog_average could take a float as a ratio parameter to +set the amount each input contributes to the output:

+ +
@package
+def analog_average(in1, in2, avg, ratio):
+    r = Part('Device', 'R', dest=TEMPLATE)
+    r1 = r(value=2000 * ratio)
+    r2 = r(value=2000 * (1-ratio))
+
+    r1[1,2] += in1, avg
+    r2[1,2] += in2, avg
+
+ +

Then the subcircuit can either be instantiated with a given ratio:

+ +
avg1 = analog_average(ratio=0.25)
+avg1.in1 += in1
+avg1.in2 += in2
+avg1.avg += out1
+
+

or you can set the ratio outside the function call:

+
avg2 = analog_average()
+avg2.ratio = 0.25  # Use a normal assignment (=) since this is not a circuit connection.
+avg2.in1 += in3
+avg2.in2 += in4
+avg2.avg += out2
+
+ +

A subcircuit function instantiates its circuitry when it is called. +But this doesn’t happen when using a package. +Instead, the subcircuit is placed in a list and executed after the +complete circuit is finalized +(i.e., whenever ERC() or generate_netlist() is called). +The arguments passed to the function consist of the connections +and other values that were assigned to the package parameters in the preceding code.

+ +

That’s about it for the @package decorator. +Since it’s new, it hasn’t seen a lot of use and there could be unknown bugs +lying in wait. +If you have questions or problems, please ask on the +SKiDL forum or +raise an issue.

+ +
+
+ + + +
+
+
+
+
+ + + + + +
+
+
+
+
+
+ Dave Vandenbout's photo + Author: +

Dave Vandenbout

+

devb@xess.com +

Relax, I do this stuff for a living.

+
+
+
+ +
+ +
+ + +