References and ports#

gdsfactory defines your component once in memory and can add multiple References (Instances) to the same component.

As you build components you can include references to other components. Adding a reference is like having a pointer to a component.

The GDSII specification allows the use of references, and similarly gdsfactory uses them (with the add_ref() function). what is a reference? Simply put: A reference does not contain any geometry. It only points to an existing geometry.

Say you have a ridiculously large polygon with 100 billion vertices that you call BigPolygon. It’s huge, and you need to use it in your design 250 times. Well, a single copy of BigPolygon takes up 1MB of memory, so you don’t want to make 250 copies of it You can instead references the polygon 250 times. Each reference only uses a few bytes of memory – it only needs to know the memory address of BigPolygon, position, rotation and mirror. This way, you can keep one copy of BigPolygon and use it again and again.

You can start by making a blank Component and add a single polygon to it.

import gdsfactory as gf

# Create a blank Component
p = gf.Component("component_with_polygon")

# Add a polygon
xpts = [0, 0, 5, 6, 9, 12]
ypts = [0, 1, 1, 2, 2, 0]
p.add_polygon([xpts, ypts], layer=(2, 0))

# plot the Component with the polygon in it
p.plot()
2024-03-27 22:12:30.841 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/component_with_polygon.lyp'.
../_images/bd06862bffb996008bebb39b7b51347a48522f77d49397a6d896f82059aef938.png

Now, you want to reuse this polygon repeatedly without creating multiple copies of it.

To do so, you need to make a second blank Component, this time called c.

In this new Component you reference our Component p which contains our polygon.

c = gf.Component("Component_with_references")  # Create a new blank Component
poly_ref = c.add_ref(p)  # Reference the Component "p" that has the polygon in it
c.plot()
2024-03-27 22:12:31.045 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/Component_with_references.lyp'.
../_images/bd06862bffb996008bebb39b7b51347a48522f77d49397a6d896f82059aef938.png

you just made a copy of your polygon – but remember, you didn’t actually make a second polygon, you just made a reference (aka pointer) to the original polygon. Let’s add two more references to c:

poly_ref2 = c.add_ref(p)  # Reference the Component "p" that has the polygon in it
poly_ref3 = c.add_ref(p)  # Reference the Component "p" that has the polygon in it
c.plot()
2024-03-27 22:12:31.235 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/Component_with_references.lyp'.
../_images/bd06862bffb996008bebb39b7b51347a48522f77d49397a6d896f82059aef938.png

Now you have 3x polygons all on top of each other. Again, this would appear useless, except that you can manipulate each reference independently. Notice that when you called c.add_ref(p) above, we saved the result to a new variable each time (poly_ref, poly_ref2, and poly_ref3)? You can use those variables to reposition the references.

poly_ref2.rotate(90)  # Rotate the 2nd reference we made 90 degrees
poly_ref3.rotate(180)  # Rotate the 3rd reference we made 180 degrees
c.plot()
2024-03-27 22:12:31.419 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/Component_with_references.lyp'.
../_images/09feed37bfe651509d2ee37428f6adce61b26e7bd4e4215baf1cf860c5984d01.png

Now you’re getting somewhere! You’ve only had to make the polygon once, but you’re able to reuse it as many times as you want.

Modifying the referenced geometry#

What happens when you change the original geometry that the reference points to? In your case, your references in c all point to the Component p that with the original polygon. Let’s try adding a second polygon to p.

First you add the second polygon and make sure P looks like you expect:

# Add a 2nd polygon to "p"
xpts = [14, 14, 16, 16]
ypts = [0, 2, 2, 0]
p.add_polygon([xpts, ypts], layer=(1, 0))
p
2024-03-27 22:12:31.656 | WARNING  | gdsfactory.klive:show:49 - UserWarning: Could not connect to klive server. Is klayout open and klive plugin installed?
2024-03-27 22:12:31.679 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/component_with_polygon.lyp'.
/home/runner/work/gdsfactory/gdsfactory/gdsfactory/klive.py:49: UserWarning: Could not connect to klive server. Is klayout open and klive plugin installed?
  warnings.warn(
component_with_polygon: uid ee8cad1d, ports [], references [], 2 polygons
../_images/77d124159ca12a267b2af861cfb957d3e5543113d194fd29d64eeda762ed6933.png

That looks good. Now let’s find out what happened to c that contains the three references. Keep in mind that you have not modified c or executed any functions/operations on c – all you have done is modify p.

c.plot()
2024-03-27 22:12:31.861 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/Component_with_references.lyp'.
../_images/74845ab38addbbae7c3bdffa22a3198dc926137a33c8eb76e5b6d020fc4f49dd.png

When you modify the original geometry, all of the references automatically reflect the modifications. This is very powerful, because you can use this to make very complicated designs from relatively simple elements in a computation- and memory-efficient way.

Let’s try making references a level deeper by referencing c. Note here we use the << operator to add the references – this is just shorthand, and is exactly equivalent to using add_ref()

c2 = gf.Component("array_sample")  # Create a new blank Component
d_ref1 = c2.add_ref(c)  # Reference the Component "c" that 3 references in it
d_ref2 = c2 << c  # Use the "<<" operator to create a 2nd reference to c.plot()
d_ref3 = c2 << c  # Use the "<<" operator to create a 3rd reference to c.plot()

d_ref1.move([20, 0])
d_ref2.move([40, 0])

c2
2024-03-27 22:12:32.054 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/array_sample.lyp'.
array_sample: uid 32030b5d, ports [], references ['Component_with_references_1', 'Component_with_references_2', 'Component_with_references_3'], 0 polygons
../_images/93a52d851997b466907e7d9fe04f0d14e8a659aa53f66b8c87b481bc5c9b908c.png

As you’ve seen you have two ways to add a reference to our component:

  1. create the reference and add it to the component

c = gf.Component("reference_sample")
w = gf.components.straight(width=0.6)
wr = w.ref()
c.add(wr)
c.plot()
2024-03-27 22:12:32.244 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/reference_sample.lyp'.
../_images/30cc45359f18592bea7a3a9b4c7daf81bccdedf46fa4482d0cebf01543953316.png
  1. or do it in a single line

c = gf.Component("reference_sample_shorter_syntax")
wr = c << gf.components.straight(width=0.6)
c.plot()
2024-03-27 22:12:32.426 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/reference_sample_shorter_syntax.lyp'.
../_images/30cc45359f18592bea7a3a9b4c7daf81bccdedf46fa4482d0cebf01543953316.png

in both cases you can move the reference wr after created

c = gf.Component("two_references")
wr1 = c << gf.components.straight(width=0.6)
wr2 = c << gf.components.straight(width=0.6)
wr2.movey(10)
c.add_ports(wr1.get_ports_list(), prefix="bot_")
c.add_ports(wr2.get_ports_list(), prefix="top_")
c.ports
{'bot_o1': {'name': 'bot_o1', 'width': 0.6, 'center': [0.0, 0.0], 'orientation': 180.0, 'layer': [1, 0], 'port_type': 'optical'},
 'bot_o2': {'name': 'bot_o2', 'width': 0.6, 'center': [10.0, 0.0], 'orientation': 0.0, 'layer': [1, 0], 'port_type': 'optical'},
 'top_o1': {'name': 'top_o1', 'width': 0.6, 'center': [0.0, 10.0], 'orientation': 180.0, 'layer': [1, 0], 'port_type': 'optical'},
 'top_o2': {'name': 'top_o2', 'width': 0.6, 'center': [10.0, 10.0], 'orientation': 0.0, 'layer': [1, 0], 'port_type': 'optical'}}

You can also auto_rename ports using gdsfactory default convention, where ports are numbered clockwise starting from the bottom left

c.auto_rename_ports()
c.ports
{'o1': {'name': 'o1', 'width': 0.6, 'center': [0.0, 0.0], 'orientation': 180.0, 'layer': [1, 0], 'port_type': 'optical'},
 'o4': {'name': 'o4', 'width': 0.6, 'center': [10.0, 0.0], 'orientation': 0.0, 'layer': [1, 0], 'port_type': 'optical'},
 'o2': {'name': 'o2', 'width': 0.6, 'center': [0.0, 10.0], 'orientation': 180.0, 'layer': [1, 0], 'port_type': 'optical'},
 'o3': {'name': 'o3', 'width': 0.6, 'center': [10.0, 10.0], 'orientation': 0.0, 'layer': [1, 0], 'port_type': 'optical'}}
c.plot()
2024-03-27 22:12:32.639 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/two_references.lyp'.
../_images/e39206240705ed1c74731b43bbbaf5a7f681408ba62f28c42bc358f816eaf8e5.png

Arrays of references#

In GDS, there’s a type of structure called a “ComponentReference” which takes a cell and repeats it NxM times on a fixed grid spacing. For convenience, Component includes this functionality with the add_array() function. Note that CellArrays are not compatible with ports (since there is no way to access/modify individual elements in a GDS cellarray)

gdsfactory also provides with more flexible arrangement options if desired, see for example grid() and packer().

As well as gf.components.array

Let’s make a new Component and put a big array of our Component c in it:

c3 = gf.Component("array_of_references")  # Create a new blank Component
aref = c3.add_array(
    c, columns=6, rows=3, spacing=[20, 15]
)  # Reference the Component "c" 3 references in it with a 3 rows, 6 columns array
c3
2024-03-27 22:12:32.816 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/array_of_references.lyp'.
array_of_references: uid 701eba22, ports [], references ['two_references_1'], 0 polygons
../_images/5fc07e0c471d9700fcfad1db345299ed3e6f791f8550acaeb24f70a3b37e4919.png

CellArrays don’t have ports and there is no way to access/modify individual elements in a GDS cellarray.

gdsfactory provides you with similar functions in gf.components.array and gf.components.array_2d

c4 = gf.Component("demo_array")  # Create a new blank Component
aref = c4 << gf.components.array(component=c, columns=3, rows=2)
c4.add_ports(aref.get_ports_list())
c4
2024-03-27 22:12:32.998 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/demo_array.lyp'.
demo_array: uid 29d2df97, ports ['o1_1_1', 'o1_1_2', 'o1_1_3', 'o2_1_1', 'o2_1_2', 'o2_1_3', 'o1_2_1', 'o1_2_2', 'o1_2_3', 'o2_2_1', 'o2_2_2', 'o2_2_3', 'o3_2_1', 'o3_2_2', 'o3_2_3', 'o4_2_1', 'o4_2_2', 'o4_2_3', 'o3_1_1', 'o3_1_2', 'o3_1_3', 'o4_1_1', 'o4_1_2', 'o4_1_3'], references ['array_1'], 0 polygons
../_images/3878ab1a5e07c50d1b6e05b7a0448b21274d0f92bf44a6a03499d5bfbf42074d.png
help(gf.components.array)
Help on function array in module gdsfactory.components.array_component:

array(component: 'ComponentSpec' = 'pad', spacing: 'tuple[float, float]' = (150.0, 150.0), columns: 'int' = 6, rows: 'int' = 1, add_ports: 'bool' = True, size: 'Float2 | None' = None, centered: 'bool' = False) -> gdsfactory.component.Component
    Returns an array of components.
    
    Args:
        component: to replicate.
        spacing: x, y spacing.
        columns: in x.
        rows: in y.
        add_ports: add ports from component into the array.
        size: Optional x, y size. Overrides columns and rows.
        centered: center the array around the origin.
    
    Raises:
        ValueError: If columns > 1 and spacing[0] = 0.
        ValueError: If rows > 1 and spacing[1] = 0.
    
    .. code::
    
        2 rows x 4 columns
         ___        ___       ___          ___
        |   |      |   |     |   |        |   |
        |___|      |___|     |___|        |___|
    
         ___        ___       ___          ___
        |   |      |   |     |   |        |   |
        |___|      |___|     |___|        |___|

You can also create an array of references for periodic structures. Let’s create a Distributed Bragg Reflector

@gf.cell
def dbr_period(w1=0.5, w2=0.6, l1=0.2, l2=0.4, straight=gf.components.straight):
    """Return one DBR period."""
    c = gf.Component()
    r1 = c << straight(length=l1, width=w1)
    r2 = c << straight(length=l2, width=w2)
    r2.connect(port="o1", destination=r1.ports["o2"])
    c.add_port("o1", port=r1.ports["o1"])
    c.add_port("o2", port=r2.ports["o2"])
    return c


l1 = 0.2
l2 = 0.4
n = 3
period = dbr_period(l1=l1, l2=l2)
period
2024-03-27 22:12:33.181 | WARNING  | gdsfactory.component_reference:connect:812 - UserWarning: Port width mismatch: 0.6 != 0.5 in straight_length0p4_width0p6 on layer (1, 0)
2024-03-27 22:12:33.205 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/dbr_period.lyp'.
/home/runner/work/gdsfactory/gdsfactory/gdsfactory/component_reference.py:812: UserWarning: Port width mismatch: 0.6 != 0.5 in straight_length0p4_width0p6 on layer (1, 0)
  warnings.warn(message)
dbr_period: uid e77f859c, ports ['o1', 'o2'], references ['straight_1', 'straight_2'], 0 polygons
../_images/7d885283b5f177fa7294c0753caa973bec35eaf3aaf805a7433d8bc93f696eb8.png
dbr = gf.Component("DBR")
dbr.add_array(period, columns=n, rows=1, spacing=(l1 + l2, 100))
dbr
2024-03-27 22:12:33.428 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/DBR.lyp'.
DBR: uid 51d60b82, ports [], references ['dbr_period_1'], 0 polygons
../_images/a0c61c571664e8b3d8686d7bd0f8cdff3a6312da638ad0c23af5ff14fe04395c.png

Finally we need to add ports to the new component

p0 = dbr.add_port("o1", port=period.ports["o1"])
p1 = dbr.add_port("o2", port=period.ports["o2"])

p1.center = [(l1 + l2) * n, 0]
dbr
2024-03-27 22:12:33.577 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/DBR.lyp'.
DBR: uid 51d60b82, ports ['o1', 'o2'], references ['dbr_period_1'], 0 polygons
../_images/001d101d0c66e63ca567afa16b4dd42f5ccd50a513216f95fd06e878eb4e335c.png

Connect references#

We have seen that once you create a reference you can manipulate the reference to move it to a location. Here we are going to connect that reference to a port. Remember that we follow that a certain reference source connects to a destination port

bend = gf.components.bend_circular()
bend
2024-03-27 22:12:33.725 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/bend_circular.lyp'.
bend_circular: uid 8f4a9de8, ports ['o1', 'o2'], references [], 1 polygons
../_images/0f4fe2c6ca36e7119143aac8ccf7bd4342b57975b9c06e7176bf1f9a95a40bb4.png
c = gf.Component("sample_reference_connect")

mmi = c << gf.components.mmi1x2()
b = c << gf.components.bend_circular()
b.connect("o1", destination=mmi.ports["o2"])

c.add_port("o1", port=mmi.ports["o1"])
c.add_port("o2", port=b.ports["o2"])
c.add_port("o3", port=mmi.ports["o3"])
c.plot()
2024-03-27 22:12:33.878 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/sample_reference_connect.lyp'.
../_images/3002b3a428e7b6110b3a964a5e6d3ef334a398386c90f1530e853a1c2e0735d4.png

You can also access the ports as reference[port_name] instead of reference.ports[port_name]

c = gf.Component("sample_reference_connect_simpler")

mmi = c << gf.components.mmi1x2()
b = c << gf.components.bend_circular()
b.connect("o1", destination=mmi["o2"])

c.add_port("o1", port=mmi["o1"])
c.add_port("o2", port=b["o2"])
c.add_port("o3", port=mmi["o3"])
c.plot()
2024-03-27 22:12:34.026 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/sample_reference_connect_simpler.lyp'.
../_images/3002b3a428e7b6110b3a964a5e6d3ef334a398386c90f1530e853a1c2e0735d4.png
c = gf.Component("sample_reference_connect_simpler")

mmi = c << gf.components.mmi1x2()
b = c.add_ref(gf.components.bend_circular()).connect("o1", destination=mmi["o2"])

c.add_port("o1", port=mmi["o1"])
c.add_port("o2", port=b["o2"])
c.add_port("o3", port=mmi["o3"])
c.plot()
2024-03-27 22:12:34.174 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/sample_reference_connect_simpler$1.lyp'.
../_images/3002b3a428e7b6110b3a964a5e6d3ef334a398386c90f1530e853a1c2e0735d4.png
c = gf.Component("sample_reference_connect_simpler_with_mirror")

mmi = c << gf.components.mmi1x2()
b = (
    c.add_ref(gf.components.bend_circular())
    .mirror()
    .connect("o1", destination=mmi["o2"])
)

c.add_port("o1", port=mmi["o1"])
c.add_port("o2", port=b["o2"])
c.add_port("o3", port=mmi["o3"])
c.plot()
2024-03-27 22:12:34.324 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/sample_reference_connect_simpler_with_mirror.lyp'.
../_images/112e84c14869fdcf8611bdffecf4fa6a18975e1ec3c7eaa3dae57ec4ac3a0c8d.png

Notice that connect mates two ports together and does not imply that ports will remain connected.

Port#

You can name the ports as you want and use gf.port.auto_rename_ports(prefix='o') to rename them later on.

Here is the default naming convention.

Ports are numbered clock-wise starting from the bottom left corner.

Optical ports have o prefix and Electrical ports e prefix.

The port naming comes in most cases from the gdsfactory.cross_section. For example:

  • gdsfactory.cross_section.strip has ports o1 for input and o2 for output.

  • gdsfactory.cross_section.metal1 has ports e1 for input and e2 for output.

size = 4
c = gf.components.nxn(west=2, south=2, north=2, east=2, xsize=size, ysize=size)
c.plot()
2024-03-27 22:12:34.477 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/nxn_afe554f8.lyp'.
../_images/caa06d45840fd36502f8605c2d48bf53a75d1a4aab04d5030a88a21810ae49a1.png
c = gf.components.straight_heater_metal(length=30)
c.plot()
2024-03-27 22:12:34.651 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/straight_heater_metal_undercut_690cad76.lyp'.
../_images/ad5d8eab96401f5d00b419729c50320831bb33761ead61d658902a0916b31a9d.png
c.ports
{'o1': {'name': 'o1', 'width': 0.5, 'center': [0.0, 0.0], 'orientation': 180.0, 'layer': [1, 0], 'port_type': 'optical'},
 'o2': {'name': 'o2', 'width': 0.5, 'center': [30.0, 0.0], 'orientation': 0.0, 'layer': [1, 0], 'port_type': 'optical'},
 'l_e1': {'name': 'l_e1', 'width': 11.0, 'center': [-15.9, 0.0], 'orientation': 180.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'l_e2': {'name': 'l_e2', 'width': 11.0, 'center': [-10.4, 5.5], 'orientation': 90.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'l_e3': {'name': 'l_e3', 'width': 11.0, 'center': [-4.9, 0.0], 'orientation': 0.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'l_e4': {'name': 'l_e4', 'width': 11.0, 'center': [-10.4, -5.5], 'orientation': 270.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'r_e1': {'name': 'r_e1', 'width': 11.0, 'center': [34.9, 0.0], 'orientation': 180.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'r_e2': {'name': 'r_e2', 'width': 11.0, 'center': [40.4, 5.5], 'orientation': 90.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'r_e3': {'name': 'r_e3', 'width': 11.0, 'center': [45.9, 0.0], 'orientation': 0.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'r_e4': {'name': 'r_e4', 'width': 11.0, 'center': [40.4, -5.5], 'orientation': 270.0, 'layer': [49, 0], 'port_type': 'electrical'}}

You can get the optical ports by layer

c.get_ports_dict(layer=(1, 0))
{'o1': {'name': 'o1', 'width': 0.5, 'center': [0.0, 0.0], 'orientation': 180.0, 'layer': [1, 0], 'port_type': 'optical'},
 'o2': {'name': 'o2', 'width': 0.5, 'center': [30.0, 0.0], 'orientation': 0.0, 'layer': [1, 0], 'port_type': 'optical'}}

or by width

c.get_ports_dict(width=0.5)
{'o1': {'name': 'o1', 'width': 0.5, 'center': [0.0, 0.0], 'orientation': 180.0, 'layer': [1, 0], 'port_type': 'optical'},
 'o2': {'name': 'o2', 'width': 0.5, 'center': [30.0, 0.0], 'orientation': 0.0, 'layer': [1, 0], 'port_type': 'optical'}}
c0 = gf.components.straight_heater_metal()
c0.ports
{'o1': {'name': 'o1', 'width': 0.5, 'center': [0.0, 0.0], 'orientation': 180.0, 'layer': [1, 0], 'port_type': 'optical'},
 'o2': {'name': 'o2', 'width': 0.5, 'center': [320.0, 0.0], 'orientation': 0.0, 'layer': [1, 0], 'port_type': 'optical'},
 'l_e1': {'name': 'l_e1', 'width': 11.0, 'center': [-15.9, 0.0], 'orientation': 180.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'l_e2': {'name': 'l_e2', 'width': 11.0, 'center': [-10.4, 5.5], 'orientation': 90.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'l_e3': {'name': 'l_e3', 'width': 11.0, 'center': [-4.9, 0.0], 'orientation': 0.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'l_e4': {'name': 'l_e4', 'width': 11.0, 'center': [-10.4, -5.5], 'orientation': 270.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'r_e1': {'name': 'r_e1', 'width': 11.0, 'center': [324.9, 0.0], 'orientation': 180.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'r_e2': {'name': 'r_e2', 'width': 11.0, 'center': [330.4, 5.5], 'orientation': 90.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'r_e3': {'name': 'r_e3', 'width': 11.0, 'center': [335.9, 0.0], 'orientation': 0.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'r_e4': {'name': 'r_e4', 'width': 11.0, 'center': [330.4, -5.5], 'orientation': 270.0, 'layer': [49, 0], 'port_type': 'electrical'}}
c1 = c0.copy()
c1.auto_rename_ports_layer_orientation()
c1.ports
{'1_0_W0': {'name': '49_0_W1', 'width': 0.5, 'center': [0.0, 0.0], 'orientation': 180.0, 'layer': [1, 0], 'port_type': 'optical'},
 '1_0_E0': {'name': '49_0_E1', 'width': 0.5, 'center': [320.0, 0.0], 'orientation': 0.0, 'layer': [1, 0], 'port_type': 'optical'},
 '49_0_W0': {'name': '49_0_W0', 'width': 11.0, 'center': [-15.9, 0.0], 'orientation': 180.0, 'layer': [49, 0], 'port_type': 'electrical'},
 '49_0_N0': {'name': '49_0_N0', 'width': 11.0, 'center': [-10.4, 5.5], 'orientation': 90.0, 'layer': [49, 0], 'port_type': 'electrical'},
 '49_0_E0': {'name': '49_0_E0', 'width': 11.0, 'center': [-4.9, 0.0], 'orientation': 0.0, 'layer': [49, 0], 'port_type': 'electrical'},
 '49_0_S0': {'name': '49_0_S0', 'width': 11.0, 'center': [-10.4, -5.5], 'orientation': 270.0, 'layer': [49, 0], 'port_type': 'electrical'},
 '49_0_W2': {'name': '49_0_W2', 'width': 11.0, 'center': [324.9, 0.0], 'orientation': 180.0, 'layer': [49, 0], 'port_type': 'electrical'},
 '49_0_N1': {'name': '49_0_N1', 'width': 11.0, 'center': [330.4, 5.5], 'orientation': 90.0, 'layer': [49, 0], 'port_type': 'electrical'},
 '49_0_E2': {'name': '49_0_E2', 'width': 11.0, 'center': [335.9, 0.0], 'orientation': 0.0, 'layer': [49, 0], 'port_type': 'electrical'},
 '49_0_S1': {'name': '49_0_S1', 'width': 11.0, 'center': [330.4, -5.5], 'orientation': 270.0, 'layer': [49, 0], 'port_type': 'electrical'}}
c2 = c0.copy()
c2.auto_rename_ports()
c2.ports
{'o1': {'name': 'o1', 'width': 0.5, 'center': [0.0, 0.0], 'orientation': 180.0, 'layer': [1, 0], 'port_type': 'optical'},
 'o2': {'name': 'o2', 'width': 0.5, 'center': [320.0, 0.0], 'orientation': 0.0, 'layer': [1, 0], 'port_type': 'optical'},
 'e1': {'name': 'e1', 'width': 11.0, 'center': [-15.9, 0.0], 'orientation': 180.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'e3': {'name': 'e3', 'width': 11.0, 'center': [-10.4, 5.5], 'orientation': 90.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'e5': {'name': 'e5', 'width': 11.0, 'center': [-4.9, 0.0], 'orientation': 0.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'e8': {'name': 'e8', 'width': 11.0, 'center': [-10.4, -5.5], 'orientation': 270.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'e2': {'name': 'e2', 'width': 11.0, 'center': [324.9, 0.0], 'orientation': 180.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'e4': {'name': 'e4', 'width': 11.0, 'center': [330.4, 5.5], 'orientation': 90.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'e6': {'name': 'e6', 'width': 11.0, 'center': [335.9, 0.0], 'orientation': 0.0, 'layer': [49, 0], 'port_type': 'electrical'},
 'e7': {'name': 'e7', 'width': 11.0, 'center': [330.4, -5.5], 'orientation': 270.0, 'layer': [49, 0], 'port_type': 'electrical'}}

You can also rename them with a different port naming convention

  • prefix: add e for electrical o for optical

  • clockwise

  • counter-clockwise

  • orientation E East, W West, N North, S South

Here is the default one we use (clockwise starting from bottom left west facing port)

             3   4
             |___|_
         2 -|      |- 5
            |      |
         1 -|______|- 6
             |   |
             8   7

c = gf.Component("demo_ports")
nxn = gf.components.nxn(west=2, north=2, east=2, south=2, xsize=4, ysize=4)
ref = c.add_ref(nxn)
c.add_ports(ref.ports)
c.plot()
2024-03-27 22:12:34.857 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/demo_ports.lyp'.
../_images/caa06d45840fd36502f8605c2d48bf53a75d1a4aab04d5030a88a21810ae49a1.png
ref.get_ports_list()  # by default returns ports clockwise starting from bottom left west facing port
[{'name': 'o1', 'width': 0.5, 'center': [0.0, 1.25], 'orientation': 180.0, 'layer': [1, 0], 'port_type': 'optical'},
 {'name': 'o2', 'width': 0.5, 'center': [0.0, 2.75], 'orientation': 180.0, 'layer': [1, 0], 'port_type': 'optical'},
 {'name': 'o3', 'width': 0.5, 'center': [1.25, 4.0], 'orientation': 90.0, 'layer': [1, 0], 'port_type': 'optical'},
 {'name': 'o4', 'width': 0.5, 'center': [2.75, 4.0], 'orientation': 90.0, 'layer': [1, 0], 'port_type': 'optical'},
 {'name': 'o5', 'width': 0.5, 'center': [4.0, 2.75], 'orientation': 0.0, 'layer': [1, 0], 'port_type': 'optical'},
 {'name': 'o6', 'width': 0.5, 'center': [4.0, 1.25], 'orientation': 0.0, 'layer': [1, 0], 'port_type': 'optical'},
 {'name': 'o7', 'width': 0.5, 'center': [2.75, 0.0], 'orientation': 270.0, 'layer': [1, 0], 'port_type': 'optical'},
 {'name': 'o8', 'width': 0.5, 'center': [1.25, 0.0], 'orientation': 270.0, 'layer': [1, 0], 'port_type': 'optical'}]
c.auto_rename_ports()
c.plot()
2024-03-27 22:12:35.044 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/demo_ports.lyp'.
../_images/caa06d45840fd36502f8605c2d48bf53a75d1a4aab04d5030a88a21810ae49a1.png

You can also get the ports counter-clockwise

             4   3
             |___|_
         5 -|      |- 2
            |      |
         6 -|______|- 1
             |   |
             7   8

c.auto_rename_ports_counter_clockwise()
c.plot()
2024-03-27 22:12:35.230 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/demo_ports.lyp'.
../_images/caa06d45840fd36502f8605c2d48bf53a75d1a4aab04d5030a88a21810ae49a1.png
c.get_ports_list(clockwise=False)
[{'name': 'o1', 'width': 0.5, 'center': [4.0, 1.25], 'orientation': 0.0, 'layer': [1, 0], 'port_type': 'optical'},
 {'name': 'o2', 'width': 0.5, 'center': [4.0, 2.75], 'orientation': 0.0, 'layer': [1, 0], 'port_type': 'optical'},
 {'name': 'o3', 'width': 0.5, 'center': [2.75, 4.0], 'orientation': 90.0, 'layer': [1, 0], 'port_type': 'optical'},
 {'name': 'o4', 'width': 0.5, 'center': [1.25, 4.0], 'orientation': 90.0, 'layer': [1, 0], 'port_type': 'optical'},
 {'name': 'o5', 'width': 0.5, 'center': [0.0, 2.75], 'orientation': 180.0, 'layer': [1, 0], 'port_type': 'optical'},
 {'name': 'o6', 'width': 0.5, 'center': [0.0, 1.25], 'orientation': 180.0, 'layer': [1, 0], 'port_type': 'optical'},
 {'name': 'o7', 'width': 0.5, 'center': [1.25, 0.0], 'orientation': 270.0, 'layer': [1, 0], 'port_type': 'optical'},
 {'name': 'o8', 'width': 0.5, 'center': [2.75, 0.0], 'orientation': 270.0, 'layer': [1, 0], 'port_type': 'optical'}]
c.ports_layer
{'1_0_W0': 'o6',
 '1_0_W1': 'o5',
 'o1': 'o1',
 'o2': 'o2',
 '1_0_N0': 'o4',
 '1_0_N1': 'o3',
 '1_0_S0': 'o7',
 '1_0_S1': 'o8'}
c.port_by_orientation_cw("W0")
{'name': 'o6', 'width': 0.5, 'center': [0.0, 1.25], 'orientation': 180.0, 'layer': [1, 0], 'port_type': 'optical'}
c.port_by_orientation_ccw("W1")
{'name': 'o6', 'width': 0.5, 'center': [0.0, 1.25], 'orientation': 180.0, 'layer': [1, 0], 'port_type': 'optical'}

Lets extend the East facing ports (orientation = 0 deg)

cross_section = gf.cross_section.strip()

nxn = gf.components.nxn(
    west=2, north=2, east=2, south=2, xsize=4, ysize=4, cross_section=cross_section
)
c = gf.components.extension.extend_ports(component=nxn, orientation=0)
c.plot()
2024-03-27 22:12:35.529 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/nxn_extend_ports_0a752cf5.lyp'.
../_images/f58c42e1fc0c85170e74f2302683329f46b62395901993d47ac90494499ad495.png
c.ports
{'o1': {'name': 'o1', 'width': 0.5, 'center': [0.0, 1.25], 'orientation': 180, 'layer': [1, 0], 'port_type': 'optical'},
 'o2': {'name': 'o2', 'width': 0.5, 'center': [0.0, 2.75], 'orientation': 180, 'layer': [1, 0], 'port_type': 'optical'},
 'o3': {'name': 'o3', 'width': 0.5, 'center': [1.25, 4.0], 'orientation': 90, 'layer': [1, 0], 'port_type': 'optical'},
 'o4': {'name': 'o4', 'width': 0.5, 'center': [2.75, 4.0], 'orientation': 90, 'layer': [1, 0], 'port_type': 'optical'},
 'o5': {'name': 'o5', 'width': 0.5, 'center': [9.0, 2.75], 'orientation': 0.0, 'layer': [1, 0], 'port_type': 'optical'},
 'o6': {'name': 'o6', 'width': 0.5, 'center': [9.0, 1.25], 'orientation': 0.0, 'layer': [1, 0], 'port_type': 'optical'},
 'o7': {'name': 'o7', 'width': 0.5, 'center': [2.75, 0.0], 'orientation': 270, 'layer': [1, 0], 'port_type': 'optical'},
 'o8': {'name': 'o8', 'width': 0.5, 'center': [1.25, 0.0], 'orientation': 270, 'layer': [1, 0], 'port_type': 'optical'}}
df = c.get_ports_pandas()
df
name width center orientation layer port_type shear_angle
0 o1 0.5 [0.0, 1.25] 180.0 [1, 0] optical None
1 o2 0.5 [0.0, 2.75] 180.0 [1, 0] optical None
2 o3 0.5 [1.25, 4.0] 90.0 [1, 0] optical None
3 o4 0.5 [2.75, 4.0] 90.0 [1, 0] optical None
4 o5 0.5 [9.0, 2.75] 0.0 [1, 0] optical None
5 o6 0.5 [9.0, 1.25] 0.0 [1, 0] optical None
6 o7 0.5 [2.75, 0.0] 270.0 [1, 0] optical None
7 o8 0.5 [1.25, 0.0] 270.0 [1, 0] optical None
df[df.port_type == "optical"]
name width center orientation layer port_type shear_angle
0 o1 0.5 [0.0, 1.25] 180.0 [1, 0] optical None
1 o2 0.5 [0.0, 2.75] 180.0 [1, 0] optical None
2 o3 0.5 [1.25, 4.0] 90.0 [1, 0] optical None
3 o4 0.5 [2.75, 4.0] 90.0 [1, 0] optical None
4 o5 0.5 [9.0, 2.75] 0.0 [1, 0] optical None
5 o6 0.5 [9.0, 1.25] 0.0 [1, 0] optical None
6 o7 0.5 [2.75, 0.0] 270.0 [1, 0] optical None
7 o8 0.5 [1.25, 0.0] 270.0 [1, 0] optical None

Port markers (Pins)#

You can add pins (port markers) to each port. Different foundries do this differently, so gdsfactory supports all of them.

  • square with port inside the component.

  • square centered (half inside, half outside component).

  • triangular pointing towards the outside of the port.

  • path (SiEPIC).

by default Component.show() will add triangular pins, so you can see the direction of the port in Klayout.

gf.components.mmi1x2()
2024-03-27 22:12:35.731 | WARNING  | gdsfactory.klive:show:49 - UserWarning: Could not connect to klive server. Is klayout open and klive plugin installed?
2024-03-27 22:12:35.747 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/mmi1x2.lyp'.
/home/runner/work/gdsfactory/gdsfactory/gdsfactory/klive.py:49: UserWarning: Could not connect to klive server. Is klayout open and klive plugin installed?
  warnings.warn(
mmi1x2: uid a606b028, ports ['o1', 'o2', 'o3'], references [], 4 polygons
../_images/5831eaaee87f93da564b8600f149b9287cf4dd6adaa8e43199b057c31c5b052b.png
mmi = gf.components.mmi1x2()
mmi_with_pins = gf.add_pins.add_pins_container(mmi)
mmi_with_pins.plot()
2024-03-27 22:12:35.928 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/mmi1x2_container_abbf818a.lyp'.
../_images/90cb8bba9649fbad42f8c9615f28ad571faf7555d975c965118be67462324f7c.png

Component_sequence#

When you have repetitive connections you can describe the connectivity as an ASCII map

bend180 = gf.components.bend_circular180()
wg_pin = gf.components.straight_pin(length=40)
wg = gf.components.straight()

# Define a map between symbols and (component, input port, output port)
symbol_to_component = {
    "D": (bend180, "o1", "o2"),
    "C": (bend180, "o2", "o1"),
    "P": (wg_pin, "o1", "o2"),
    "-": (wg, "o1", "o2"),
}

# Generate a sequence
# This is simply a chain of characters. Each of them represents a component
# with a given input and and a given output

sequence = "DC-P-P-P-P-CD"
component = gf.components.component_sequence(
    sequence=sequence, symbol_to_component=symbol_to_component
)
component.name = "component_sequence"
component.plot()
2024-03-27 22:12:36.152 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/component_sequence.lyp'.
../_images/dff04f52191e46b2908d0bd93ed551940c4878ccd71f66121db9161964d54e29.png

As the sequence is defined as a string you can use the string operations to easily build complex sequences

Movement#

You can move, rotate and mirror ComponentReference as well as Port, Polygon, ComponentReference, Label, and Group

import gdsfactory as gf

# Start with a blank Component
c = gf.Component("demo_movement")

# Create some more Components with shapes
T = gf.components.text("hello", size=10, layer=(1, 0))
E = gf.components.ellipse(radii=(10, 5), layer=(2, 0))
R = gf.components.rectangle(size=(10, 3), layer=(3, 0))

# Add the shapes to c as references
text = c << T
ellipse = c << E
rect1 = c << R
rect2 = c << R

c.plot()
2024-03-27 22:12:36.341 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/demo_movement.lyp'.
../_images/f5b8df089e34cc5a9ea0aba1188386c7b3473b855ca42bf37cc09705084a57c2.png
c = gf.Component("move_one_ellipse")
e1 = c << gf.components.ellipse(radii=(10, 5), layer=(2, 0))
e2 = c << gf.components.ellipse(radii=(10, 5), layer=(2, 0))
e1.movex(10)
c.plot()
2024-03-27 22:12:36.529 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/move_one_ellipse.lyp'.
../_images/0692ecd7bf15e9c1775e736f10e6c6c14e7d43a4ab0c83c39a918d099df77988.png
c = gf.Component("move_one_ellipse_xmin")
e1 = c << gf.components.ellipse(radii=(10, 5), layer=(2, 0))
e2 = c << gf.components.ellipse(radii=(10, 5), layer=(2, 0))
e2.xmin = e1.xmax
c.plot()
2024-03-27 22:12:36.688 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/move_one_ellipse_xmin.lyp'.
../_images/04ac6b03e00d4ceb63bd6defee89a3b0b2149482eae3d14eef69e81e850d61c0.png
# Now you can practice move and rotate the objects.

c = gf.Component("two_ellipses_on_top_of_each_other")
E = gf.components.ellipse(radii=(10, 5), layer=(2, 0))
e1 = c << E
e2 = c << E
c.plot()
2024-03-27 22:12:36.879 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/two_ellipses_on_top_of_each_other.lyp'.
../_images/a587c1552790109a6c6b63a9414d90c5efe8a7bc6f4875ac45f53b32f66a31bd.png
c = gf.Component("ellipse_moved")
e = gf.components.ellipse(radii=(10, 5), layer=(2, 0))
e1 = c << e
e2 = c << e
e2.move(origin=[5, 5], destination=[10, 10])  # Translate by dx = 5, dy = 5
c.plot()
2024-03-27 22:12:37.066 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/ellipse_moved.lyp'.
../_images/bbf70f07c10b92b14d8e48e773a553f1bb098b8bc4c91ac31f00a72f9ff54e4b.png
c = gf.Component("ellipse_moved_v2")
e = gf.components.ellipse(radii=(10, 5), layer=(2, 0))
e1 = c << e
e2 = c << e
e2.move([5, 5])  # Translate by dx = 5, dy = 5
c.plot()
2024-03-27 22:12:37.260 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/ellipse_moved_v2.lyp'.
../_images/bbf70f07c10b92b14d8e48e773a553f1bb098b8bc4c91ac31f00a72f9ff54e4b.png
c = gf.Component("rectangles")
r = gf.components.rectangle(size=(10, 5), layer=(2, 0))
rect1 = c << r
rect2 = c << r

rect1.rotate(45)  # Rotate the first straight by 45 degrees around (0,0)
rect2.rotate(
    -30, center=[1, 1]
)  # Rotate the second straight by -30 degrees around (1,1)
c.plot()
2024-03-27 22:12:37.432 | WARNING  | gdsfactory.component:_write_library:1934 - UserWarning: Component rectangles has invalid transformations. Try component.flatten_offgrid_references() first.
2024-03-27 22:12:37.455 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/rectangles.lyp'.
/home/runner/work/gdsfactory/gdsfactory/gdsfactory/component.py:1934: UserWarning: Component rectangles has invalid transformations. Try component.flatten_offgrid_references() first.
  warnings.warn(
../_images/65305ea62094365fba6162115466adefc534a7ddc6d0a12b5496e6625a86bf6c.png
c = gf.Component("mirror_demo")
text = c << gf.components.text("hello")
text.mirror(p1=[1, 1], p2=[1, 3])  # Reflects across the line formed by p1 and p2
c.plot()
2024-03-27 22:12:37.727 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/mirror_demo.lyp'.
../_images/52834538b44e12b3a6768940d9d1a3ba83d01153fc85d0e6841bfff1a1b12005.png
c = gf.Component("hello")
text = c << gf.components.text("hello")
c.plot()
2024-03-27 22:12:37.908 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/hello.lyp'.
../_images/4e0d36f0b70f0d3767e6ee240f819ff72074e0aa6d719e11c665f65d4d48f48c.png

Each Component and ComponentReference object has several properties which can be used to learn information about the object (for instance where it’s center coordinate is). Several of these properties can actually be used to move the geometry by assigning them new values.

Available properties are:

  • xmin / xmax: minimum and maximum x-values of all points within the object

  • ymin / ymax: minimum and maximum y-values of all points within the object

  • x: centerpoint between minimum and maximum x-values of all points within the object

  • y: centerpoint between minimum and maximum y-values of all points within the object

  • bbox: bounding box (see note below) in format ((xmin,ymin),(xmax,ymax))

  • center: center of bounding box

print("bounding box:")
print(
    text.bbox
)  # Will print the bounding box of text in terms of [(xmin, ymin), (xmax, ymax)]
print("xsize and ysize:")
print(text.xsize)  # Will print the width of text in the x dimension
print(text.ysize)  # Will print the height of text in the y dimension
print("center:")
print(text.center)  # Gives you the center coordinate of its bounding box
print("xmax")
print(text.xmax)  # Gives you the rightmost (+x) edge of the text bounding box

# Let's use these properties to manipulate our shapes to arrange them a little
# better
bounding box:
[[ 1.  0.]
 [34. 11.]]
xsize and ysize:
33.0
11.0
center:
[17.5  5.5]
xmax
34.0
c = gf.Component("canvas")
text = c << gf.components.text("hello")
E = gf.components.ellipse(radii=(10, 5), layer=(3, 0))
R = gf.components.rectangle(size=(10, 5), layer=(2, 0))
rect1 = c << R
rect2 = c << R
ellipse = c << E
c.plot()
2024-03-27 22:12:38.103 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/canvas.lyp'.
../_images/804c0a668ec20fa15a1206a4e8996e0d785304b3a4de9907be3466d55cc023b0.png
ellipse.center = [
    0,
    0,
]  # Move the ellipse such that the bounding box center is at (0,0)

# Next, let's move the text to the left edge of the ellipse
text.y = (
    ellipse.y
)  # Move the text so that its y-center is equal to the y-center of the ellipse
text.xmax = ellipse.xmin  # Moves the ellipse so its xmax == the ellipse's xmin

# Align the right edge of the rectangles with the x=0 axis
rect1.xmax = 0
rect2.xmax = 0

# Move the rectangles above and below the ellipse
rect1.ymin = ellipse.ymax + 5
rect2.ymax = ellipse.ymin - 5

c.plot()
2024-03-27 22:12:38.295 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/canvas.lyp'.
../_images/765a3c795e84c45cbaeba697d888263c8d0c4d9ff20ccac281cc089eac6d8d44.png
# In addition to working with the properties of the references inside the
# Component,
# we can also manipulate the whole Component if we want.  Let's try mirroring the
# whole Component `c`:

print(c.xmax)  # Prints out '10.0'

c2 = c.mirror((0, 1))  # Mirror across line made by (0,0) and (0,1)
c2.plot()
10.0
2024-03-27 22:12:38.484 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/_mirror_componentcanvas.lyp'.
../_images/a13bfaa6181142b7f6eedf5d4348e229bc4b7278bbd4e2350ec3df77161fb071.png
# A bounding box is the smallest enclosing box which contains all points of the geometry.

c = gf.Component("hi_bbox")
text = c << gf.components.text("hi")
bbox = text.bbox
c << gf.components.bbox(bbox=bbox, layer=(2, 0))
c.plot()
2024-03-27 22:12:38.676 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/hi_bbox.lyp'.
../_images/eeaa1e344c1a8fefe8bb59e265986fa9fff77a86e091334a95ef6a93aed1f484.png
c = gf.Component("sample_padding")
text = c << gf.components.text("bye")
device_bbox = text.bbox
c.add_polygon(gf.get_padding_points(text, default=1), layer=(2, 0))
c.plot()
2024-03-27 22:12:38.871 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/sample_padding.lyp'.
../_images/d814b6155af097a55ae6f2a7bc4feed857e78817ed52388be89b0a4d79af4ca4.png
# When we query the properties of c, they will be calculated with respect to this bounding-rectangle.  For instance:

print("Center of Component c:")
print(c.center)

print("X-max of Component c:")
print(c.xmax)
Center of Component c:
[12.   3.5]
X-max of Component c:
24.0
c = gf.Component("rect")
R = gf.components.rectangle(size=(10, 3), layer=(2, 0))
rect1 = c << R
c.plot()
2024-03-27 22:12:39.071 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/rect.lyp'.
../_images/54d8792c2e0b43218ea1d599b1dad93f3521dc72916ddeff50a79200d1be6a90.png
# You can chain many of the movement/manipulation functions because they all return the object they manipulate.
# For instance you can combine two expressions:

rect1.rotate(angle=37)
rect1.move([10, 20])
c.plot()
2024-03-27 22:12:39.234 | WARNING  | gdsfactory.component:_write_library:1934 - UserWarning: Component rect has invalid transformations. Try component.flatten_offgrid_references() first.
2024-03-27 22:12:39.257 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/rect.lyp'.
/home/runner/work/gdsfactory/gdsfactory/gdsfactory/component.py:1934: UserWarning: Component rect has invalid transformations. Try component.flatten_offgrid_references() first.
  warnings.warn(
../_images/770d8d9340e1be490de5a2f12cacef5172ff87fc35a978cf6238eaaee6ac6c01.png
# ...into this single-line expression

c = gf.Component("single_expression")
R = gf.components.rectangle(size=(10, 3), layer=(2, 0))
rect1 = c << R
rect1.rotate(angle=37).move([10, 20])
c.plot()
2024-03-27 22:12:39.433 | WARNING  | gdsfactory.component:_write_library:1934 - UserWarning: Component single_expression has invalid transformations. Try component.flatten_offgrid_references() first.
/home/runner/work/gdsfactory/gdsfactory/gdsfactory/component.py:1934: UserWarning: Component single_expression has invalid transformations. Try component.flatten_offgrid_references() first.
  warnings.warn(
2024-03-27 22:12:39.456 | INFO     | gdsfactory.technology.layer_views:to_lyp:1018 - LayerViews written to '/tmp/gdsfactory/single_expression.lyp'.
../_images/770d8d9340e1be490de5a2f12cacef5172ff87fc35a978cf6238eaaee6ac6c01.png