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