Place

class ipkiss3.all.Place

Specifies that an instance (inst1), its port (insts1:out), corner of the bounding box (insts1@NE), or geometric center (insts1@C), should be placed at a given position with a given angle, or relative to another instance (inst2), its port (insts2:out), corner of the bounding box (insts2@NW), or geometric center (insts2@C) with a given offset.

If relative_to is defined, the position will be relative to that instance/port/bounding_box/center. When relative_to is undefined (i.e. relative_to = None), then the position is defined globally. The angle will always be relative to the global axis. relative_to can be a tuple of two instance/port identifiers in which case the relative X position is relative to the first element and the Y position relative to the second.

If angle is not specified (i.e. angle = None), then the instance will keep its original transformations.

If angle is specified, the original transformations will be overridden and the instance will be rotated.

If you specify an angle and choose to place a port that has an angle, then the instance is rotated such that the port’s angle will equal this desired angle.

If you place a port with an undefined port angle (i.e. angle = None), and you specify an angle in Place, then the port’s angle will stay ‘None’ but its instance will be rotated.

For examples on different usages see

Placement and routing specifications example.

Parameters:

pos_selectorstr

A string referring to the instance (e.g. inst1), to the port of an instance (e.g. inst1:out), to the corner of the bounding box (e.g. inst1@NE), or to it’s geometric center (e.g. inst1@C).

positiontuple of float

A tuple with an x and y value for the absolute position or relative offset (depending if relative_to is set).

anglefloat, default=None

A floating point value for the angle.

relative_tostr or tuple of str, default=None

When this argument is provided, the specified position will be relative to this entity or entities of the tuple. See Symbols for more information.

Examples

Absolute placement of instances or ports can be defined like this:

>>> # Place 'inst' at (0, 0), original transformations are kept
>>> i3.Place('inst', (0, 0))
>>>
>>> # Place 'inst' at (0, 0) with a rotation of 90 degrees, original transformations are discarded
>>> i3.Place('inst', (0, 0), angle=90)
>>>
>>> # Place port 'out' of 'inst' at (0, 0) with the angle of the port of the instance
>>> i3.Place('inst:out', (0, 0))
>>>
>>> # Place port 'out' of 'inst' (original port angle = 180) at (0, 0), with port angle 90 degrees,
>>> # original transformations are discarded
>>> i3.Place('inst:out', (0, 0), angle=90)
>>>
>>> # Place port 'out' of 'inst' (original port angle is None) at (0, 0), with a rotation of 90 degrees,
>>> # original transformations are discarded
>>> i3.Place('inst:out', (0, 0), angle=90)
>>>
>>> # Place the upper right corner of 'inst' at (0, 0)
>>> i3.Place('inst@NE', (0, 0))

They are used in a circuit like this:

import si_fab.all as pdk
import ipkiss3.all as i3

x_coord = 20
y_coord = 40

# the output port of the grating coupler will be placed at (x_coord, y_coord)
place_spec = i3.Place("gc:out", (x_coord, y_coord))

gc = pdk.FC_TE_1550()
circuit = i3.Circuit(insts={"gc": gc}, specs=[place_spec])
circuit.Layout().visualize(annotate=True)

Relative placement of instances or ports can be defined like this:

>>> # Place 'inst1' relative to 'inst2' with an offset (10, 15). Original transformations are kept.
>>> i3.Place('inst1', (10, 15), relative_to='inst2')
>>>
>>> # Place 'inst1' relative to 'inst2' with an offset (10, 15). Rotation of 'inst1' is 45.
>>> i3.Place('inst1', (10, 15), angle=45, relative_to='inst2')
>>>
>>> # Place port 'out' of 'inst1' at a 180-degree angle
>>> # relative to port 'in' from 'inst2' with an offset (10, 0).
>>> i3.Place('inst1:out', (10, 0), angle=180, relative_to='inst2:in')
>>>
>>> # Place port 'out' of 'inst1' relative to port 'in' from 'inst2' with an offset (-10, -10).
>>> # Original transformations are kept.
>>> i3.Place('inst1:out', (-10, -10), relative_to='inst2:in')
>>>
>>> # Place the center of 'inst' relative to the upper right corner of `inst2` with an offset (5, 10)
>>> i3.Place('inst1@C', (5, 10), relative_to='inst2@NE')
>>>
>>> # Place `inst1` at 10 relative to `inst2` on the X-axis and at -5 relative to `inst3` on the Y-axis.
>>> i3.Place('inst1', (10, -5), relative_to=('inst2', 'inst3'))
>>>
>>> # i3.Place with a tuple passed to relative_to is a shorthand notation for a i3.Place.X and i3.Place.Y on the
>>> # same instance. The previous example can also be written as
>>> i3.Place.X('inst1', 10, relative_to='inst2')
>>> i3.Place.Y('inst1', -5, relative_to='inst3')

They are used in a circuit like this:

import si_fab.all as pdk
import ipkiss3.all as i3
import matplotlib.pyplot as plt

# the second grating coupler will be shifted by (20, 40) with respect to the first one
placerelative_spec = i3.Place("gc2", (20, 40), relative_to="gc1")

gc = pdk.FC_TE_1550()
circuit = i3.Circuit(
    insts={"gc1": gc, "gc2": gc},
    specs=[i3.Place("gc1:out", (0, 0)), placerelative_spec],
)
circuit.Layout().visualize(annotate=True)

class X

A sub-specification of i3.Place that only specifies the position on the x-axis.

All other dimensions remain the same.

For examples on different usages see Placement and routing specifications example.

Parameters:

pos_selectorstr

A string referring to the instance (e.g. inst1), to the port of an instance (e.g. inst1:out), to its bounding box edge along the X axis (e.g. inst1@E), or to it’s geometric center (e.g. inst1@C).

xfloat

A float value for the absolute position or relative offset on the x-axis (depending if relative_to is set).

relative_tostr, default=None

When this argument is provided, the specification will be relative to this entity.

Examples

import si_fab.all as pdk
import ipkiss3.all as i3

# the output port of the grating coupler will be placed at 10 on the x-axis
place_spec = i3.Place.X("gc:out", 10)

gc = pdk.FC_TE_1550()
circuit = i3.Circuit(
    insts={"gc": gc},
    specs=[place_spec],
)
circuit.Layout().visualize(annotate=True)

class Y

A sub-specification of i3.Place that only specifies the position on the y-axis.

All other dimensions remain the same.

For examples on different usages see Placement and routing specifications example.

Parameters:

pos_selectorstr

A string referring to the instance (e.g. inst1), to the port of an instance (e.g. inst1:out), to its bounding box edge along the Y axis (e.g. inst1@N), or to it’s geometric center (e.g. inst1@C).

yfloat

A float value for the absolute position or relative offset on the y-axis (depending if relative_to is set).

relative_tostr, default=None

When this argument is provided, the specification will be relative to this entity.

Examples

import si_fab.all as pdk
import ipkiss3.all as i3

# the output port of the grating coupler will be placed at 10 on y-axis
place_spec = i3.Place.Y("gc:out", 10)

gc = pdk.FC_TE_1550()
circuit = i3.Circuit(
    insts={"gc": gc},
    specs=[place_spec],
)
circuit.Layout().visualize(annotate=True)

class Angle

A sub-specification of i3.Place that only specifies angle.

All other dimensions remain the same.

Parameters:

pos_selectorstr

A string referring to the instance (e.g. inst) or the port of an instance (e.g. inst:out).

anglefloat

A float value for the angle of the instance or port.

Examples

import si_fab.all as pdk
import ipkiss3.all as i3

# the output port of the grating coupler will be rotated to 45 degrees
place_spec = i3.Place.Angle("gc:out", 45)

gc = pdk.FC_TE_1550()
circuit = i3.Circuit(
    insts={"gc": gc},
    specs=[place_spec],
)
circuit.Layout().visualize(annotate=True)