xPDK BB - 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>

license

Specify license information if it differs from the PDK license scope.
This is typically not needed, but in some cases there may be IP restrictions from other parties involved or sub-licensing/restrictions for using this building block.
XSD(license):
Define license information. 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 etc.
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>

library

The library defines a BB-grouping, see GUI.
XSD(library):
    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>

version

The version tag defines the BB version, which can be different from the PDK version. If it is the same, best leave the it out.
XSD(version):
Version information.

The version can be defined as:
  • major.minor
    this is the short-hand version number. This can be a YYYY.MM (year.month) value also.
  • major.minor.patch
    adds the patch to indicate small changes. This can be a YYYY.MM.DD (year.month.day) value also.
  • major.minor.patch.iteration
    where the iteration is often relating to a (software) implementation and thus less typical in PDK or BB versions. It can be useful in the compact model files to indicate that the same measurements or simulations have received a new model instance.
full file
<bb name="myBB">
 <version>1.0.0</version>
</bb>

boundary

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

Ports

These 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>

Parameters

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">
  <parameters>
   <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="CurrentDensity" 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>
  </parameters>
 </bb>
XSD(parameters):
  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.
  

locals

Local variables are handy to shrink long equations, they can use the globals and parameters as well as locals that are defined before them. Using locals is also a way to shrink expression size by having shortened names for a parameter as is shown in the example below. The OnTheOutsideIamLong will be visible in the software, while in for example a boundary you can use i.
Another typical use is conversion from arguments in degrees to radian or the sine/cosine etc of that, so you avoid errors in long expressions with many brackets.
full file

<bb name="myParam">
  <parameters>
   <parameter name="OnTheOutsideIamLong" min="1"> 5.0 </parameter>
   <parameter name="SomeAngle" unit="degree"> 45 </parameter>
  </parameters>
  <locals>
   <local name="i">OnTheOutsideIamLong</local>
   <local name="ca">cos(rad(SomeAngle))</local>
   <local name="sa">sin(rad(SomeAngle))</local>
  </locals>
 </bb>
XSD(locals):
  Optional local variables and attributes, mainly handy to define intermediate values based
  on the arguments. Locals are not visible from outside (in the software) or by the designer.
  The locals are evaluated from top to bottom and can combine the parameters, the globals as
  well as earlier defined locals.

  Attributes are key/value pairs that are intended mostly as flags in the software. They are defined in
  the PDAFlow API and are intended for software internal use. Aspects like "being default" or "not yet placed"
  as well as "schematic versus layout mismatch" type of attributes can be aligned on between software
  vendors to support designers further.
  

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.

full file
<bb name="myBB_0">
 <drcManhattan>true</drcManhattan>
</bb>

<bb name="myBB_1">
 <drcXaligned>true</drcXaligned>
</bb>

<bb name="myBB_2">
 <drcXaligned>true</drcXaligned>
</bb>

<bb name="myBB_3">
 <drcAngles>45.0 135.0 225.0 315.0</drcAngles>
</bb>
XSD(drcManhattan):
     Shortened notation for drcAngles 0 90 180 270
     
XSD(drcXaligned):
     Shortened notation for drcAngles 0 180
     
XSD(drcYaligned):
     Shortened notation for drcAngles 90 270
     
XSD(drcAngles):
      Space seperated list of allowed global angles (in degrees) for the complete BB.
      

xsection

Defines a valid xsection for the BB, you can define a series of them.
Some building blocks like straight waveguides can be used in different xsection so if you do not want to make many copies in the design kit, 1 per waveguide, dc & rf track and so on, you can use this field. 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.
In case only a single xsection is allowed, typical for active elements like SOAs, then you should not use this field, but define all ports 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>
XSD(xsection):
Defines a valid xsection for the BB.

Some BBs can be used in multiple xsections, typical 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.

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 pdaflow/lib2/expr library.

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>
XSD(doc):
   Document anything relevant for the topic you want to define.
   
  Multiple paragraphs is fine. Format is plain text.
  
XSD(tex):
  Document anything relevant for the topic you want to define.
  
  Multiple paragraphs is fine. Format is Latex, so more complex content is possible.
  

Building block type

The BBtype tag defines applicable compact simulation models. This table is stored in a seperate XML file and/or can be included in the BB file itself.
XSD(BBtype):
    Optional type information that links to the compact model table.

    The type is an identifier to simplify cross-references.
    
full file
  <!-- Include the compact model list to ensure correct references.
   -->
  <xi:include href="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
  <BBtype name="waveguide">

    <ModelName name="beta" >
     <software app="PICWave"      version=">=2020.00" />
     <software app="OptoDesigner" version=">=2020.00" />
     <software app="VPI"          version=">=2020.00" />
     <doc>Beta via xsection, so width, radius, wavelength, ... dependent</doc>
     <parameter name="Wavelength" unit="um" />
     <parameter name="Width"      unit="um" />
     <parameter name="Radius"     unit="um" />
     <parameter name="Temperature" unit="C" />
    </ModelName>

    <ModelName name="loss" unit="dB" >
      <parameter name="Wavelength" unit="um" />
    </ModelName>

    <ModelName name="coolnessFactor" />

  </BBtype>

  <BBtype name="soa">

    <ModelName name="loss" unit="dB" >
      <parameter name="Wavelength" unit="um" />
    </ModelName>

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

  </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.

The full CSM file is xPDK_CompactModel_List.xml which has XSD: xPDK_CompactModel_List.xsd.

This file contains a list of Supported BB Compact Simulation Models (CSMs) with names:

spt

Use the spt 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.

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