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.ListDefinitionProperty: This Property allows to specify a parameter which is a list consisting of allowed types of objects to be specified.
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.
`ListDefinitionProperty`
`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`
`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), which contains only ASCII characters
`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)
`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.

The data structures defined by IPKISS are:

`TypedList`	A list that ensures that all elements in it are of a given type.
`OrderedTypedDict`	Base class for (ordered) dicts with items of a given type.
`OrderedNamedTypedDict`	Dict with named items of a given type.

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.
`AliasProperty`	Alias for another property (get + set).

LockedProperty 

LockedProperty

Generic read-only property

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
`RestrictTuple`	Restrict the value of the property to a tuple, with values of specified allowed types.
`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 exception 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()