SKiDL Packages: should they stay or should they go?

[devbisme]

While I was working on the circuitsascode repository, I discovered some problems with SKiDL Interfaces (finding these errors is one of the reasons I created circuitsascode).

While fixing the Interface problem, I broke the @package decorator (including the underlying Package and ProtoNet objects). I've spent the past few days trying to patch it together so it will work. All I've succeeded in doing is convince myself that fixing the problems with @package will take a considerable amount of re-thinking and work. And this wouldn't benefit me since I can replace everything that Packages do by using Interfaces instead (see discussion below).

So the only reason to keep Packages is if others are using them in their code. If enough of you are, I'll try to save this feature. Otherwise, I'll remove Packages and ProtoNets and simplify the SKiDL code. I'll leave this question open until next weekend in order for people to have a chance to reply.

Packages versus Interfaces

Here is a three-terminal voltage regulator and a couple of filter capacitors described using @package:

@package
def vreg_module(vi, vo, gnd):
    vrg = Part("
            lib="Regulator_Linear",
            name="AZ1117",
            footprint="Package_TO_SOT_SMD:SOT-223-3_TabPin2"
    )
    ci, co = 2 * Part(
        lib = 'Device',
        name = 'C',
        value="10uF",
        dest=TEMPLATE,
        footprint="Capacitor_SMD:C_0805_2012Metric"
    )
    vrg['VI VO GND'] += vi, vo, gnd
    vi & ci & gnd
    vo & co  & gnd

Here is the same regulator circuit using Interfaces:

@subcircuit
def vreg_module():

    # Instead of parameters, explicitly define three internal nets.
    vin, vout, gnd = 3 * Net()

    vrg = Part("
            lib="Regulator_Linear",
            name="AZ1117",
            footprint="Package_TO_SOT_SMD:SOT-223-3_TabPin2"
    )
    ci, co = 2 * Part(
        lib = 'Device',
        name = 'C',
        value="10uF",
        dest=TEMPLATE,
        footprint="Capacitor_SMD:C_0805_2012Metric"
    )
    vrg['VI VO GND'] += vin, vout, gnd
    vin & ci & gnd
    vout & co  & gnd

    # Explicitly return an interface that connects to the three internal nets.
    return Interface(vi=vin, vo=vout, gnd=gnd)

The main differences in the two approaches is that the Interfacemethod requires the input nets/buses to be explicitly defined and an Interface object has to be explicitly returned, whereas the @package method tries to extract this information implicitly (which is what causes some of the problems).

Regardless of whether the circuit module is defined using Packages or Interfaces, it is used the same way:

regulator = vreg()  # Instantiate the voltage regulator circuit.

# Connect the regulator circuit I/O to some nets in the upper level of circuitry.
regulator.vi += unregulated_voltage
regulator.vo += regulated_voltage
regulator.gnd += ground_net

[devbisme]

I managed to save the @package feature in the latest release of SKiDL. Based on the response, I'll assume that nobody cares if Packages are removed at some future date.

[shanemmattner]

Interface logic seems like something you could hide from the user in order to make SKiDL code read more like regular python functions. Could you instead check that the passed objects are nets/buses for each subcircuit and do this in the background for the user?

@subcircuit
def circuit_a(vi, vo, gnd):
  # this section would be part of the subcircuit class and happen in the background, not explicitly declared in each function
   for i in locals():
      if not isinstance(x, net):
          if not isinstance(x, bus):
              raise TypeError('x must be a net or bus')

[devbisme]

With modules defined using the interface method, there aren't any passed-in circuit objects. You would instantiate the voltage regulator circuit like this:

vreg1 = vreg_module()

Then you would connect it as if it were just some Part-like object:

vreg1.gnd += Net("GND")
vreg1["vin"] += pwr_jack[1]
...

So you can't parse the I/O when the module is called (i.e., instantiated) because there isn't any (in this case). And you can't do it when the @subcircuit decorator processes the vreg_module() function because, again, no I/O is specified. I suppose you could do something like list the I/O as parameters with default values instead of declaring them inside the function like this:

@subcircuit
def vreg_module(vin=Net(), vout=Net(), gnd=Net()):

    vrg = Part("
            lib="Regulator_Linear",
            name="AZ1117",
            footprint="Package_TO_SOT_SMD:SOT-223-3_TabPin2"
    )
...

Then two more problems arise:

1. If you make connections to any of the I/O circuit objects listed as defaults, then this will affect the nets of each instantiation of vreg_module and all the instantiated modules will be interconnected. (Default arguments are created one time when a Python function is defined, not each time the function is called, so they persist across all calls.)
2. The I/O gets fixed as a certain type and size. But this prevents you from creating a generic module that handles buses of different sizes like my VGA interface?

Trying to infer the interface from indirect information is tricky and locks you into a rigid structure as to what can enter and exit the module. IMO, explicitly returning an interface provides is simpler, more transparent about what is happening, and more flexible.