xPDK BB - Boundary

The boundary field is for mask layout as well as on-screen display to avoid overlapping elements. Different shapes are available.
XSD(boundary):
Annotate the topview with different aspects. The typical aspect is the "geometric" boundary, but you can specify multiple regions with other aspects like "metal", "rf" or special optical exclusions and so on.
You can define as many boundaries as needed.

You can define a polygon (use point), a rectangle, circle or ellips now. Additional types will be added later.
Via the <spt> tag you can use OptoDesigner specific shapes also in case you want a white-box building block.

The "purpose" attribute set more details in case multiple boundaries are used. And the "xsection" can be used to use the xsection's to write to GDS, support DRC and so on.

purpose

This optional field is a general string and thus can have any value. However design software is likely to ignore "nice" names and just uses the listed ones. You can propose & use new ones however.
XSD(purpose):
Typical region purposes are: boundary, metal, waveguide, dc, rf but you can add others like thermal, mechanical and so on.
Without a purpose string it is defined as the global boundary and should contain all the other regions. This avoids the need of calculating (by software) the outer boundary which is used in the designs.
full file

<bb name="myBB">
 <port label="in0">
   <position>
     <x>0</x>
   </position>
 </port>
 <boundary purpose="waveguide">
   <rectangle portref="in0" width="10" length="20" x="0" y="0" />
 </boundary>
</bb>

xsection

XSD(xsection):
The xsection allows to specify this boundary is also used via the design / mcs / cad layer. This is oriented at gray-box and black-box design rule checking, where you do not have the full data for things like distance checks.
Using the xsection can reduce the amount of cases where you need spt-sections in the cell definition as it allows to easily use white-box designs also.

The example shows a reference on the locally defined A.
full file

 <!-- define xsection for use in boundary -->
<xsection name="A" />

<bb name="myBB">
 <port label="in0">
   <position>
     <x>0</x>
   </position>
 </port>
 <boundary>
   <rectangle portref="in0" width="10" length="20" x="0" y="0" />
   <xsection>A</xsection>
 </boundary>
</bb>

spt

XSD(spt):

The following spt gives a parabolic taper.
full file

<bb name="myBB">
 <port label="in0">
  <position>
     <x>0</x>
   </position>
 </port>
 <boundary>
  <od_spt>
   ml::Straight(cin-> this@in0 : wopar(1,3),20);
  </od_spt>
 </boundary>
</bb>

align

See also docu at portref as this field relates to that one.
XSD(align):
The alignment allows to move the shape relative to the portref. Using "bic" is good for input ports on symetric devices. Using "boc" is good for the outputs.
For DC/RF pads the "bcc" is a likely candidate.

Allowing shapes to relate to ports saves a lot of equations being re-used and thus makes the file more readable. An example is the polar bend, where the end point is [R*cos(a),R*sin(a)] so if you need to define a small rectangle on the "inside" of the bend, you need lots of equations.
The alignment values are shown below and refer to a rectangle that will fit just around the shape you work on; so for a circle the bil will not be on the bic location but at [-R,R] compared to the center of such a circle.
--------------------
|bil     bcl    bol|
|                  |
|bic     bcc    boc|
|                  |
|bir     bcr    bor|
--------------------
    
full file

 <!-- define xsection for use in boundary -->
<xsection name="A" />

<bb name="myBB">
 <port label="org" />
 <port label="in0" org="true">
   <position>
     <x>0</x>
   </position>
 </port>
 <port label="out0">
   <position>
    <x>200</x><y>50</y><angle>45</angle>
   </position>
 </port>
 <port label="out1">
   <position>
    <x>200</x><y>-50</y><angle>-45</angle>
   </position>
 </port>
 <boundary>
   <!-- default alignment: portref="org"  align="bic"
      - does not need to be defined.
     -->
   <rectangle  width="60" length="200" />
 </boundary>
 <boundary>
   <rectangle portref="in0"  align="bic" width="10" length="20" />
 </boundary>
 <boundary>
   <rectangle portref="out0" align="boc" width="10" length="20" />
 </boundary>
 <boundary>
   <rectangle portref="out1" align="boc" width="10" length="20" />
 </boundary>
</bb>

portref

See also docu at align as this field relates to that one.
XSD(portref):
When using a portref/align the x,y is relative to that location.

The default port to which shapes are defined is the normally implicitly defined org which is often the in0 port for Y-symmetric building blocks like straight or tapering waveguide as well as 1xN or Nx1 MMIs and many others.
This combines with the default alignment of bic to have the center-left of a shape like a rectangle to be be placed in the [0,0] of such a building block - this is a typical situation.
In many cases it is unhandy to use such a reference for a shape; a simple rule is to keep the coordinate expressions short and/or have clear references for the link. If for example you want to have a small rectangle at an outX port, it is easier to use:

  portref="out0" align="boc"
  
without using x & y at all instead of trying to calculate the [x,y] based on an org port. For example you can try this for a simple polar bend - the math is not too complex but the equations are lengthy and error-prone in maintenance.
To be portable between software, you need to define the port to which portref refers explictly. And when you define ports relative to other ports, they should be defined before use also.
Note - when just targetting OptoDesigner these restrictions do not apply as the locations of ports will be calculated during the netlist expansion and ordering of ports per building block is not relevant.
full file

 <!-- define xsection for use in boundary -->
<xsection name="A" />

<bb name="myBB">
 <port label="org" />
 <port label="in0" org="true">
   <position>
     <x>0</x>
   </position>
 </port>
 <port label="out0">
   <position>
    <x>200</x><y>50</y><angle>45</angle>
   </position>
 </port>
 <port label="out1">
   <position>
    <x>200</x><y>-50</y><angle>-45</angle>
   </position>
 </port>
 <boundary>
   <!-- default alignment: portref="org"  align="bic"
      - does not need to be defined.
     -->
   <rectangle  width="60" length="200" />
 </boundary>
 <boundary>
   <rectangle portref="in0"  align="bic" width="10" length="20" />
 </boundary>
 <boundary>
   <rectangle portref="out0" align="boc" width="10" length="20" />
 </boundary>
 <boundary>
   <rectangle portref="out1" align="boc" width="10" length="20" />
 </boundary>
</bb>

point

XSD(point):
Define a series of points using [x,y] pairs. The values for x & y can be expressions and have unit micron.
The [x,y] are defined always with respect to the port org and the portref/align can thus not be used for a polygon. This is defined this way to avoid complex boundary calculations to find the bic/boc and so on.
full file

 <bb name="myBB">
  <port label="org" />
  <port label="in0" org="true">
   <position>
     <x>0</x>
   </position>
 </port>
  <boundary>
   <point x="0" y="-myWidth/2"/>
   <point x="myLength" y="-myWidth/2"/>
   <point x="myLength" y="myWidth/2"/>
   <point x="0" y="myWidth/2"/>
  </boundary>
 </bb>

rectangle

For example see portref.
XSD(rectangle):
Define a rectangle with width, length and [x,y] defined in micron.

circle

XSD(circle):
Define a circle with radius and [x,y] defined in micron.
full file

 <bb name="myBB">
  <port label="org" />
  <port label="in0" org="true">
   <position>
     <x>0</x>
   </position>
 </port>
 <boundary> <!-- using align=bcc puts the circle's center on [x,y] -->
   <circle portref="in0" align="bcc" x="25" y="5" radius="10"/>
  </boundary>
 </bb>

ellips

XSD(ellips):
Define a ellips with radiusX, radiusY and [x,y] defined in micron.
full file

 <bb name="myBB">
  <port label="org" />
  <port label="in0" org="true">
   <position>
     <x>0</x>
   </position>
 </port>
  <boundary> <!-- using align=bcc puts the ellips's center on [x,y] -->
   <ellips portref="in0" align="bcc" x="25" y="5" radiusX="10" radiusY="5"/>
  </boundary>
 </bb>