xPDK_BB

This section in a xPDK extends from
xPDK_Header.

This BB information contains the typical shared data between software: This information is needed in schematic design and circuit simulation as well as in layout.

This scope is therefore fairly broad and future extensions are likely to capture more information. The current common fields provide for a rich design kit already compared to other formats, while adressing different software.
Vendor extensions are supported in this section, so software specific details are possible therefore to tune behavior.

Extensive example

This example is part of the full file below. It is mostly listed here so you do not need to download it. It shows many fields and properties that can be defined and these are described in the child pages.
This file includes the technology file and adds the Met, Met1 and Met2 xsection's in the meta data to show both options work.

Use:
xmllint - -format - -xinclude - -schema xPDK_BB.xsd xPDK_BB.xml
to validate.
full file
  Demo Material
  </license>

 <doc>
  This file is a very cool one.
 </doc>

  <!-- triggers "duplicate glbA, glbB when using with the
       Python API.
    -->
 <global name="glbA" type="int"> 4 </global>
 <global name="glbB" type="double"> exp(glbA*3) </global>
  <!-- triggers "duplicate key-sequence" glbB
  <global name="glbB" type="double"/>exp(glbA*3)</global>
  -->

 <extend>
   <!-- Series of supplier extensions for supplier side for trace-ability.
  -->
  <foundryDatabase app="SQL" version="2.0.0">See ISO forms - software release documents</foundryDatabase>
  <foundryDatabase app="GUI" version="1.0.42">See ISO forms - software release documents</foundryDatabase>
  <foundryReporter waveguide_module="2.0.1">Loss, neff, groupindex</foundryReporter>
  <foundryReporter active_module="1.2.9">groupindex</foundryReporter>
  <labRuns>march-june 2021, december 2021-april 2022.</labRuns>
 </extend>

 <!-- Include the technology file to ensure correct references.
   -->
  <xi:include href="xPDK_Layout.xml" parse="xml"/>
  <!-- Include the compact model list to ensure correct references.
   -->
  <xi:include href="xPDK_CompactModel_List.xml" parse="xml"/>


 <!-- Some xsection's for port's that are not defined in the basic technology
    - file. Such a list can include parts of the technology file instead of
    - the full include.
    - Note - adding xsection's here that include GDS layer mapportgs is ok for
    - the XML, but you risk that the software that only uses the technology
    - file does not use all data.
    -->
 <xsection name="Met"/>
 <xsection name="Met1"/><xsection name="Met2"/>


 <!-- very simple BB -->
 <bb name="myBB">
  <library>Basic components/demo</library>
  <version>1.0</version>
  <!-- implicit layout ports, here just for testing the portref.
       comment when using the DemoPDK.
    -->
  <!--
  <port label="bil"/> <port label="bcl"/> <port label="bol"/>
  <port label="bic"/> <port label="bcc"/> <port label="boc"/>
  <port label="bir"/> <port label="bcr"/> <port label="bor"/>
  <port label="org"/>
  -->

  <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>
    <width unit="um" min="2" max="100000">5</width>
    <radius unit="um" min="5" max="100000">50</radius>
  </port>
  <boundary>
    <rectangle width="10" length="20" x="0" y="0"/>
  </boundary>
  <boundary>
    <rectangle portref="in0" width="1" length="2" x="5" y="0"/>
  </boundary>
 </bb>

 <bb name="myDate">
  <lastChangedDate>2022-04-29</lastChangedDate>
 </bb>

 <bb name="mySOA">
   <bbtype>SOA</bbtype>
 </bb>

 <bb name="myParam">
   <parameter name="MinL" type="int" min="1">5</parameter>
   <parameter name="MaxL" max="100"> 5.0 </parameter>
   <parameter name="RangeL" min="1" max="100"> 5.0 </parameter>
   <parameter name="IntSet" type="int" allowedValues="1 2 5 6 10">5</parameter>
   <parameter name="StringSet" type="string" allowedValues="a1 b2 c5 6 10">"c5"</parameter>
   <parameter name="noexpr" type="double" min="1"/>
 </bb>

 <bb name="myDoc">
   <doc>This is the short one.

    Can still span lines though.</doc>
   <tex>And here I go for some Tex docu like $\rightarrow$ or even \input{sub.tex}.

    Can be manu lines too.</tex>
 </bb>



 <!-- simple BB with multiple port & parameters -->
 <bb name="myBB1">
  <version>2.0</version>
  <doc>I am a really nice BB with 2 parameters</doc>
  <align style="Manhattan"/>
  <!-- implicit layout ports, here just for testing the portref. -->
  <port label="orgx"/>

   <parameter name="L"> 5.0 </parameter>
   <parameter name="IntSet" type="int" allowedValues="1 2 5 6 10">5</parameter>
   <parameter name="StringSet" type="string" allowedValues="a1 b2 c5 6 10">"c5"</parameter>

  <port label="in0">
    <domain>Optical</domain>
    <position> <!-- units for x,y,z: um; for angle,pitch,roll: degree -->
     <x doc="We are symmetric">0</x><y>0</y>
      <angle>10</angle>
    </position>
  </port>
  <port label="out0">
    <domain>Optical</domain>
    <position> <!-- units for x,y,z: um; for angle,pitch,roll: degree -->
      <x>L</x><y>0</y>
      <angle>0</angle>
    </position>
    <drcAngles>0 45 90 135 180</drcAngles>
  </port>
   <parameter name="Width" type="int" min="10" max="500"
          doc="The width is key for this BB">
    42
   </parameter>
   <local name="Length" min="0.5">
     3*Width+7.0
   </local>
 </bb>

 <bb name="myIcon1" exportclass="amplifier">
  <icon> <!-- this data is not actually a PNG ! -->
   <file format="png">4oVIUNDopNMHqhuzLaDOFXnzCT+cRkQM/NroSIdxnALeS1kYcYMKeRGrdRnc
yXtMtUAk6Xmnoje2X6EnYll/Zn0+GEfFl/6birD2W6ZVc3HhoRQ5Fnl8DObg
WhiGthy1dwNPhKULEzVoDEsffEilx1FfnRWaNSQr0sMfVPIUXH5Gpfb0+zvn
69+xutJmQa9cCrUgsNpYPQFZQLNj7B/gxzYywQHlNQPjO2OakXW7zruTfrgU
TYJlSTSmdJXwdBNN0Vbbn0giRM7RHDgJy/XA6Yvm2BIJci4K41fu+DEhtq+e
L8zzN6cDA6SzeOBcSDd4LWf6nvdmKdX9tIBw5zPlDO+kFSg/ldUPiSJG5udy
PnoaiBfw6faCyV3lTMD13w+HR0EUZCYWF+pu5swDlYstQidbSO59isRQsi7j
+VZb+D/l8SI0JpB2HCpw97gePmXuVKIKuXKmfpOqSWC9nSRlc1qm+++m270p
b2sdpETAstnriFLgcn98jrvKzbCQPRyLJteBzqBOyIaTe50zcDjwENSoVTzI
gwquDVYndjqZIR/ZrcCG7R3ic0LqFzuznQB0BIFN3sbBaVwquCS5Fd9vr0hp
96HXjpSz3NQouc5fMYPYcwK2QU1m+w5L/e5DFqLzbTpbWKO2MvGz5tlPuqoR
1hi7iZHduuKAwyba1acptLGw9zp6ZmtSFaqWKHHcQFV2Uu+vFnM24lunQHW/
VfpLIx5joVsncxfVDYbDcqlffKM3RmszKIt/NRVRbNwKTRteO3EhE4SrRKNi
FX19GlCWXz9vjqFDBvq4cRf+4XLG6IHk6lLxo6QY4zzRNo1p</file>
  </icon>
 </bb>

 <bb name="myIcon2" exportclass="amplifier">
  <icon>
   <!-- use fixed files -->
   <filename format="png">icon.png</filename>
   <filename format="svg">icon.svg</filename>
   <!-- call some drawing code, specific per software -->
   <function trigger="onChange">
      <software app="Software1" version="1.0.0"/>
      <code>call_something_to_draw();</code>
   </function>
   <function trigger="onUpdate">
      <software app="Software2" version="1.0.0"/>
      <code>
       n=Shape()
       n.draw_me()
      </code>
     </function>
  </icon>
 </bb>

 <!-- more content in BB -->
 <bb name="myBB2" exportclass="source">
  <library>Advanced components/Using parameters</library>
  <version>1.0.0</version>
  <icon>
   <!-- call some drawing code, specific per software -->
   <function trigger="onChange">
      <software app="Software1" version="1.0.0"/>
      <code>call_something_to_draw();</code>
   </function>
   <function trigger="onUpdate">
      <software app="Software2" version="1.0.0"/>
      <code>
       n=Shape()
       n.draw_me()
      </code>
     </function>
  </icon>
  <port label="out0">
    <domain>Optical</domain>
    <position>
      <x>0</x><y>0</y>
      <angle>10</angle>
    </position>
    <drcMinimumX>200</drcMinimumX>
    <drcMaximumY>400</drcMaximumY>
  </port>
  <port label="out1" refport="out0">
    <domain>Optical</domain>
    <position>
      <x>0</x><y>0</y>
      <angle>10</angle>
    </position>
    <drcMinimumX>200</drcMinimumX>
    <drcMaximumY>400</drcMaximumY>
  </port>
  <port label="rf0">
    <domain>RF</domain>
    <position>
      <x>100</x><y>200+myLength/2</y>
      <angle>10+sqrt(Length)</angle>
    </position>
  </port>
   <parameter name="myWidth" type="int" min="10" max="500"
          doc="The width is key for this BB">42
   </parameter>
   <parameter name="myLength" min="0.5"> 3*2.+7.0 </parameter>
   <parameter name="Length"   min="0.5"> 3*2.+7.0 </parameter>
   <parameter name="myPos" type="point" unit="um"
          doc="A location is a 2 value expression">
     [ 3*2.+7.0 , sqrt(4.0) ]
   </parameter>
   <attribute key="justStarted">InitialStage</attribute>
   <attribute key="pleaseDoSomeGUIplacement"/>
  <!-- PDAFlow views. The code in PDAFlow allocates the views & sets parameters.
       Here just arbitrary names and values.
  -->
  <view name="pdaLayoutView">
     <parameter name="myWidth" type="int"> 42 </parameter>
  </view>
  <view name="pdaModelView">
    <parameter name="myNeff" type="double"> 1.0/myWidth </parameter>
  </view>
  <view name="pdaModelReference">
    <parameter name="ref" type="string"> "WaveguideModel" </parameter>
  </view>
  <!-- Some specialized views -->
  <SpecView name="loss">5 dB/cm</SpecView>
  <SpecView name="maturity">very high</SpecView>

  <boundary>
   <polygon>
   <point x="0" y="-myWidth/2"/>
   <point x="myLength" y="-myWidth/2"/>
   <point x="myLength" y="myWidth/2"/>
   <point x="0" y="myWidth/2"/>
   </polygon>
  </boundary>
 </bb>

 <bb name="myStraight">
   <parameter name="Width" type="int" min="10" max="500"
          doc="The width is key for this BB"> 42 </parameter>
   <parameter name="Length" min="0.5"> 3*1.0+7.0 </parameter>

     <xsection>WG</xsection>
     <xsection>Met</xsection>
  <port label="in0" org="true">
    <domain>Optical</domain>
  </port>
 </bb>

 <!-- simple BB with multiple port & parameters -->
 <bb name="myBB3">
  <version>2.0</version>
  <doc>I am a really nice BB with 2 parameters</doc>
  <align style="Manhattan"/>
  <port label="in0">
    <domain>Optical</domain>
    <position>
      <x>0</x><y>0</y>
      <angle>10</angle>
    </position>
     <xsection>WG</xsection>
  </port>
  <port label="out0">
    <domain>Optical</domain>
    <position>
      <x>Length</x> <y>0</y>
      <angle>0</angle>
    </position>
    <drcAngles>0 45 90 135 180</drcAngles>
  </port>

   <port label="out1">
    <domain>Optical</domain>
    <position>
      <x>Length</x> <y>0</y>
      <angle>0</angle>
    </position>
    <drcAngles>0 45 90 135 180</drcAngles>
  </port>

   <parameter name="Width" type="int" min="10" max="500"
          doc="The width is key for this BB"> 42 </parameter>
   <parameter name="Length" min="0.5"> 3*1.0+7.0 </parameter>
   <!-- gives Duplicate key-sequence ['Length'] - ->
   <parameter name="Length" min="0.5">3*W+7.0</parameter>-->
   <local name="xlW" type="int" min="10" max="500"
          doc="The width is key for this BB">42
   </local>
   <local name="xlL" min="0.5">3*Width+7.0</local>
   <!-- gives Duplicate key-sequence ['xlL'] - ->
   <local name="xlL" min="0.5">3*Width+7.0</local> -->
  <boundary>
    <rectangle width="10" length="20"/>
  </boundary>
  <boundary purpose="metal">
    <rectangle portref="in0" width="4" length="2"/>
  </boundary>
  <boundary purpose="metal">
    <rectangle portref="out0" align="boc" width="4" length="2"/>
  </boundary>
  <boundary purpose="metal">
    <circle portref="out0" align="bcc" radius="42.24" y="10"/>
     <xsection>Doc</xsection>
  </boundary>
  <boundary purpose="metal">
    <od:sptHeader> ml::Straight(cin->[0] : );
    </od:sptHeader>
  </boundary>
  <boundary purpose="waveguide">
    <circle portref="out0" align="bcc" radius="42.24" y="10"/>
     <xsection>WG</xsection>
  </boundary>
 </bb>


  <!-- simple BB with multiple port & defaults xsection -->
 <bb name="myBB_manyport">
  <xsection>Met</xsection>
  <xsection>WG</xsection>
  <port label="in0"/>
  <port label="out0"/>
  <port label="rf0"/>
  <port label="rf1"/>
 </bb>

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.

<xPDK_BB  generateDRC="..."  generateDerived="..."  generateLVS="..."  portMapDC="..."  portMapDCi="..."  portMapDCo="..."  portMapIn="..."  portMapOut="..."  portMapRF="..."  portMapRFi="..."  portMapRFo="..."  xPDK_Header:pdk_name="..." ... > ...
  <bb> ... </bb>   list
  <bbAnnotateFontSize> ... </bbAnnotateFontSize>    optional
  <bbAnnotateName> ... </bbAnnotateName>    optional
  <bbLaser> ... </bbLaser>   list
  <bbModulator> ... </bbModulator>   list
  <bbPIN> ... </bbPIN>   list
  <bbPassive> ... </bbPassive>   list
  <bbSOA> ... </bbSOA>   list
  <bbTransition> ... </bbTransition>   list
  <bbWaveguide> ... </bbWaveguide>   list
  <changelog> ... </changelog>   list
  <feature> ... </feature>   list   optional
  <group> ... </group>   list   optional
  <run_name> ... </run_name>   list
  <software> ... </software>   list   optional
  <ticket> ... </ticket>   list
  <xPDK_CompactModel_List> ... </xPDK_CompactModel_List>   list
  <xPDK_Layout> ... </xPDK_Layout>   list
  <xsection> ... </xsection>   list
  <xPDK_Header:MRL> ... </MRL>    optional
  <xPDK_Header:TRL> ... </TRL>    optional
  <xPDK_Header:attribute> ... </attribute>   list
  <xPDK_Header:doc> ... </doc>   list
  <xPDK_Header:global> ... </global>   list
  <xPDK_Header:groupRef> ... </groupRef>   list
  <xPDK_Header:license> ... </license>    optional
  <xPDK_Header:mpw_run> ... </mpw_run>   list
  <xPDK_Header:provider> ... </provider>    optional
  <xPDK_Header:tex> ... </tex>   list
  <xPDK_Header:version> ... </version>    optional
</xPDK_BB>

XSD

The schema file can be downloaded or viewed at xPDK_BB.

Details

Type xPDK_Header


Most is optional and extension capability is the idea.

bb

Define a series of building blocks, sometimes called cell or pcell also (EDA terminology).
This section is used by both layout and schematic / circuit oriented software to allow designers to create their circuits. In general it does not make sense to have design kits without BBs in there. However it is not a required to have them - there are gds layer / process only design kits also.
It is possible to use global variables defined in layout.xml in the expressions here, for example to set default waveguide widths. For example:
layout.xml:
0.9
bb.xml:

wgWidth

full file
<bb name="myBB_0">
 <!-- put real definitions in here - see other sections. -->
</bb>

<bb name="myBB_1">
 <!-- put real definitions in here - see other sections. -->
</bb>
Type pdaBBdefinition documentation: BB definitions including ports, parameters, attributes and views.

Basic fields

The following example shows the basic information that is expected (but not required). With this content you can start using it in different software. It does not define parameters, so it is a fixed design.
Normally BB's have more ports as well as parameters, so a "real" BB will be longer.
full file

<bb name="myBB">
 <library>Basic components/demo</library>
 <license>Just the PDAFlow one</license>
 <version>1.0.0</version>

 <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>
   <width unit="um" min="2" max="100000">5</width>
   <radius unit="um" min="5" max="100000">50</radius>
 </port>
 <boundary>
   <rectangle portref="in0" width="10" length="20" x="0" y="0"/>
 </boundary>
</bb>

Documentation

Adding documentation is easy also, the doc is used by more software then the tex. tex is for long pieces of text like full help pages.
full file

<bb name="myDoc">
   <doc>This is the short one.

    Can still span lines though.</doc>
   <tex>And here I go for some Tex docu like $\rightarrow$ or even \input{sub.tex}.

    Can be many lines too.</tex>
 </bb>

Alignment

A building block can be validated on angle - this is using the "org" port as coordinate reference.
You can select one of the following options: Manhattan, Xaligned, Yaligned, Angles as a series of values
Note that the global position of this is relevant; if you use the BB in your library and thus create a design hierarchy, the (relative) location inside the library netlist/component is not relevant.

full file
<bb name="myBB_0">
 <align style="Manhattan"/>
</bb>

<bb name="myBB_1">
 <align style="Xaligned"/>
</bb>

<bb name="myBB_2">
 <align style="Yaligned"/>
</bb>

<bb name="myBB_3">
 <align style="Angles">45.0 135.0 225.0 315.0</align>
</bb>

Check definition

The xPDK format allows many aspects to be defined. To check that you defined it correctly, you can use the xsl files that convert the definition to the software of your choice.
A basic option is to use the gdspy project. The xsl/xPDK_toPython.xsl can use this library to generate the basic curves / black box designs. You can convert the BB.xml (as that includes the Layout.xml) in a simple script to generate a pdk.py.

xmllint --xinclude BB.xml | xmlstarlet tr $XPDK/xsl/xPDK_toPython.xsl -s pdkiteration=0 -s whitebox='nocell' > export/pdk.py

This (large) python file uses the xPDK Geometry.py and gdspy code jointly to allow the different boundary views, port locations and so on to be written to a GDS file or shown on screen.
Suppose you want to test the definition of a BB called myBB that has a paramter Length. Create a test.py with the following content:

from Geometry import Design
from pdk import *

myDesign=Design('/tmp/myBB.gds')
t=myBB()
t.Length=10
e0=t.place(myDesign,"element0",org=[0])
#e0.print_boundary()
t.Length=20
e1=t.place(dp,bir=e0.bol)
#e1.print_boundary()
#myDesign.draw_gdspy() # Just generate GDS
myDesign.draw_gdspy(show=True) # Show on screen
myDesign.write()

This should place two myBB's on the design, one with Length=10 and one with Length=20. The GDS file will depend on the type of BB (whitebox or not) and the -s whitebox='nocell' command line option. For black-box and grey-box BBs you should see two GDS cells, one per parameter setting.

bbAnnotateFontSize

Type bbAnnotateFontSize documentation:

bbAnnotateName

Type bbAnnotateName documentation:

bbLaser

Type bbLaser documentation: Laser.
This group defines the BBs that convert electrical power to optical signal, normally with II/VI or III/V materials. Typically they contain an bbSOA. The main difference is that some reflection mechanism is used on both sides which changes behavior a lot. Therefore the lasers are normally defined with a single optical output.

bbModulator

Type bbModulator documentation: Electro/thermo optical component (or other domain that modifies optical properties like chemical sensors or mechanical switches).
This group defines the BBs that have some non-optical influence that impacts the optical performance of the underlying m * n port component. Typical BBs are electro optic and thermo optic modulators which add to the 2 optical ports the 2 electrical ports. For the amount of electrical ports the speed is sometimes relevant too - for high speed (RF) often balanced or g/s/g ports are configured.

bbPIN

Type bbPIN documentation: Detector.
This group defines the BBs that provide optical to electrical conversion. This can be full power capture (so 1 optical in) or more like a power monitor that leaves most of the power going through (so 1 optical in, 1 out).
For electrical signal the amount of ports depends normally on "DC" or "RF" style speeds.

bbPassive

Type bbPassive documentation: This group is for passive component - until we have a better name.
This includes couplers, splitters, mode filters and so on. So any m * n port BB that has no driving / steering conditions (apart from maybe some thermal tuning for stability).

bbSOA

Type bbSOA documentation: Optical gain block.
This group defines the BBs that provide optical gain, normally by driving it electrical in II/VI or III/V materials. They tend to have 2 optical ports (in / out) and one or more electrical driving ports, depending on the substrate style - if the substrate is ground, then 1 electrical driving port can be enough allthough in practice multiple "electrical source ports" are sometimes used also to give better gain uniformity.

bbTransition

Type bbTransition documentation: This group is for waveguide transitions.
Transitions are often fixed components - no parameters. They have the optical input in 1 xsection and the optical output in another one.

bbWaveguide

Type bbWaveguide documentation: This group is for waveguides.
The waveguides can be any routing shape, so we consider the straight waveguides as well as the arc, sine, cosine and euler bends all to be waveguides. But also things like "inbetween" connectors. A combination of waveguide segments like an arc/line/arc could be defined as waveguide.
Waveguides have an optical in and out. Sometimes they are thermally tuned, so having more ports is fine.

changelog

Type xPDK_ChangeLog documentation: list, which can be empty. Software or design kit providers are not required to fill this data when changes are made, but it can help users to see what changed over time.

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.

feature

Type feature documentation: Define the features that are availble for use with this PDK in the given software.
This information is used in the design manual creation but can be embedded in the software specific design kit also.

generateDRC

Type generateDRC documentation: Specify that the DRC layer operations in the tech-file should be converted to ICValidator deck.

generateDerived

Type generateDerived documentation: Specify that the derived layer operations in the tech-file should be converted to ICValidator deck.

generateLVS

Type generateLVS documentation: Specify that an LVS deck should be generated for ICValidator.

group

Type group documentation: Define a PDK-group.
The PDK-groups can be used to structure information independent of the scope of the data. You can for example define a 'waveguide' group that contains layers, xsections and drc-rules.
The content in this field is in LaTeX format and (name) sorted item-lists are added before this text is put in the design manual. Those are defined as: xpdkGroupList'name''type', so you can use it inside the tex-text.
Here 'type' is one of:

portMapDC

Type portMapDC documentation: Use the port label or label_rev to pick the direction; do not add numbers.

portMapDCi

Type portMapDCi documentation: Use the port label or label_rev to pick the direction; do not add numbers.

portMapDCo

Type portMapDCo documentation: Use the port label or label_rev to pick the direction; do not add numbers.

portMapIn

Type portMapIn documentation: Use the port label or label_rev to pick the direction; do not add numbers.

portMapOut

Type portMapOut documentation: Use the port label or label_rev to pick the direction; do not add numbers.

portMapRF

Type portMapRF documentation: Use the port label or label_rev to pick the direction; do not add numbers.

portMapRFi

Type portMapRFi documentation: Use the port label or label_rev to pick the direction; do not add numbers.

portMapRFo

Type portMapRFo documentation: Use the port label or label_rev to pick the direction; do not add numbers.

run_name

Define the wafer runs (fab shuttles) names for which this PDK can be used. 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_])*

software

Type software documentation: Define the software versions to use with this PDK.
This information is used in the design manual creation but can be embedded in the software specific design kit also

ticket

Type pdaTicket documentation:

xPDK_CompactModel_List

Include the defined compact models for easy checks and/or define them locally.
Using the <xi:include ... /> is the preferred route as it allows to share the definition between design kits.
See building block type for the more details on what this section defines. The preferred route is to include such files rather then embedding them.
full file

 <!-- Include compact model file -->
 <xi:include href="xPDK_CompactModel_List.xml"/>
Type xPDK_CompactModel_List documentation: This section in a xPDK extends from xPDK_Header.

The Compact Model List file provides a table with building block types. Per building block type a list of models is defined that describes what type of (compact) model should be defined for a BB/Model definition file using the Circuit Simulation file.

xPDK_Layout

Include the technology file and/or define them locally.
Include a full technology file to avoid copy/paste errors and other data inconsistencies. See xPDK_Layout.xml for how to do this.

Define basic technology info.

The technology file contains the xsection information which is needed in the port to make sure the references are correct. To get this information, you can include a full technology file or just query the data using xsltproc and keep the (xs:include expanded) meta data file short.
full file

 <!-- Full tech file -->
 <xi:include href="xPDK_Layout.xml"/>

Technology file → summary

You can run the following to summarize a technology file for the (embedded or xs:include'd) xsection list.
xsltproc - -xinclude xPDK_xsection_list.xsl xPDK_Layout.xml
This should give the following output:
full file
The XSLT file can be downloaded: xPDK_xsection_list.xsl.
Type xPDK_Layout documentation: This section in a xPDK extends from xPDK_Header.

The layout section contains information for mask layout purposes as well as performing derived layer operations and (geometrical) design rule checking. It is therefore the key information for getting correct GDS files to a foundry.

Layer operations

The definition order in the XML file does not define the order of the operations to go from a schematic design (circuit or layout style) to the final GDS polygons, cells and other data in the GDS file. This would complicate the definition; instead the order of operations is defined by the following steps. The software writing the GDS is responsible for the correct order.

Derived layer operations

Derived layer operations are common in chip design to simplify work for designers and make their work more efficient and less error-prone. This holds for both single-layer and multi-layer operations.

The implementations of these operations vary strongly per software so efficiency (cpu, runtime, memory) will be different per software. In general a tool-specific set of operations can be much (> 10x) faster then a generic / converted deck and (optimal) runtime may easily be hours of wallclock-time, see also Design Rule Checking.

Multi-layer derived layers look like the single-layer operations, they mainly differ in the amount of layers that are used.
For the input of the operations there are two flavors - the named layers A, B and sometimes C. And the layer list via a list of layer fields. The first option is used if order of layers is relevant, for example in a layerAnotB. Changing the A & B layers will lead to very different results.

The layer-list is suitable in case many layers can be used and ordering is not important. This option like in layerIsCoveredBy do use a list of layers like in the Cover and In fields, which combine like an "or".

The output of the operation is (for derived layers) stored in the layer in which the operation was defined, this can be a gds layer or an applayer.
full file

<!-- some base layser -->
<layer name="layer1">
 <gds_number>0</gds_number> <gds_datatype>0</gds_datatype>
</layer>

<layer name="layer2">
 <gds_number>1</gds_number> <gds_datatype>0</gds_datatype>
</layer>

<layer name="layer3">
 <gds_number>2</gds_number> <gds_datatype>0</gds_datatype>
</layer>

<layer name="layer4">
 <gds_number>4</gds_number> <gds_datatype>0</gds_datatype>

  <layerAnotB A="layer1" B="layer3"/>

  <layerOr><layer>layer1</layer><layer>layer3</layer></layerOr>

  <layerAnd A="layer1" B="layer3"/>

  <layerXor A="layer1" B="layer3"/>
</layer>

<layer name="layerA0">
 <gds_number>0</gds_number> <gds_datatype>2</gds_datatype>
</layer>

<layer name="layerA1">
 <gds_number>0</gds_number> <gds_datatype>4</gds_datatype>

 <layerOffset>
   <doc>Some combined output</doc>
   <In>
     <layer>layer1</layer> <layer>layer2</layer> <layer>layerA0</layer>
   </In>
   <dist>2.0</dist>
 </layerOffset>

 <layerIsCoveredBy>
   <doc>Some combined output</doc>
   <Cover>
     <layer>layer1</layer> <layer>layer2</layer>
   </Cover>
   <In>
     <layer>layer1</layer> <layer>layer2</layer> <layer>layerA0</layer>
   </In>
   <how>partly_including</how>
 </layerIsCoveredBy>
</layer>

Derived layers (single & multiple) are often needed to be able do define DRC rules more precisely as they tend to have clauses like "if this & that, then the rule is so&so". This this&that and so&so are both often derived layers.

Some "single layer derived" layers are shown here.
full file

<layer name="layer1">
   <gds_number>1</gds_number>
   <gds_datatype>0</gds_datatype>
   <grid>0.001</grid>
   <purpose>Waveguide layer</purpose>
   <color R="10" G="20" B="30"/>
   <visible>true</visible>
   <fillstyle>NOFILL</fillstyle>
   <linestyle>fill</linestyle>
</layer>

<layer name="layer2">
  <gds_number>3</gds_number>
  <gds_datatype>8</gds_datatype>
  <grid>0.01</grid>
  <purpose>Deeper and deeper</purpose>
   <!-- not making sense, just to show the setuip  -->
    <layerSize extentSize="2.0" A="layer1">
     <msg>sizing</msg>
    </layerSize>
    <layerGrow growSize="2.0" A="layer1">
     <msg>grow</msg>
    </layerGrow>
    <layerShrink shrinkSize="2.0" A="layer1">
     <msg>shrinking</msg>
    </layerShrink>
</layer>
Here the layerGrow, layerSize and layerShrink fill up content in this layer from another one. The A-reference should be to a GDS layer.

Design rule checking

This section describes the geometric (layer) design rule checking options that operate on geometric data. Often you need to assemble a chain of derived layer operations to get the required rule check.
A simple example is a minimum width check - you can implement this by a "shrink, followed by a grow" and then do a layer overlap with the original to see if there is a difference (note: this is not a fast way and not recommended!).

The operation chain is often using intermediate layers that are not needed in the output files - hence the use of applayer to store such interim layers. Sometimes the operations are just needed on the input data - so it can be a puzzle to write a test down in geometric correct specifications.
A second complication is that different software implements the tests and boolean operations differently; so an optimal result (in cpu / runtime / memory) on one software may not be so on another one. It is therefore recommended to validate with software vendors to see that the layer-operation chain and design rule check is well defined.
In general the best option is to use as few layer operations as possible with as little layers as possible in the rule check, but there are clear and common exceptions to this.

To validate the rule is correctly implemented, it is recommended to make a test design per rule; such a design should contain one or more of the failing designs, a few just-passing designs and some designs with a clear pass. The amount of pass/fail tests depends on the complexity of the rule.
With OptoDesigner you can then validate the operations to get the correct amount of fails. Setting up the regressionstesting with autoxml then allows you to automate the testing during new releases, so you reduce much effort in maintenance on existing rules, while not risking operations in the layer-operation chain failing due to extending the DRC deck.

The (clock) runtime of larger DRC decks can be considerable, even for photonics designs which are mostly empty space on the chip compared to electronic designs. The difference between a well-written / tool-specific DRC deck and a xPDK_Layout converted version is likely to be very relevant to designers. First of all because the tool-specific deck can use more / faster operations then xPDK_Layout supports. And secondary because the optimal layer operation chain + rule validation is different per tool.
You may need to make the choice therefore between cost for designers versus cost for the foundry (DRC deck user versus provider).

In short - be careful with the layer operations to make sure your DRC deck runs fast enough. And talk with your software partners to implement rules.

A simple exapmle is shown here.
full file

<layer name="layer1">
   <gds_number>1</gds_number>
   <gds_datatype>0</gds_datatype>
   <purpose>Waveguide layer</purpose>
   <!-- DRC -->
     <drcConvex/>
     <drcMinSpace rule="R1" value="0.2"><doc>Min dist between gides</doc></drcMinSpace>
</layer>
That extends these a bit with more layer references and some more values.
full file

<!-- some base layser -->
<layer name="layer1">
 <gds_number>0</gds_number> <gds_datatype>0</gds_datatype>
  <drcNoOverlap drcExclude="layer3">
   <doc>Just a msg</doc>
  </drcNoOverlap>
</layer>

<layer name="layer2">
 <gds_number>1</gds_number> <gds_datatype>0</gds_datatype>
</layer>

<layer name="layer3">
 <gds_number>2</gds_number> <gds_datatype>0</gds_datatype>
</layer>

  <!-- Define multi-layer operations -->
  <drcA_NoOverlap_B rule="1" A="layer1" B="layer3" drcExclude="layer2">
   <msg>triple</msg>
   <doc>Do something more exclusive here?</doc>
  </drcA_NoOverlap_B>

  <drcMinSpacingA_to_B rule="2" A="layer1" B="layer3">
   <msg>Keep some distance</msg>
   <value>5</value>
  </drcMinSpacingA_to_B>

  <drcOverlapOf_A_by_B rule="3" A="layer1" B="layer2">
   <msg>Need some overlap</msg>
   <value unit="um">5</value>
  </drcOverlapOf_A_by_B>

OptoDesigner export

The xPDK_toOptoDesigner02.xsl used the information to convert a xPDK Layout file into a 02-file as part of the OptoDesigner design kit or a self contained example that can be used directly.
In the former case you should also convert a xPDK BB file into a 04-file and your layout-only design kit is ready (the xsl is not yet there).
For the latter case it provides an easy way to embed BB, DRC, ... test files and user examples inside the technology file so if the die-template, design rules, ... change you can easily re-generate an extensive set of test cases and user examples.

xsection

Define local xsection's which can be added to a technology file or be just the a sub-set of the technology file to reduce file size and make the files stand-alone.

You can copy the output of the summary generation into the XML file and/or define additional xsection. As only the name is needed, the list is short.
full file
 <!-- Local tech file, eg. from summary -->
 <xsection name="Waveguide"/>
 <xsection name="Metal1"/>
 <xsection name="Metal2"/>

Sometimes it is handy to add xsection's for port's that are not defined in the basic technology file. Such a list can include parts of the technology file instead of the full include.
Note - adding xsection's here that include GDS layer mapportgs is ok for the XML, but you risk that the software that only uses the technology file does not use all data.

Type pdaXsection documentation: properties.

Design layers which map via gridding onto GDS/Oasis/OpenAccess layers. xsection's provide for "optical" logic like default width, bend radius, coupling length and so on.
Each design layer can map to multipe GDS layers, so you can define a layer stack relating to a waveguide in a single definition.
Take for example a typical core, cladding and trench or some under/over etch compensation. This approach is not only suitable for photonics, but is practical in many technologies. The picture below shows a cross-section of a (printed) transistor.



Instead of writing in many GDS layers, you can simply use the xsection which represents OptoDesigner's mcs concept which is shown in the picture.

xsection

This defines a xsection which in EDA-design is often called a cad or design layer. In OptoDesigner this is a mcs. The xsection's define what the port should refer to. A xsection is normally something like a waveguide or metal track and is often using multiple (gds) layers.

Very basic definition.

full file
 <xsection name="WGbase">
  <purpose>Base waveguide</purpose>
 </xsection>
This definition is good for marking things up, but elements placed in this design layer will not go to a mask file.

Including GDS mapping and some properties

full file

<!-- define GDS layers for the <map> sections -->
<layer name="layer1">
 <gds_number>1</gds_number> <gds_datatype>0</gds_datatype>
</layer>

<layer name="layer2">
 <gds_number>2</gds_number> <gds_datatype>0</gds_datatype>
</layer>

<!-- define MCS layers -->
<xsection name="WG">
  <purpose type="active">Waveguide with grid</purpose>
  <grid>
   <map accuracy="0.1">layer1</map>
   <map widen="2">layer2</map>
  </grid>
  <xsSetWidth useDrc="false">0.5</xsSetWidth>
  <xsSetRadius min="100">200</xsSetRadius>
 </xsection>

 <xsection name="Doc">
  <purpose type="doc">Metal highlighting</purpose>
  <grid>
   <map accuracy="0.1">layer2</map>
   <map widen="2">layer2</map>
  </grid>
  <xsSetWidth useDrc="false">0.5</xsSetWidth>
  <xsSetRadius min="100">200</xsSetRadius>
 </xsection>

MRL

Type pdaMRL documentation: Manufacturing Readiness Level (MRL) as defined by the EU.

TRL

Type pdaTRL documentation: Technology Readiness Level (TRL) as defined by the EU.

attribute

Type pdaAttributeType documentation: and views with information that is likely to be software specific. So it is more a 'flag' then a value. The value is just a string and not something with an expression in it.

doc

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.

global

Type pdaNamedValue documentation:

groupRef

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_])*

license

Type pdaLicense documentation:
State the basic conditions of using the file and typically refer to legal documents.
License information should be compact enough to be clear as reference. The reference is expected to be to signed documents like Non Disclose Agreements (NDA) or service contracts and so on.

mpw_run

other data file can be applied. Type pdaMPWrun documentation: library.

pdk_name

under the same provider name.

The pdk_name at the start (just below the xsi:noNamespaceSchemaLocation defines the design kit name and is intended as a relatively short name. It should be unique enough to avoid confusion by designers. Type pdaPDKname documentation: general then the pdaIdentifier.
In text this is a letter or number, followed by letters, numbers or underscore. The check is regular expression: [A-Za-z0-9]([A-Za-z0-9_])*

provider

Type pdaProvider documentation: provider, so a full company or institute name for example, instead of the smaller pdk_name.

tex

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.

version

version numbers helps to keep track of which files to use. Type pdaVersion documentation: