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
port
s 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
<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>
Design information
In addition to the locations & type, we need for photonics more things. Basic aspect isxsection
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
Forport
s 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.
<xsection name="WG"/>
<bb name="myBB">
<port label="in0">
<drcAngles>0 45 90 135 180</drcAngles>
<drcMinimumX>200</drcMinimumX>
<drcMaximumY>400</drcMaximumY>
</port>
</bb>
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.
<port 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
</port>
XSD The schema file can be downloaded or viewed at xPDK_BB.
Details
WaiveReport
Type WaiveReport documentation: Waive an issue in the Report.htmldirection
<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>
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 whenlabel
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.
<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>
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
<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>
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.
<globals>
<!-- 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>
</globals>
<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>
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
<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>
- 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).
<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>
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"
<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"
<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.
<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>
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.
<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.
<xsection name="WG"/>
<bb name="myBB">
<port label="in0">
<xsection>WG</xsection>
</port>
</bb>