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

<bb name="myBB">
<library>Basic components/demo</library>
<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>
</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: drcManhattan, drcXaligned, drcYaligned, drcAngles

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>


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

<bb  exportclass="..."  name="..." ... > ...
<SpecView> ... </SpecView>   list
<bbtype> ... </bbtype>    optional
<boundary> ... </boundary>   list
<changelog> ... </changelog>   list
<doc> ... </doc>    optional
<drcAngles> ... </drcAngles>    optional
<drcManhattan> ... </drcManhattan>    optional
<drcXaligned> ... </drcXaligned>    optional
<drcYaligned> ... </drcYaligned>    optional
<icon> ... </icon>    optional
<lastChangedDate> ... </lastChangedDate>    optional
<library> ... </library>    optional
<locals> ... </locals>   list
<od_spt> ... </od_spt>    optional
<parameter> ... </parameter>   list
<port> ... </port>   list
<tex> ... </tex>    optional
<version> ... </version>    optional
<view> ... </view>   list
<xsection> ... </xsection>   list
</bb>

### XSD

The schema file can be downloaded or viewed at xPDK_BB.

## Details

### SpecView

Type pdaSpecView documentation: Defines a (short) basic specification for a building block, 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.

### 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
  <!-- 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


<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="um" />
<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="um" />
<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="um" />
<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="um" />
<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="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 pdaIdentifier documentation: Defines a valid name for an identifier.

Identifiers are used in the Python library for the getName() and setName() function and can thus be used to identify the different elements in lists.
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_])*

### 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: Annotate the topview with different aspects. The typical 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.

### 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: Trace changes to the data.
This is time-stamped change 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.

### doc

Type pdaDocumentation documentation: Document anything relevant for the topic you want to define.

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.

### drcAngles

Space seperated list of allowed global angles (in degrees) for the complete BB. Type pdaDoubleList documentation: Define a list of (space seperated) double inside a single text (attribute or element).

### drcManhattan

Shortened notation for drcAngles 0 90 180 270

### drcXaligned

Shortened notation for drcAngles 0 180

### drcYaligned

Shortened notation for drcAngles 90 270

### 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" devicetype="source">
</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: This section allows to add your own field or attributes.

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.

### icon

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

<bb name="myIcon1" devicetype="amplifier">
<icon> <!-- this data is not actually a PNG ! -->
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" devicetype="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: Define a picture. The picture can be provided as embedded (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>


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


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.

### 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">
<parameter name="OnTheOutsideIamLong" min="1"> 5.0 </parameter>
<parameter name="SomeAngle" unit="degree"> 45 </parameter>
<locals>
<local name="i">OnTheOutsideIamLong</local>
</locals>
</bb>

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

### name

Type pdaIdentifier documentation: Defines a valid name for an identifier.

Identifiers are used in the Python library for the getName() and setName() function and can thus be used to identify the different elements in lists.
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_])*

### od_spt

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_spt>
ml::Straight(cin-> this@in0:wfix(1),20) elm;
this{"elm"}=elm;
this{"L"}=20;
</od_spt>
</bb>

Type od_VendorExtension documentation:

### 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: Create a named value with expression / type support.

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

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.

### tex

Type pdaTexDocumentation documentation: As 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

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: 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.
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: Optional pda::View implementations; in the pdaConfig.xsd/cc 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: