bbWaveguide

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.

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.

<bbWaveguide  
pdaBBdefinition:LayoutInterfaceArguments="..."  pdaBBdefinition:LayoutInterfaceBB="..."  pdaBBdefinition:LayoutInterfaceCondition="..."  pdaBBdefinition:LayoutInterfacePriority="..."  pdaBBdefinition:bbStyle="..."  pdaBBdefinition:busConfigArguments="..."  pdaBBdefinition:busConfigElement="..."  pdaBBdefinition:dmPictSize="..."  pdaBBdefinition:exportclass="..."  pdaBBdefinition:mcsWrapper="..."  pdaBBdefinition:name="..."  pdaBBdefinition:noParameterRangeTest="..."  pdaBBdefinition:pcellFail="..."  pdaBBdefinition:portMapDC="..."  pdaBBdefinition:portMapDCi="..."  pdaBBdefinition:portMapDCo="..."  pdaBBdefinition:portMapIn="..."  pdaBBdefinition:portMapOut="..."  pdaBBdefinition:portMapRF="..."  pdaBBdefinition:portMapRFi="..."  pdaBBdefinition:portMapRFo="..."  pdaBBdefinition:symbolLibName="..."  pdaBBdefinition:symbolView="..."  pdaBBdefinition:symbolViewReorderPorts="..."  pdaBBdefinition:symbolViewTemplate="..." ... > ...
  <pdaBBdefinition:DesignRule> ... </DesignRule>   list
  <pdaBBdefinition:GuiView> ... </GuiView>   list
  <pdaBBdefinition:SpecView> ... </SpecView>   list
  <pdaBBdefinition:WaiveReport> ... </WaiveReport>   list   optional
  <pdaBBdefinition:align> ... </align>    optional
  <pdaBBdefinition:attribute> ... </attribute>   list
  <pdaBBdefinition:bbAnnotateFontSize> ... </bbAnnotateFontSize>    optional
  <pdaBBdefinition:bbAnnotateName> ... </bbAnnotateName>    optional
  <pdaBBdefinition:bbFlexWrapper> ... </bbFlexWrapper>   list   optional
  <pdaBBdefinition:bbWrapper> ... </bbWrapper>   list   optional
  <pdaBBdefinition:bbtype> ... </bbtype>    optional
  <pdaBBdefinition:boundary> ... </boundary>   list
  <pdaBBdefinition:changelog> ... </changelog>   list
  <pdaBBdefinition:doc> ... </doc>    optional
  <pdaBBdefinition:groupRef> ... </groupRef>   list
  <pdaBBdefinition:icon> ... </icon>    optional
  <pdaBBdefinition:lastChangedDate> ... </lastChangedDate>    optional
  <pdaBBdefinition:library> ... </library>    optional
  <pdaBBdefinition:license> ... </license>    optional
  <pdaBBdefinition:local> ... </local>   list
  <pdaBBdefinition:parameter> ... </parameter>   list
  <pdaBBdefinition:port> ... </port>   list
  <pdaBBdefinition:pxFactory> ... </pxFactory>   list   optional
  <pdaBBdefinition:sptFooter> ... </sptFooter>    optional
  <pdaBBdefinition:sptHeader> ... </sptHeader>    optional
  <pdaBBdefinition:tex> ... </tex>    optional
  <pdaBBdefinition:ticket> ... </ticket>   list
  <pdaBBdefinition:version> ... </version>    optional
  <pdaBBdefinition:view> ... </view>   list
  <pdaBBdefinition:xsection> ... </xsection>   list
</bbWaveguide>

XSD

The schema file can be downloaded or viewed at xPDK_BB.

Details

Type pdaBBdefinition

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.

DesignRule

Define a 'meta rule', so non-geometric. Type pdaDrcGeneralRule documentation: Define a design rule that is not layer or "polygon" / "geometric" based.
Design rules are available in different flavors, some of which can not be associated with layers; for example the name of the GDS cell that is required to be used for the design.
The rule is described in text and software may (or not) be able to implement them. Using the rule field gives designers an easy way to find more information on the DRC fail if it appears.

GuiView

Type pdaGuiView documentation: be have some additional remarks / special conditions. This field allows to define this.

LayoutInterfaceArguments

Type LayoutInterfaceArguments documentation: See also od:busConfigArguments for context; the epLayoutInterface resembles the od:BusConfig but is defined for Python.

LayoutInterfaceBB

Type LayoutInterfaceBB documentation: Define the BB mappings in the wxcfg class. It is ok to have multiple PDK elements map to the same wpcfg instance, for example depending on the wavelength band which is selected. The LayoutInterfaceCondition can then be used to select which version to pick, where the first is selected. Order is determined by LayoutInterfacePriority, highest is last.

LayoutInterfaceCondition

Type LayoutInterfaceCondition documentation: Set the selection mechanism for a multi-BB mapping. This can be as function call etc but then it should be somewhat language independent, so do not use self.X() but X() in python. The xsl code can prefix it with a class/instance scope.
You can use a reference to the technology definition, as tech.X(), for example for band-selection or enabled processes.

LayoutInterfacePriority

Type LayoutInterfacePriority documentation: Set the selection priority for a multi-BB mapping, lowest value is first.

SpecView

Type pdaSpecView documentation: for example a modulation depth or maximum modulation speed of a modulator. These are just for quick information for users. Typical values are insertion loss, modulation speed and so on.

WaiveReport

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

align

Building block placement validation.

This group is oriented at crystal / wafer alignment as for some BBs (like SOA and EAM) performance depends on crystalline alignment. Type pdaBBplacement documentation: Space seperated list of allowed global angles (in degrees) for the complete BB.

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.

bbAnnotateFontSize

Type bbAnnotateFontSize documentation:

bbAnnotateName

Type bbAnnotateName documentation:

bbFlexWrapper

Type bbFlexWrapper documentation: Define Flex-wrapper.
The BB's flex-wrapper is used for standardizing the port names (mask::setLayoutPort()) so we can use them consistently in the bus-routers, back-annotation of layouts back into schematic (for pose-layout simulation).

bbStyle

This attribute can be used to mark a BB as whitebox; if not set to that value, a graybox (or blackbox) style should be used by the software.
Type pdaBoxStyle documentation:

bbWrapper

Type bbWrapper documentation: Define that this BB replaces another one.
Due to PDK changes, older BBs may need migration to new ones. Using this field allows to define at the definition of the new BB the mapping from the old one. You can change parameters and ports.
Remove the old BB from the PDK, a new definition will be added which gives the replace by.. type of message on its use. This allows designers to quickly migrate their design.
You can use the optional (plain) text content for additional information.

bbtype

Optional type information that links to the compact model table. The type is an identifier to simplify cross-references.
This field defines applicable compact simulation models. This table is stored in a seperate XML file and/or can be included in the BB file itself.
full file
 </doc>
  <!-- Include the compact model list to ensure correct references.
   -->
  <xi:include href="http://www.pdaflow.org/xpdk/docu/examples/xPDK_CompactModel_List.xml" parse="xml"/>

<bb name="mySOA">
  <bbtype>soa</bbtype>
</bb>
The value is a string that links to something like:
full file

  <license>
  Stichting PDAFlow Foundation.

  See http://www.pdaflow.org/xpdk_license.php.
  </license>

  <version>2022.12</version>


  <modeltype name="EMPTY">
   <doc>
    Tag an empty model.

    This tells that the model is not yet implemented, but may be so in the future.
   </doc>
  </modeltype>


  <modeltype name="RAW_SMATRIX">
   <doc>
    Raw s-matrix data in abs2 / phase combination.
   </doc>
    <parameter name="Wavelength" unit="nm" />
    <property name="abs2" unit="none">Define the power transmission.</property>
    <property name="phase" unit="radian">Define the phase of the transmission.</property>
  </modeltype>

  <modeltype name="CML">
   <doc>
    Compact Model definition.

    The values are single item, either double or complex.
   </doc>
  </modeltype>

  <!-- To be defined.
    -->

   <modeltype name="LOSS_MATRIX">
   <doc>
    Loss (in dB)
   </doc>
    <parameter name="Wavelength" unit="nm" />
    <property name="value" unit="dB">Define the power loss.</property>
  </modeltype>


  <modeltype name="LOSS_PER_LENGTH_MATRIX">
   <doc>
    Loss (in dB/cm) for waveguides.
   </doc>
    <parameter name="Wavelength" unit="nm" />
    <property name="value" unit="dB/cm">Define the power loss per length.</property>
  </modeltype>


  <modeltype name="BETA_MATRIX">
   <doc>
    Beta via xsection, so width, radius, wavelength, ... dependent
   </doc>
     <parameter name="Wavelength" unit="nm" />
     <parameter name="Width"      unit="um" />
     <parameter name="Radius"     unit="um" />
     <parameter name="Temperature" unit="C" />

    <property name="re" unit="none">Define real part.</property>
    <property name="im" unit="none">Define imaginary part.</property>
  </modeltype>


    <!-- To be defined.
    -->

  <bbtype name="passive">
    <ModelName name="transfer" modeltype="RAW_SMATRIX"/>
    <ModelName name="loss" modeltype="LOSS_MATRIX" />
  </bbtype>

  <bbtype name="transition">
    <ModelName name="transfer" modeltype="RAW_SMATRIX"/>
    <ModelName name="loss" modeltype="LOSS_MATRIX" />
  </bbtype>

  <bbtype name="coupler">
    <doc>
    Passive components.

    This is normally defined with a S-matrix style transfer function and
    optional group delay or optical path length.
    </doc>

    <ModelName name="transfer" modeltype="RAW_SMATRIX" />
  </bbtype>



  <bbtype name="waveguide"> <!-- use waveguide or curve? -->
    <doc>
    Waveguide models.

    These are mode-based models.
    </doc>

    <ModelName name="transfer" modeltype="RAW_SMATRIX" />
    <ModelName name="loss" modeltype="LOSS_PER_LENGTH_MATRIX" />
    <ModelName name="beta" modeltype="BETA_MATRIX" />
  </bbtype>



  <!-- To be defined.
    -->

  <bbtype name="soa">
   <doc>
   Optical amplifier.

   This type is rather complicated - many modelling aspects.
   </doc>

   <ModelName name="loss" modeltype="LOSS_MATRIX" />

    <ModelName name="gain" modeltype="LOSS_PER_LENGTH_MATRIX">
      <parameter name="current" unit="mA" />
    </ModelName>

  </bbtype>


  <bbtype name="eam">
   <doc>
   Electro-absorption modulator.

   This type is rather complicated - many modelling aspects.
   </doc>
   <ModelName name="loss" modeltype="LOSS_MATRIX" />
  </bbtype>


which defines the compact models (CSM). This is likely to be defined between multiple foundry and software and thus not defined in the BB file itself, but xi:include in the BB file via:
<xi:include href="xPDK_CompactModel_List.xml" parse="xml" />
as shown.
Type pdaIdentifierExtended documentation:
Those names are mostly XML scope and thus for readability support more general naming then the pdaIdentifier.

boundary

The boundary field is for mask layout as well as on-screen display to avoid overlapping elements. Different shapes are available.
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>
Type pdaBoundaryView documentation: 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.

busConfigArguments

Type busConfigArguments documentation: The OptoDesigner bus-router simplifies complex (delay based) routing. It needs a few different BBs to be setup per PDK, which can be generic waveguide curves also.
For the argument/order you can look in the /*default:*/ below, which shows the curve that is used if you do not overrule it. wwg is the configured waveguide width for the bus.
 // create straight in some way, must support a port/port spec via L=null
 abstract layout straight(double L nullable UnitInfo "micron") TexDoc "Create a straight waveguide";
    /*default:*/ ml::Straight( cin->this@in0,cout->this@out0 : wfix(wwg), L == null?null:max(0,L));

 // create taper in some way, L=null allows sub-class to spec it
 abstract layout taperToBus(double win UnitInfo "micron",double L nullable UnitInfo "micron") TexDoc "Width taper";
    /*default:*/ ml::Straight( cin->this@in0,cout->this@out0 : wlin(win,wwg), L);

 // create taper in some way, L=null allows sub-class to spec it
 abstract layout taperFromBus(double wto UnitInfo "micron",double L nullable UnitInfo "micron") TexDoc "Width taper";
    /*default:*/ ml::Straight( cin->this@in0,cout->this@out0 : wlin(wwg,wto), L);

 // create 90deg bend in some way
 abstract layout bend90(int up RangeSpec[-2,2]) TexDoc "Manhattan bend style";
    /*default:*/ ml::BendPolar( cin->this@in0,cout->this@out0 : wfix(wwg), wwr, up*90);

 // create some bend
 abstract layout bend(double r UnitInfo "micron",double a UnitInfo "Degree") TexDoc "General bend";
    /*default:*/ ml::BendPolar( cin->this@in0,cout->this@out0 : wfix(wwg),r,a);
 

The string data is the argument for the PDK bb element based on the mapping from above. In addition to the (very few) arguments of the layout's above, you can use:
 final function getWidth()  TexDoc "Return width"
final function getRadius() TexDoc "Return radius"
final function getDistance() TexDoc "Return wg/wg distance"
final function getDistanceCenterCenter() TexDoc "Center - center distance of 2 waveguides"
final function getTaperAngle() TexDoc "Return default angle for tapers"

For the busConfigElement arguments: L,win,wbus

busConfigElement

Type busConfigElement documentation:

changelog

Track changes to building blocks.
It is recommended for BB suppliers (foundry, design house, software, designer, ...) to track what changes over type in the definition. This helps in migrating designs to newer design kits, see what changed by designers and so on.
It is not required to do so.
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.

dmPictSize

Type dmPictSize documentation: Specify picture size (sml, mid, big) or use \sizepict{..} or something like that. It specifies the size of the BB picture in the design manual.

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.

exportclass

Export control & library

This element in the BB can be used for export control as some combinations need (legal) validation.
Without this attribute it is assumed to be a passive component.
full file

<bb name="myBB2" exportclass="source">
  <library>Advanced components/Using parameters</library>
</bb>
Type pdaDeviceType documentation: This information is intented for export control as some combinations of BBs need legal validation. Design software can validate the devicetype combinations that are used in the design and report on possible export regulations.

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.

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 or dot. The XSD schema validation is a regular expression: [A-Za-z]([A-Za-z0-9_])*

icon

Icon’s can be fully embedded as base64 encoded data. This avoids the need for external file references.
full file

<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>
Using files is possible also as shown with the filename statement. And calling some (software specific) functions can also be defined.
full file

<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>
The resolution of pictures should be high enough to allow good scaling in schematic designs. As such SVG is preferred.

Note: Pictures do not need to be square as for some BBs it is nicer using rectangular shapes.
Note: To keep the files “human editable” also, it is probably a good idea to have big pictures not embedded in the file, but referenced.
Type pdaPicture documentation: (use file) or file reference (so external file, use reffile) and for some software via function calls (use function).

lastChangedDate

This date allows a foundry to define the date that the BB really changed, so things like new layout, changes in layer stack and so on. Doing new measurements is not part of this.

The date is specified in the following form "YYYY-MM-DD" where:
YYYY indicates the year
MM indicates the month
DD indicates the day

library

The library defines a BB-grouping.

Defines the location in an library / element tree. In OptoDesigner it is used as dlgname and thus populates the Element dialog.
full file
<bb name="myBB">
 <library>Basic components/demo</library>
</bb>

license

Specify license information if it differs from the PDK license scope.

This is typically not needed, but in some cases providers there may be IP restrictions from other parties involved or sub-licensing/restrictions for using this building block.
full file
<bb name="myBB">
 <license>This deviates from the PDAFlow one for the example; - it requires a patent license
    or a reference to PDAFlow's website in an article.
 </license>
</bb>
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.

local

Type pdaNamedValue documentation:

mcsWrapper

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

name

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 or dot. The XSD schema validation is a regular expression: [A-Za-z]([A-Za-z0-9_])*

noParameterRangeTest

Type noParameterRangeTest documentation: This provides for a convenient non-default value testing also, however it may be that those parameter combinations are not valid. Per parameter the min/max may work, but it can be that the minimum of one parameter requires a non-default value for another one.
Setting this property in the BB definition allows to define such a test pattern, for now this is not yet used, so any string is fine.

parameter

List of parameters (can be empty).

Parameters are named-values and can have an unit, type and value. The value is defined via an expression.
Parameters / globals and locals share the same style. A BB defining parameters with different constraints is shown here. It does not add the other information from the previous example to keep it focussed.
full file

<bb name="myParam">
   <parameter name="MinL" min="1" unit="um"> 5.0 </parameter>
   <parameter name="MaxL" max="100"> 5.0 </parameter>
   <parameter name="RangeL" min="1" max="100"> 5.0 </parameter>
   <parameter name="IntSet" type="int" unit="kA/cm^2" allowedValues="1 2 5 6 10">5</parameter>
   <parameter name="StringSet" type="string" allowedValues="a1 b2 c5 6 10">c5</parameter>
   <parameter name="ang" doc="This is the center angle of something" unit="degree" min="0" max="5">3.0</parameter>
 </bb>
Type pdaNamedValue documentation:

pcellFail

Type pcellFail documentation: This pcell fails in OptoCompiler PyCell; reason is listed in the string.
The BB definition needs to be fixed.

port

Ports define the connection points, see port definition.
full file

<bb name="myBB_0">
  <!-- very basic definition! -->
  <port label="in0" org="true"/>
  <port label="out0"/>
  <port label="out1"/>
</bb>

Type pdaPortDefinition documentation: 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.

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.

pxFactory

Type pxFactory documentation: Define a pxFactory map.
See OptoDesigner documentation.

sptFooter

Type sptFooter documentation: This section will be put at the end of a definition via XSLT.

Tech/02 definition

This section is copied into the '02' file just before the function export()
The typical use is for backward compatability (for example mapping older mcs names) or some custom tech functions that need access to most of the tech-file.
Using this element instead of the TechFooter is easier in case of enriching the design kit via the C++ or Python library.

pdaSingleLayerOPS

This section is copied into the '02' file below the (gds/mcs) layer definitions in the single-layer operation block. It is intended for more complex single/multi layer derived operations or DRC.

Download the xsl/xml/xsd's and run the (bash) command line below to convert the XML to a SPT example in OptoDesigner (see short docu):

xsltproc --xinclude -stringparam standalone true -stringparam example drc0 xPDK_toOptoDesigner02.xsl layer_singleSpt.xml
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="100" G="200" B="255"/>
    <visible>true</visible>
    <fillstyle>open</fillstyle>
    <linestyle>fill</linestyle>
  </layer>
  <layer name="layer2">
    <gds_number>2</gds_number>
    <gds_datatype>0</gds_datatype>
    <grid>0.001</grid>
    <purpose>Waveguide layer</purpose>
    <color R="255" G="20" B="20"/>
    <visible>true</visible>
    <fillstyle>open</fillstyle>
    <linestyle>fill</linestyle>
    <SingleLayerOps>
      <od_sptFooter>
      // println("hi");
    </od_sptFooter>
    </SingleLayerOps>
  </layer>
Spt:

xsection

This section is copied into the '02' file below the mcs definition and is intended for more complex properties like waveguide models and so on.
It provides also for less common mcsSet*() functions or feeding them with values that xPDK does not support.
full file

 <xsection name="WG">
  <od_sptHeader>// This section does some special OptoDesigner things.
   mcsSetCurveCheck();
   mcsSetAltWG("WGhigh","WGlow");
  </od_sptHeader>
 </xsection>

BB definition

This section is copied into the '04' file inside the layout definition and is intended for fine-tuning behavior, giving control over returned attributes and so on. In typical cases it is not needed.
Use this field in case the xPDK format does not have all the fields you need for your BB in OptoDesigner. For example this is possible for returning more layout attributes or supporting more complex design rule checking.

full file
<bb name="myBB">
 <port label="in0">
  <position>
     <x>0</x>
  </position>
 </port>
 <od_sptFooter>
  ml::Straight(cin-> this@in0:wfix(1),20) elm;
  this{"elm"}=elm;
  this{"L"}=20;
 </od_sptFooter>
</bb>

BB boundary

This section is copied into the '04' file into the layout itself and can be used to mark up complex boundaries. Also the use of multiple mcs/gds layers for DRC can be simpler this way.
Instead of using spt, you can also use the xsection for typical cases and reduce vendor dependence for this section.
full file

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

sptHeader

Type sptHeader documentation: This section will be put at the start of a definition via XSLT.

Tech/02 definition

This section is copied into the '02' file at the start of the TechnologyPDKLIB class instance.
The typical use is waveguide mode models and other bigger spt sections that can then be used in the different sections.

pdaSingleLayerOPS

This section is copied into the '02' file below the (gds/mcs) layer definitions in the single-layer operation block. It is intended for more complex single/multi layer derived operations or DRC.

Download the xsl/xml/xsd's and run the (bash) command line below to convert the XML to a SPT example in OptoDesigner (see short docu):

xsltproc --xinclude -stringparam standalone true -stringparam example drc0 xPDK_toOptoDesigner02.xsl layer_singleSpt.xml
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="100" G="200" B="255"/>
    <visible>true</visible>
    <fillstyle>open</fillstyle>
    <linestyle>fill</linestyle>
  </layer>
  <layer name="layer2">
    <gds_number>2</gds_number>
    <gds_datatype>0</gds_datatype>
    <grid>0.001</grid>
    <purpose>Waveguide layer</purpose>
    <color R="255" G="20" B="20"/>
    <visible>true</visible>
    <fillstyle>open</fillstyle>
    <linestyle>fill</linestyle>
    <SingleLayerOps>
      <od_sptFooter>
      // println("hi");
    </od_sptFooter>
    </SingleLayerOps>
  </layer>
Spt:

xsection

This section is copied into the '02' file below the mcs definition and is intended for more complex properties like waveguide models and so on.
It provides also for less common mcsSet*() functions or feeding them with values that xPDK does not support.
full file

 <xsection name="WG">
  <od_sptHeader>// This section does some special OptoDesigner things.
   mcsSetCurveCheck();
   mcsSetAltWG("WGhigh","WGlow");
  </od_sptHeader>
 </xsection>

BB definition

This section is copied into the '04' file inside the layout definition and is intended for fine-tuning behavior, giving control over returned attributes and so on. In typical cases it is not needed.
Use this field in case the xPDK format does not have all the fields you need for your BB in OptoDesigner. For example this is possible for returning more layout attributes or supporting more complex design rule checking.

full file
<bb name="myBB">
 <port label="in0">
  <position>
     <x>0</x>
  </position>
 </port>
 <od_sptFooter>
  ml::Straight(cin-> this@in0:wfix(1),20) elm;
  this{"elm"}=elm;
  this{"L"}=20;
 </od_sptFooter>
</bb>

BB boundary

This section is copied into the '04' file into the layout itself and can be used to mark up complex boundaries. Also the use of multiple mcs/gds layers for DRC can be simpler this way.
Instead of using spt, you can also use the xsection for typical cases and reduce vendor dependence for this section.
full file

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

symbolLibName

Type symbolLibName documentation: Define the library to copy the symbol view from.
See symbolView.

symbolView

Type symbolView documentation: Define the symbol view to copy.
For pcells it is handy to start with an existing symbol view in the OA database. Using an existing view saves errors and makes life easier. The default library to search in is the photonicLib; you can use the symbolLibName to select another library. Another option is to use the symbolViewTemplate field to create a symbol view based on a template.

symbolViewReorderPorts

Type symbolViewReorderPorts documentation:

symbolViewTemplate

Type symbolViewTemplate documentation: Define the symbol view to use as basis.
When using this field, the OptoCompiler PDK will use this shape as template and generate the symbol based on the pre-defined template. This is an alternative of using the symbolView use.

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.

ticket

Type pdaTicket documentation:

version

Optional version information.

To get an idea of the maturity of the BB design, you can add a lastChangedDate in the BB definition. It does not imply that it needs to have run on many wafers since that change. Another option to show this is the use of the version tag.
full file

<bb name="myDate">
  <lastChangedDate>2022-04-29</lastChangedDate>
  <version>1.2.3</version>
</bb>
This tag defines the BB version, which can be different from the PDK version. If it is the same, best leave it out.
full file
<bb name="myBB">
 <version>1.0.0</version>
</bb>
Type pdaVersion documentation:
The version can be defined as: A major number change indicates something big changed, while the minor is for more incremental changes. The patch indicates normally small data updates like new measurements.

view

General Views

Instead of defining a lot of somewhat hard-coded / fixed “views” on the “BB”, the PDAFlow concept of having BB's & View’s can be used also.
full file

 <bb name="myViews">
 <!-- 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>
   <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>

Note To keep the files “human editable” also, it is probably a good idea to have big simulation files not embedded in the file, but referenced, like xPDK Simulation

So allowing multiple “view”s - one that references side files and one that has it embedded can make life easier later on when the files are likely generated fully.

Having the option to add views is maybe not needed in combination with foundry / vendor extensions, but if we can use the same view by multiple parties, it saves effort and then makes sense to incorporate.
Type pdaView documentation: code this is handled with the object factories to automatically add them.

Views are defined in PDAFlow1 as C++ objects that can be created via an object factory. They can have arguments of any type, but not sub-views.
The idea of a view is to look at a building block / component in a flexible way, the view uses the information from the actual BB instance in a defined way; this can be things like layout, simulation as well as user interface aspects like icons, library references and so on.

xsection

Defines a valid xsection for the BB, you can define a series of them.

Some building blocks can be used in multiple xsections, typical examples are (straight) waveguides. Instead of defining many of these, one per xsection, it is easier to define one that allows to be defined in multiple xsections. List each of the allowed xsections in the BB section.
Consider for example an advanced SOI technology with 4 waveguide styles, 4 metal layers and 2 RF tracks - that would give 10 myStraight_<X>, which makes the library very big and unclear.

All port's of such a BB will be implicitly defined to be that xsection, unless defined in the port itself. Such an overrule is likely in things like TOPM's where the waveguide is for example DEEP/SHALLOW, but the electrical contact pads are allways DC.

BBs that support multiple xsections make life also much easier in more complex composites as you do not need to multiply your own library also. It may requires xsection dependent equations (things like phase, neff) which can be done easily via the xPDK expr library.

In case only a single xsection is allowed, typical for active elements like SOAs, then you should not use this field, but define all portbb_port's completely.
full file
 <!-- Local tech file, eg. from summary -->
 <xsection name="Waveguide"/>
 <xsection name="Metal1"/>
 <xsection name="Metal2"/>

<bb name="myBB">
  <port label="in0">
   <domain>Optical</domain>
   <position>
     <x>0</x>
   </position>
   <!-- always the same -->
   <xsection>Waveguide</xsection>
 </port>
 <port label="dc0">
   <domain>DC</domain>
 </port>
 <port label="dc1">
   <domain>DC</domain>
 </port>
 <!-- dc0 and dc1 can be one of the following -->
 <xsection>Metal1</xsection>
 <xsection>Metal2</xsection>
</bb>
Type pdaXsectionReference documentation: