pdaPortDefinition

Ports are the connection point for BBs and can be signal (schematic interfaces) and/or geometric-only (bounding box etc in OptoDesigner).
We want at least 1 port, otherwise we can not connect / place the instances. And as ports are key for connection, layout and simulation. Therefore a lot of information can be specified here.

Ports have a "per component" aspect (local coordinates) which typically depends on the parameters like widths and lengths of the BB. After placement on a chip/die these are then also associated with global coordinates. If the die is placed via Assembly Design Kit (ADK) suitable software like OptoDesigner these global coordinates are 6-axis values (x,y,z,y,yaw,pitch,roll) and thus incorporate both locations and angles in 3D.

Therefore the 'position' is supporting this capability also, with (for chip design) often unused "z" as well as the 3D angles pitch and roll.

Local port coordinates are assumed to be referenced to an implicitly defined "org" port, which is for Y-symmetrical devices (straight waveguide, simple MMIs, basic Yjunctions) often the "in0" port for easy calculation of output ports.
Use the org="true" attribute to specifiy a specific port is the [0,0,0,0,0,0] local position.

Use the refIn and refOut attributes to simplify element chain definitions; if they are not set, OptoDesigner will assume things instead, which is less robust. Per BB only a single port can be refIn or refOut, but the same port can be both.

Basic info

full file


<bb name="myBB">
 <port label="in0">
   <domain>Optical</domain>
   <position> <!-- units for x,y,z: um; for angle,pitch,roll: degree -->
     <x>0</x><y>0</y>
     <angle>10</angle>
   </position>
 </port>
</bb>

Values that are not specified are considered default; which is either “0” or specified in the xsd.

Design information

In addition to the locations & type, we need for photonics more things. Basic aspect is xsection which defined the design scope more precise, see the for the definition of these. Here they are references to this data.

Location design rule checks

For ports different logical rules may be needed to make sense on a layout. Typical info is either location or angle - for example an SSC in the middle of the design does not make sense.
It is also common to require crystal-axis alignment for active devices.

The min/max x/y are absolute coordinates for the chip design and have an origin that depends on the foundry - common values are to have the [0,0] at the lower-left of the design area or to have the [0,0] to be in the center of the design area. The former is most common, so the example below uses that.
As the foundry defines both the [0,0] and the coordinate checks, it is no problem to use a different setup - as long as they are consistent.

full file


<xsection name="WG"/>

<bb name="myBB">
 <port label="in0">
    <drcAngles>0 45 90 135 180</drcAngles>
    <drcMinimumX>200</drcMinimumX>
    <drcMaximumY>400</drcMaximumY>
  </port>
</bb>

An alternative for location based port checks it to annotate the Die-template with different zones like "SSC zone", "black box zone" and "die area zone" and use the enclosure test. This is a much more CPU-intensive test, but shrinks the amount of definitions per port or building block a lot.
Note: this is unlikely to be supported by schematic editors, who may support the port location test.

Structure

The attributes and elements are shown below, in a sorted per type fashion.
In case a list is printed after an element, it indicates that you can have many, otherwise it should be a single element. With a optional it tells the element is not required.

<pdaPortDefinition  label="..."  org="..."  portMapToName="..."  refIn="..."  refOut="..."  refport="..." ... > ...
  <WaiveReport> ... </WaiveReport>   list   optional
  <direction> ... </direction>    optional
  <doc> ... </doc>    optional
  <domain> ... </domain>    optional
  <drcAngles> ... </drcAngles>    optional
  <drcMaximumX> ... </drcMaximumX>    optional
  <drcMaximumY> ... </drcMaximumY>    optional
  <drcMinimumX> ... </drcMinimumX>    optional
  <drcMinimumY> ... </drcMinimumY>    optional
  <position> ... </position>    optional
  <radius> ... </radius>    optional
  <tex> ... </tex>    optional
  <width> ... </width>    optional
  <xsection> ... </xsection>    optional
</pdaPortDefinition>

XSD

The schema file can be downloaded or viewed at xPDK_BB.

Details

WaiveReport

Type WaiveReport documentation: Waive an issue in the Report.html

direction

full file


<bb name="myBB">
 <port label="in0"> <!-- standard optical names -->
   <domain>Optical</domain>
   <direction>In</direction>
 </port>
 <port label="out0">
   <domain>Optical</domain>
   <direction>Out</direction>
 </port>
 <port label="alt_name"> <!-- Signal allows to connect any -->
   <domain>Signal</domain>
   <direction>InOut</direction>
 </port>
</bb>

Type pdaPortDirection documentation:
For photonics ports the signals are bi-directional - also the output of a laser acts as input in the sense that if you send in optical power there, you modify the laser performance. However for a designer it is a logical output.
The same holds for a 1:2 splitter - it has a single logical input and two logical outputs, otherwise you would call it a 2:1 combiner. The geometry can be the same in optics!
Allowed values: In, Out and InOut.

doc

This field can be used when label is not directly clear and/or is not using the standard names like in/out/dc/rf/..n style names and thus needs more clarification.

full file


<bb name="myBB">
 <port label="in0"> <!-- standard optical names -->
   <domain>Optical</domain>
   <direction>In</direction>
   <doc>Standard optical input (note: optical signal is bidirectional!)</doc>
 </port>
 <port label="out0">
   <domain>Optical</domain>
   <direction>Out</direction>
   <doc>Standard optical output (note: optical signal is bidirectional!)</doc>
 </port>
 <port label="alt_name"> <!-- Signal allows to connect any -->
   <domain>Signal</domain>
   <direction>InOut</direction>
   <doc>As the port name is unclear, this is some unclear explanation on its purpose.</doc>
 </port>
</bb>

Type pdaDocumentation documentation:
This field allows some (short, few lines) documentation to be written. It can be a long string, but the idea is not to replace a design manual.
This fields is like tex which allows documentation in LaTex format; doc is restricted to plain text.

domain

full file


<bb name="myBB">
 <port label="in0"> <!-- standard optical names -->
   <domain>Optical</domain>
 </port>
 <port label="out0">
   <domain>Optical</domain>
 </port>
 <port label="dc0"> <!-- standard DC names -->
   <domain>DC</domain>
 </port>
 <port label="dci0">
   <domain>DC</domain>
 </port>
 <port label="dco0">
   <domain>DC</domain>
 </port>
 <port label="rf0"> <!-- standard RF names -->
   <domain>RF</domain>
 </port>
 <port label="rfi0">
   <domain>RF</domain>
 </port>
 <port label="rfo0">
   <domain>RF</domain>
 </port>
 <port label="alt_name"> <!-- Signal allows to connect any -->
   <domain>Signal</domain>
 </port>
</bb>

Type pdaDomain documentation: match for both building blocks.

Supported values:

Optical: optical signal, light is bi-directional for modelling.
RF: different styles exist like s / gsg / gssg and so on. For > few GHz.
DC: assuming for low(er) rate signals so including AC; so typical speeds to < 1 GHz
Signal
This value defines that any domain is acceptable, which is suitable for things like straight waveguides that are allowed in multiple xsection's and therefore can span multiple domains.
Geometric
This defines that the domain is just geometric, so no electrical or optical signal will go through it. Its purpose is thus for layout oriented software, but can also be used as port to connect a boundary to and thus simplify long equations you may otherwise need. See at the boundary, the portref/align documentation.

drcAngles

Space seperated list of allowed global angles (in degrees) for the port.

The per-port angle check is less common then the BB-global alignment, but is more specific and is usefull for cases where the BB ports are not all parallel / orthogonal.

Type pdaDoubleList documentation: text (attribute or element).

drcMaximumX

Maximum global X for the port (micron).
Look at drcMinimumY for an example that has global chip sizes and uses those values to define ports to be in a range. Type pdaExpression documentation:
Expression need to be commonly evaluated by many software, so having a restricted set of math / types and so on is key. In PDAFlow lib2/expr there is a yacc/lex parser available with some unit support as well as double / complex expressions. An alternative is tinyexpr, but this is more restrictive, so may be very unhandy for things like waveguide model expressions.

drcMaximumY

Maximum global Y for the port (micron).
Look at drcMinimumY for an example that has global chip sizes and uses those values to define ports to be in a range. Type pdaExpression documentation:
Expression need to be commonly evaluated by many software, so having a restricted set of math / types and so on is key. In PDAFlow lib2/expr there is a yacc/lex parser available with some unit support as well as double / complex expressions. An alternative is tinyexpr, but this is more restrictive, so may be very unhandy for things like waveguide model expressions.

drcMinimumX

Minimum global Y for the port (micron).
Look at drcMinimumY for an example that has global chip sizes and uses those values to define ports to be in a range. Type pdaExpression documentation:
Expression need to be commonly evaluated by many software, so having a restricted set of math / types and so on is key. In PDAFlow lib2/expr there is a yacc/lex parser available with some unit support as well as double / complex expressions. An alternative is tinyexpr, but this is more restrictive, so may be very unhandy for things like waveguide model expressions.

drcMinimumY

Minimum global Y for the port (micron).

Use of locations like this is often harder to maintain then adding some applayer's - one for the boundary of the chip (for example called checkPortToBeHere) and one for the boundary view of the BB - just add some shape around the port in a applayer called thisIsThePortLocation and define in the layout a drcOverlapOf_A_by_B(thisIsThePortLocation,checkPortToBeHere) or something like that.

full file


 <!-- The die's [0,0] is in the center of the chip design area -->
 <global name="chipL" unit="um" doc="Define the chip design area - length">
   10000
 </global>
 <global name="chipW" unit="um" doc="Define the chip design area - width">
   6000
 </global>

<bb name="myBB">
 <port label="in0" org="true" refIn="true">
  <position>
   <x>0</x>
  </position>
  <!-- keep in0 inside the die, with a 200um zone -->
  <drcMinimumX>
   -0.5*chipL+200
  </drcMinimumX>
  <drcMaximumX>
   0.5*chipL-200
  </drcMaximumX>
  <drcMinimumY>
   -0.5*chipW+200
  </drcMinimumY>
  <drcMaximumY>
   0.5*chipL-200
  </drcMaximumY>
 </port>
</bb>

Type pdaExpression documentation:
Expression need to be commonly evaluated by many software, so having a restricted set of math / types and so on is key. In PDAFlow lib2/expr there is a yacc/lex parser available with some unit support as well as double / complex expressions. An alternative is tinyexpr, but this is more restrictive, so may be very unhandy for things like waveguide model expressions.

extend

Type AllowExtend documentation: Allows to extend with any (complex) data for enriching a design kit. The sub-data of an


        extend

will normally be vendor or provider specific, but may span multiple software vendors or suppliers.

Provider extensions can be references to (or embedded) reporting scripts or their versions; source database references and so on. Such data is helpful in cross-referencing production issues or differences between export snapshots. Embedding such data in the XML rather then side-files enhances tracebility and reduces errors.

Using this section is not considered part of the xPDK format therefore, but as long as the files validate with the Stichting PDAFlow Foundation schema's, it is not considered a (not allowed) Derivative version.
For conventions, please check also Extensions.
See also xPDK License.

label

This defines the name for a port, which is typically shown in the GUI software as a simple text label on the ports (or locations of them). Type pdaIdentifier documentation:
Identifiers are used in the Python library for the getName() and


        setName()

function and can thus be used to identify the different elements in list s.
In text the specification is a letter, followed by letters, numbers, underscore. The XSD schema validation is a regular expression: [A-Za-z]([A-Za-z0-9_])*

org

Defines (if set to true) that this port is explicitly the typically implicitly defined 'org' port. Therefore all coordinates are relative to this port.
Per building block, only a single port can be org="true" and to reduce ambiquousness, it is recommended to explicitly define the origin, in particular when using the polygon boundary option.

portMapToName

Type portMapToName documentation: or something like that - it is a ml::setPort(this: label -> this@portMapToName );

position

Define the port position relative to the org port, which can be implicit or explictly defined

full file


<bb name="myGratingCoupler">
 <port label="in0"> <!-- standard optical names -->
   <domain>Optical</domain>
   <direction>In</direction>
   <doc>Input side (chip)</doc>
   <position>
    <x>0</x>
   </position>
 </port>
 <port label="out0">
   <domain>Optical</domain>
   <direction>Out</direction>
   <doc>Output side (oriented off-chip)</doc>
   <position>
    <x>30</x><y>0</y>
    <z>1</z>          <!-- bit upwards compared to waveguide -->
    <angle>0</angle>  <!-- straight on-->
    <pitch>10</pitch> <!-- off-chip fiber angle -->
    <roll>0</roll>    <!-- we do not rotate the fiber -->
   </position>
 </port>
</bb>

Type pdaPosition3D documentation: in 3D, but as chip design needs only x & y and less angles only the x is required. The x, y and z are in micron, while the angles angle, pitch and roll are in degrees.

The x & y locations are for 2D / chip design.
The z coordinate is mostly oriented at Assembly Design Kits (ADK) but if different layer stacks are used on chip (regrowth, etching) it provides for vertical in-chip coupling.
The angle is the rotation in x/y plane and often used in all-angle photonics chip design.
The pitch is the angle off-chip and for chip design mostly for vertical fiber/chip coupling.
The roll is oriented at Assembly Design Kits (ADK) and not needed in chip design kits (PDK).

radius

This is the "logical" radius for the port as measured compared to the port location; a bended waveguide has different inner and outer radius, so port location inside the waveguide matters for this value.
Use "0" for straight waveguides and/or do not list.

The waveguide/port bend radius is measured with respect to the geometrical waveguide center (in the case of most common symmetric waveguides).

full file


<bb name="myBB">
 <port label="in0">
   <width unit="um" min="2" max="100000">5</width>
   <radius unit="um" min="5" max="100000">50</radius>
  </port>
</bb>

Type pdaValue documentation: none, and value is the expression in the content. The difference with attributes is that they are more like annotation; basically key/value string to add more information in a software specified way.

refIn

Define that this port is the default 'input' for follow up connections via OptoDesigner's "last" connectivity which simplifies the typical chain of elements a lot.
Per building block, only a single port can be refIn="true"

full file


<bb name="myBB">
 <port label="in0" org="true" refIn="true">
  <position>
   <x>0</x>
  </position>
 </port>
 <port label="out0" refOut="true">
  <position>
   <x>20</x>
  </position>
 </port>
</bb>

refOut

Define that this port is the default 'output' for follow up connections via OptoDesigner's "last" connectivity which simplifies the typical chain of elements a lot.
Per building block, only a single port can be refIn="true"

full file


<bb name="myBB">
 <port label="in0" org="true" refIn="true">
  <position>
   <x>0</x>
  </position>
 </port>
 <port label="out0" refOut="true">
  <position>
   <x>20</x>
  </position>
 </port>
</bb>

refport

Define the port position to be relative to another port of this BB. Default is "org" which is normally not explicitly defined, unless you use the "boundary" with a "rectangle" style.

full file


<bb name="myBB1to3">
 <port label="in0" org="true">
  <position>
   <x>0</x>
  </position>
 </port>
 <port label="mid" refport="in0">
  <domain>Geometric</domain>
  <position>
   <x>10</x>  <!-- becomes x=10 -->
  </position>
 </port>
 <port label="out0" refport="mid">
  <position>
   <x>10</x>  <!-- becomes x=20 -->
  </position>
 </port>
 <port label="out1" refport="out0">
  <position>
   <x>0</x>  <!-- stays x=20 -->
   <y>-10</y>
  </position>
 </port>
 <port label="out2" refport="out0">
  <position>
   <x>0</x>  <!-- stays x=20 -->
   <y>10</y>
  </position>
 </port>
</bb>

Type pdaPortReference documentation:

tex

In addition to the shorter doc this field can be used to write more details in Latex format, for example to describe the type of driving signals, spectral aspects and so on. This information can be used for design manuals as well as online help. Type pdaTexDocumentation documentation: doc , but tex can be a long text in LaTex format to document the layer in more detail if needed.

You can document anything relevant for the topic you want to define.

Multiple paragraphs is fine. Format is Latex, so more complex content is possible.

width

This is the "logical" width for the port, not the width of each related GDS/Oasis layer as due to mcs widen/shrink operations these can differ.

full file


<bb name="myBB">
 <port label="in0">
   <width unit="um" min="2" max="100000">5</width>
   <radius unit="um" min="5" max="100000">50</radius>
  </port>
</bb>

xsection

This value is optional as the BB may support a xsection-list (eg waveguide). For BBs which which are only for a single xsection it is better to explicitly define it per port.

full file


<xsection name="WG"/>

<bb name="myBB">
 <port label="in0">
    <xsection>WG</xsection>
  </port>
</bb>

Type pdaXsectionReference documentation: