pdaNetlist
  Structure
  Details

---

pdaBBdefinition:exportclass=.. name=..
  <bb_connect> ...  -tp->
  <bb_instance> ...  -tp->
  <designkit> ...  -tp->
  <extport> ...  -tp->
  <model> ...  -tp->
  <pdaBBdefinition:SpecView> ...  -tp->
  <pdaBBdefinition:bbtype> ...  -tp->
  <pdaBBdefinition:boundary> ...  -tp->
  <pdaBBdefinition:changelog> ...  -tp->
  <pdaBBdefinition:doc> ...  -tp->
  <pdaBBdefinition:drcAngles> ...  -tp->
  <pdaBBdefinition:drcManhattan> ...  -tp->
  <pdaBBdefinition:drcXaligned> ...  -tp->
  <pdaBBdefinition:drcYaligned> ...  -tp->
  <pdaBBdefinition:icon> ...  -tp->
  <pdaBBdefinition:lastChangedDate> ...  -tp->
  <pdaBBdefinition:library> ...  -tp->
  <pdaBBdefinition:license> ...  -tp->
  <pdaBBdefinition:locals> ...  -tp->
  <pdaBBdefinition:od_spt> ...  -tp->
  <pdaBBdefinition:parameter> ...  -tp->
  <pdaBBdefinition:port> ...  -tp->
  <pdaBBdefinition:tex> ...  -tp->
  <pdaBBdefinition:version> ...  -tp->
  <pdaBBdefinition:view> ...  -tp->
  <pdaBBdefinition:xsection> ...  -tp->

pdaNetlist

Define a flat netlist.

The flat netlist is a series of BBs or other netlist instances. Each of these can have its parameter values changed but it is not required to set all of them.
These instances are connected via the bb_connect's or to the external ports of the netlist via the extport.

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.

---

<netlist  pdaBBdefinition:exportclass="..."  pdaBBdefinition:name="..." ... > ...
  <bb_connect> ... </bb_connect>   list
  <bb_instance> ... </bb_instance>   list
  <designkit> ... </designkit>
  <extport> ... </extport>   list
  <model> ... </model>   list
  <pdaBBdefinition:SpecView> ... </SpecView>   list
  <pdaBBdefinition:bbtype> ... </bbtype>    optional
  <pdaBBdefinition:boundary> ... </boundary>   list
  <pdaBBdefinition:changelog> ... </changelog>   list
  <pdaBBdefinition:doc> ... </doc>    optional
  <pdaBBdefinition:drcAngles> ... </drcAngles>    optional
  <pdaBBdefinition:drcManhattan> ... </drcManhattan>    optional
  <pdaBBdefinition:drcXaligned> ... </drcXaligned>    optional
  <pdaBBdefinition:drcYaligned> ... </drcYaligned>    optional
  <pdaBBdefinition:icon> ... </icon>    optional
  <pdaBBdefinition:lastChangedDate> ... </lastChangedDate>    optional
  <pdaBBdefinition:library> ... </library>    optional
  <pdaBBdefinition:license> ... </license>    optional
  <pdaBBdefinition:locals> ... </locals>   list
  <pdaBBdefinition:od_spt> ... </od_spt>    optional
  <pdaBBdefinition:parameter> ... </parameter>   list
  <pdaBBdefinition:port> ... </port>   list
  <pdaBBdefinition:tex> ... </tex>    optional
  <pdaBBdefinition:version> ... </version>    optional
  <pdaBBdefinition:view> ... </view>   list
  <pdaBBdefinition:xsection> ... </xsection>   list
</netlist>

---

XSD

The schema file can be downloaded or viewed at xPDK_Netlist.

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.

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.

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

bb_connect

Define a connection between bb_instances in this netlist. Type pdaBBconnect documentation: Defines a connection between a port on one BB instance to a port on another BB instance
The connection is "direct" in the sense that for the actual (mask) layout the two BBs are abutted - so the ports of both BBs connect exactly.
In a schematic view this is not needed, a (not optically / electrically) functional wire can be drawn between these to ports to show their connection.

bb_instance

This element defines the use of a design kit building block. Each instance should have a unique name and can be connected to others. Type pdaBBinstance documentation: BB instance in a netlist

designkit

A netlist can contain elements from different design kits, therefor we maintain a list of the sources. Type pdaDesignKit documentation: Define a series of BB sources.

The BB definitions are needed to validate the data in the netlist, so we use the xPDK_BB data for that. A netlist can be a mixed technology provider and/or design house and/or software library.
The technology providers are typically:

• Wafer foundry - having a Process Design Kit (PDK)
• Assembly service - having an Assembly Design Kit (ADK)
• Test service - having an Test Design Kit (ADK)

From design houses and software partners there are typically also

• IP library: one or more BBs grouped in a design kit that add capabilities on top of the PDK / TDK / ADK.

For use in the netlist there are behaving in the same way, so we can combine them inside it.

extport

Link a bb_instance in the netlist to the outside; effectively this makes the netlist behave like a building block instance - however instead of being defined in a design kit, it is in the design or user library file. Type pdaExtPort documentation: Designates a port on a BB instance as an external netlist port - by which the netlist can be connected to other things e.g. other BBs/netlists

model

Define a model.

The optional model allows to the exchange of simulation or measurement data in addition to the schematic. This allows the flat netlist to be re-used in circuit simulation and thus act as user-created IP-library.
An alternative use-case is that a foundry provides such data for more complex sub-circuits like test-circuits or PCMs that are put on a wafer. This supports the validation of more complex circuits between foundry and software or design partners. Type xPDK_Simulation documentation: This section in a xPDK extends from xPDK_Header.

The xPDK circuit simulation section allows to define compact models for photonics. Such models can be described in formulas or data files.
The basic idea is to have one (or a few) files with model data per building block so it is easy to cross-reference data and keep all models synchronized.

The compact models can be defined in an included xPDK CompactModel List XML file and are thus external to the building block simulation data - this as the same models are shared between foundry and software partners.

The building block information can be

• summarized from a full xPDK BB file
  You can use the XSLT code for this.
• be XIncluded, so with a reference to the full data
• be fully embedded in the file
  This is easy to do with an XML processor that expands the XInclude section. The advantage of this is that you snap-shot the building block definition.
  xmllint --xinclude simIn.xml > simOut.xml
  will run this.

This information is needed to ensure correct references within a building block model file.

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. The value is a string that links to something like: 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.
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. 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.
See also xPDK License.

icon

Icon’s can be fully embedded as base64 encoded data. This avoids the need for external file references.
Using files is possible also as shown with the filename statement. And calling some (software specific) functions can also be defined. 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.

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. Type pdaLicense documentation: Define license information.

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

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

port

Ports define the connection points, see port definition. 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

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. 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.
This tag defines the BB version, which can be different from the PDK version. If it is the same, best leave it out. 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.

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