Properties & Restrictions Reference

Properties are the user-definable parameters of objects such as PCells and Views. In Python, there is no type checking on variables, which means that a user could accidentally assign non-nonsensical values to parameters. For instance, a property width, designating the width of a certain feature, could be assigned by the user the value "helloworld" without any problem.

In an environment for designing complex ICs, checking of types and values is necessary to avoid errors. Therefore, Ipkiss has a Property system, which allows for strong type checking and imposing Restrictions on variables. For instance, IntProperty defines a user settable parameter which has to be an integer number, and RestrictPositive restricts a value to be positive.

Basic Properties

The following properties are the most basic properties which IPKISS offers. Most properties are just more specific derivations of these properties, which means that their behavior will be very similar. In a lot of cases you will not need these basic properties.

i3.DefinitionProperty
The most widely used Property, in most use cases DefinitionProperty, or one of its derived properties, is the best choice for specifying your parameters. Only in more advanced cases you need to resort to the special properties that are listed below. Any DefinitionProperty can have a restriction and a pre-processing filter.
i3.FunctionProperty
This Property allows you to specify a function/method that will be called upon setting or getting a value. This behavior makes it very similar to Python’s property function, but with the additional advantage that type restriction and preprocessing can be added.
i3.FunctionNameProperty
Very similar to FunctionProperty but instead of assigning a function, the names of the get/set methods are specified. These methods can be overloaded in subclasses, enhancing the behavior of the property. Because of this additional indirection, FunctionNameProperty is slower than FunctionProperty.
DefinitionProperty DefinitionProperty is one of the most frequently used property types.
FunctionProperty property which calls a get and set method to set the variables
FunctionNameProperty property which calls a get and set method to set the variables.

Properties Derived From DefinitionProperty

All these properties are special cases of i3.DefinitionProperty

Numbers

Properties to store a variety of numbers.

NumberProperty DefinitionProperty restricted to be a floating point number (python float)
PositiveNumberProperty DefinitionProperty restricted to be a positive (>0) int or float
NonNegativeNumberProperty DefinitionProperty restricted to be a positive or zero-valued (>=0) int or float
ComplexNumberProperty DefinitionProperty restricted to be a complex number (python complex)
FloatProperty DefinitionProperty restricted to be a floating point number (python float)
IntProperty DefinitionProperty restricted to be an integer (python int)
LongIntProperty DefinitionProperty restricted to be an long integer (python long)
NonNegativeIntProperty DefinitionProperty restricted to be a positive or zero-valued (>=0) int
FractionProperty Property restricted to be a number within [0,1]
ComplexFractionProperty DefinitionProperty restricted to be a fraction, possibly complex, with abs(value)<=1
AngleProperty DefinitionProperty restricted to be a floating point number (python float)
NormalizedAngleProperty Property restructed to be a number within ]-180.0, 180.0]

Properties handling IPKISS PCells and Views

PCellProperty Property for assigning a PCell Accepts both a PCell and a View, if a view is assigned the corresponding cell is retrieved and assigned to the property
ChildCellProperty Property for assigning a Child PCell
ChildCellListProperty Property for assigning a list of PCells as child cells.
ViewProperty Property for assigning a View
ViewInSameCellProperty A property containing a View within the same cell.
TraceTemplateProperty Property that accepts a Trace Template PCell object
WaveguideTemplateProperty Property that accepts a WaveguideTraceTemplate PCell object.
WaveguideTemplateListProperty Property that accepts a List of WaveguideTraceTemplate PCell objects
ElectricalWireTemplateProperty

Layout Properties

OpticalPortProperty Property type for storing an OpticalPort
ElectricalPortProperty Property type for storing an ElectricalPort
TransformationProperty
ShapeProperty Property for assigning a Shape Accepts a Shape, or an iterable that can be converted to a shape (list of tuples, numpy array, …)
Coord2Property Coord2 property descriptor for a class
Coord3Property Coord3 property descriptor for a class
SizeInfoProperty SizeInfo property descriptor for a class
Size2Property Coord2 based size descriptor for a class (non-negative values in both dimensions)
Size3Property Coord3 based size descriptor for a class (non-negative values in both dimensions)
VectorProperty property restricted to a vector
ProcessProperty Property accepting a process layer
PurposeProperty Property accepting a PatternPurpose
LayerProperty
LayoutViewProperty Property for assigning a View When assigning a PCell instead of a LayoutView, the default layout of that pcell (with name ‘layout’) will be assigned.

Strings & Datastructures

Sometimes you might want to specify a property that contains a more complex datastructure. For the most common data structures we provide Properties that allow to restrict the value to a given datastructure.

StringProperty DefinitionProperty restricted to be a string (python str)
Tuple2Property Property restricted to be a python tuple object with a length of 2
ListProperty Property restricted to be a python list object
TypedListProperty DefinitionProperty for storing a typed list.
DictProperty Property restricted to be a dictionary (python dict)
NamedTypedDictProperty Property restricted to be a NamedTypedDict
OrderedNamedTypedDictProperty Property restricted to be a OrderedNamedTypedDict
CallableProperty DefinitionProperty restricted to be a callable like for example a function
BoolProperty DefinitionProperty restricted to be a boolean.

Numpy Array Properties

Almost all scientific python applications use numpy to store arrays and matrices and do operations on them in an efficient way.

NumpyArrayProperty Property restricted to be a numpy array (numpy.ndarray).
NumpyMasked2DArrayProperty Property restricted to be a numpy masked array with 2 dimensions
NumpyMasked3DArrayProperty Property restricted to be a numpy masked array with 3 dimensions

Special Properties

We provide a few properties that cover a specific use case, most users will not want to use these, but we add them for completeness.

TimeProperty Property restricted to be number representing a time
FilenameProperty DefinitionProperty restricted to be a filename string
IdStringProperty DefinitionProperty restricted to be a string without special characters
FontProperty Property that accepts a font
SetFunctionProperty A special version of DefinitionProperty which calls a set method to set the variables, but it is stored in a known attribute, so a get method need not be specified.

LockedProperty

LockedProperty the use of this class disables a property in a parent class

This special property is only used when a a new type is being created through subclassing. When the parent class has a property that should become read-only in the new subclass, the property can be overridden with LockedProperty. That way, in the new class the property becomes read-only, while maintaining all the restrictions and preprocessing of the original property.

Consider the following class

class FruitOrder(StrongPropertyInitializer):
    fruit_type = StringProperty(restriction=RestrictValueList(allowed_values=["apple", "pear", "cherry"]))
    quantity = PositiveNumberProperty()

    def __str__(self):
        return "Order for {0} pieces of {1}".format(self.quantity, self.fruit_type)

We can now subclass for a particular type of fruit, and lock the property fruit_type:

class CherryOrder(FruitOrder):
    fruit_type = LockedProperty()

    def _default_frout_type(self):
    return "cherry"

The default is set by adding the method _default_fruit_type

More information on this behavior can be found in How to create new Types with Properties.


Restrictions

Restrictions are used in combination with i3.DefinitionProperty to restrict the kind of values you can assign to a property. By default a DefinitionProperty doesn’t have any restrictions so you can assign all possible values to it. Once you provide a restriction, the DefinitionProperty will check upon assignment that the value you’re assigning is validated by the restriction. If it’s not valid, an Error will be raised.

You can apply boolean operations to Restrictions, this is best explained by a simple example:

from ipkiss3.all import i3
rest1 = i3.RestrictRange(lower=1, upper=10)
rest2 = i3.RestrictRange(lower=-5, upper=5)

rest1_not = not rest1 # value is valid if not within [1, 10[
rest1_and_rest2 = rest1 and rest2 # value is valid if within [1, 5[
rest1_or_rest2 = rest1 or rest2 # value is valid if within [-5, 10[

Often there exists a property that already specifies the restriction for you. This is the case for the properties we listed above. Only in more advanced use cases you will have to specify the restriction yourself.

Below you can find all the standard restrictions IPKISS provides.

RestrictRange restrict the argument to a given range
RestrictType restrict the type or types the argument can have.
RestrictClass restrict the base class of an argument which is a class.
RestrictLen restrict the length of a list, tuple, shape, …
RestrictLenRange restrict the length of a list, tuple, shape, …
RestrictFunction restricts the value to those that return ‘True’ when passed to a given function
RestrictIterable subject all individual elements of an iterable to a certain restriction
RestrictList subject all individual elements of an iterable to a certain restriction
RestrictTypeList restrict the argument to a list which contains a given type or types.
RestrictValueList restrict the argument to a list of allowed values
RestrictValueEnum restrict the argument to the members of an Enum.
RestrictContains restrict the argument to an object with contains at least one of a set of allowed values
RestrictDictValue subject all values in a dictionary to a certain restriction
RestrictDictValueType restrict the argument to a dict which contains items of a given type or types.

Property Preprocessors

Preprocessors can convert a value before it’s being assigned to a property, this can be useful when you’re assigning an invalid value that can easily be converted to a valid value

ProcessorTypeCast restrict the type or types the argument can have, and tries a typecast where possible
ProcessorInt This preprocessor makes sure that the value stored is a python int, but only if the input is considered a valid int (bool, int, numpy.int_, …).
ProcessorFloat This preprocessor makes sure that the value stored is a python float, but only if the input is considered a valid float (float, int, bool, numpy.int_, numpy.float_, …).
ProcessorString Processor that typecasts to a string.
ProcessorRange brings a number to within a certain range
ProcessorIntRound rounds a number to the nearest integer

Property Validation Errors

When you throw a validation error it is best to use a custom execption that is made for this purpose and ensures a proper handling of the error.

PropertyValidationError Exception used when validating properties, to be thrown from validate_properties()