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.

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.
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.
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.

Properties Derived From DefinitionProperty

All these properties are special cases of DefinitionProperty

Numbers

Properties to store a variety of numbers.

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

Properties handling IPKISS PCells and Views

ipkiss3.all.PCellProperty([doc, restriction]) 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
ipkiss3.all.ChildCellProperty([doc, restriction]) Property for assigning a Child PCell
ipkiss3.all.ChildCellListProperty([restriction]) Property for assigning a list of PCells as child cells.
ipkiss3.all.ViewProperty([restriction]) Property for assigning a View
ipkiss3.all.ViewInSameCellProperty(view_type) A property containing a View within the same cell.
ipkiss3.all.TraceTemplateProperty([restriction]) Property that accepts a Trace Template PCell object
ipkiss3.all.WaveguideTemplateProperty([doc, …]) Property that accepts a WaveguideTraceTemplate PCell object.
ipkiss3.all.WaveguideTemplateListProperty([…]) Property that accepts a List of WaveguideTraceTemplate PCell objects
ipkiss3.all.ElectricalWireTemplateProperty([…])

Layout Properties

ipkiss3.all.OpticalPortProperty([…]) Property type for storing an OpticalPort
ipkiss3.all.ElectricalPortProperty([restriction]) Property type for storing an ElectricalPort
ipkiss3.all.TransformationProperty([…])
ipkiss3.all.ShapeProperty([doc, …]) Property for assigning a Shape Accepts a Shape, or an iterable that can be converted to a shape (list of tuples, numpy array, …)
ipkiss3.all.Coord2Property([…]) Coord2 property descriptor for a class
ipkiss3.all.Coord3Property([…]) Coord3 property descriptor for a class
ipkiss3.all.SizeInfoProperty([…]) SizeInfo property descriptor for a class
ipkiss3.all.Size2Property([…]) Coord2 based size descriptor for a class (non-negative values in both dimensions)
ipkiss3.all.Size3Property([…]) Coord3 based size descriptor for a class (non-negative values in both dimensions)
ipkiss3.all.VectorProperty([…]) property restricted to a vector
ipkiss3.all.ProcessProperty([…]) Property accepting a process layer
ipkiss3.all.PurposeProperty([…]) Property accepting a PatternPurpose
ipkiss3.all.LayerProperty([…])
ipkiss3.all.LayoutViewProperty([restriction]) 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.

ipkiss3.all.StringProperty([…]) DefinitionProperty restricted to be a string (python str)
ipkiss3.all.Tuple2Property([…]) Property restricted to be a python tuple object with a length of 2
ipkiss3.all.ListProperty([…]) Property restricted to be a python list object
ipkiss3.all.TypedListProperty([…]) DefinitionProperty for storing a typed list.
ipkiss3.all.DictProperty([…]) Property restricted to be a dictionary (python dict)
ipkiss3.all.NamedTypedDictProperty([restriction]) Property restricted to be a NamedTypedDict
ipkiss3.all.OrderedNamedTypedDictProperty([…]) Property restricted to be a OrderedNamedTypedDict
ipkiss3.all.CallableProperty([…]) DefinitionProperty restricted to be a callable like for example a function
ipkiss3.all.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.

ipkiss3.all.NumpyArrayProperty([…]) Property restricted to be a numpy array (numpy.ndarray)
ipkiss3.all.NumpyMasked2DArrayProperty([…]) Property restricted to be a numpy masked array with 2 dimensions
ipkiss3.all.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.

ipkiss3.all.TimeProperty([…]) Property restricted to be number representing a time
ipkiss3.all.FilenameProperty([…]) DefinitionProperty restricted to be a filename string
ipkiss3.all.IdStringProperty([…]) DefinitionProperty restricted to be a string without special characters
ipkiss3.all.FontProperty([…]) Property that accepts a font
ipkiss3.all.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

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 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.

ipkiss3.all.RestrictRange([lower, upper, …]) restrict the argument to a given range
ipkiss3.all.RestrictType(allowed_types, **kwargs) restrict the type or types the argument can have.
ipkiss3.all.RestrictClass(allowed_types, …) restrict the base class of an argument which is a class.
ipkiss3.all.RestrictLen(length, **kwargs) restrict the length of a list, tuple, shape, …
ipkiss3.all.RestrictLenRange([min_length, …]) restrict the length of a list, tuple, shape, …
ipkiss3.all.RestrictFunction(…) restricts the value to those that return ‘True’ when passed to a given function
ipkiss3.all.RestrictIterable(restriction, …) subject all individual elements of an iterable to a certain restriction
ipkiss3.all.RestrictList(restriction, **kwargs) subject all individual elements of an iterable to a certain restriction
ipkiss3.all.RestrictTypeList(allowed_types) restrict the argument to a list which contains a given type or types.
ipkiss3.all.RestrictValueList(allowed_values) restrict the argument to a list of allowed values
ipkiss3.all.RestrictValueEnum(allowed_values) restrict the argument to the members of an Enum.
ipkiss3.all.RestrictContains(allowed_values) restrict the argument to an object with contains at least one of a set of allowed values
ipkiss3.all.RestrictDictValue(restriction) subject all values in a dictionary to a certain restriction
ipkiss3.all.RestrictDictValueType(allowed_types) 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

ipcore.properties.processors.ProcessorTypeCast(…) restrict the type or types the argument can have, and tries a typecast where possible
ipcore.properties.processors.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_, …).
ipcore.properties.processors.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_, …).
ipcore.properties.processors.ProcessorString() Processor that typecasts to a string.
ipcore.properties.processors.ProcessorRange([…]) brings a number to within a certain range
ipcore.properties.processors.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.

ipkiss3.all.PropertyValidationError([…]) Exception used when validating properties, to be thrown from validate_properties()