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()