ordec.core.cell — Parametrizable cells and @generate

This module offers the Cell class, which acts as base class for user-defined design cells (modules) in ORDeC. Cell subclasses typically define view generator methods through @generate. Cell subclasses can be parametrized through Parameter.

Parametrizable cells

class ordec.core.cell.Cell(*args, **kwargs)

Subclass this class to define (parametric) design cells.

When a Cell subclass is instantiated multiple times with identical effective parameters, the same instance is returned. In other words, each Cell subclass in combination with a particular parameter setting acts as singleton. This magic is accomplished by the metaclass MetaCell.

classmethod params_preprocess(args, kwargs)

A subclass can override this method to modify args and kwargs at instantiation. This method is called using the original args and kwargs provided, before any processing of their values is done.

Override this to modify how args and kwargs are handled.

Example uses:

• restrict use of positional parameters,

• rename parameters (aliases).

classmethod params_rewrite(params: dict) → dict

A subclass can override this method to modify the parameter dict before per-parameter type checking.

This method is called after args and kwargs are mapped to the parameter dict and after basic per-parameter type coercion.

Example uses:

• custom type conversion of parameters,

• calculation of missing parameters based on parameters provided.

classmethod params_check(params: dict)

A subclass can override this method to implement parameter checking. This method is called after successful per-parameter type checking and should not modify the parameter dictionary. If the parameters are found to be invalid, a descriptive ParameterError should be raised.

Example uses:

• check whether transistor dimensions are within technology ranges,

• check whether values of dependent parameters are consistent.

classmethod discoverable_instances() → list[Self]

This classmethod defines which instances of a Cell subclass are discoverable for the web UI, i.e. shown to the user.

By default, only the Cell’s instance with empty parameter set is discoverable. If this instance is unavailable due to a ParameterError (e.g. mandatory parameters), no instances are discoverable. In this case, a Cell subclass could override this method and return a list of one or multiple of its instances created from valid parameters.

Cell subclasses can be parametrized by adding Parameter instances as class attributes.

class ordec.core.cell.Parameter(t: type, optional: bool = False, default=None)

Defines a Cell parameter.

Accessing the parameter from a Cell instance returns its value; accessing it from a Cell class returns the Parameter object. This behavior is achieved by Parameter acting as a Python Descriptor.

Parameters:

• t – The type that the parameter must be an instance of. Instances of the type should be immutable and hashable.

• optional – Indicate whether None is a valid parameter value.

• default – Default value of the parameter.

Example:

class SomeCell(Cell):
    param1 = Parameter(R)
    param2 = Parameter(int)
    param3 = Parameter(str)

    @generate
    def schematic(self):
        print("param1 is", self.param1)
        print("param2 is", self.param2)
        print("param3 is", self.param3)
        # ...

SomeCell('100k', 123, 'string parameter').schematic

exception ordec.core.cell.ParameterError

Exception raised during Cell instantiation upon:

• missing mandatory parameter,

• invalid type for parameter,

• too many positional arguments

• parameter set using both positional and keyword argument,

• unknown paramter name,

• parameter outside valid range,

• inconsistent combination of parameter values.

View generators

@ordec.core.cell.generate(func=None, **kwargs)

Decorator for view generator methods defined in Cell subclasses. The decorated function cannot have any parameters beyond ‘self’ (use Cell-level parameters instead).

Decorated view generator methods are visible in the web UI.

@generate returns a Python Descriptor.

Example:

class SomeCell(Cell):
    @generate
    def schematic(self):
        s = Schematic(cell=self)
        s.my_net = Net()
        # ...
        return s

To disable automatic refreshing in the web interface (e.g. for long simulations):

class SomeCell(Cell):
    @generate(auto_refresh=False)
    def schematic(self):
        # ...

@ordec.core.cell.generate_func(*args, **kwargs)

Decorator for view generator functions. Use for module-level functions outside of Cell subclasses. The decorated function cannot have any parameters.

Decorated view generator functions are visible in the web UI.

@generate_func is provided to simplify small examples. For anything complex, @generate should be prefered.

@generate_func is similar to Python’s functools.cache.

Example:

@generate
def schematic():
    s = Schematic()
    s.my_net = Net()
    # ...
    return s

@generate_func supports the same optional parameters as @generate, for example:

@generate(auto_refresh=False)
def schematic():
    s = Schematic()
    s.my_net = Net()
    # ...
    return s