xPDK_Simulation

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 This information is needed to ensure correct references within a building block model file.

Structure

The attributes and elements are shown below, in a sorted per type fashion.
In case a list is printed after an element, it indicates that you can have many, otherwise it should be a single element. With a optional it tells the element is not required.

<xPDK_Simulation  xPDK_Header:pdk_name="..." ... > ...
  <bb> ... </bb>
  <changelog> ... </changelog>   list
  <database> ... </database>    optional
  <model> ... </model>   list
  <pdk_version> ... </pdk_version>    optional
  <timestamp> ... </timestamp>    optional
  <xPDK_CompactModel_List> ... </xPDK_CompactModel_List>    optional
  <xPDK_Header:attribute> ... </attribute>   list
  <xPDK_Header:doc> ... </doc>   list
  <xPDK_Header:global> ... </global>   list
  <xPDK_Header:groupRef> ... </groupRef>   list
  <xPDK_Header:license> ... </license>    optional
  <xPDK_Header:mpw_run> ... </mpw_run>   list
  <xPDK_Header:provider> ... </provider>    optional
  <xPDK_Header:tex> ... </tex>   list
  <xPDK_Header:version> ... </version>    optional
</xPDK_Simulation>

XSD

The schema file can be downloaded or viewed at xPDK_Simulation.

Details

Type xPDK_Header


Most is optional and extension capability is the idea.

bb

Define local BB to cross-reference ports/properties against.
Local definitions can be used instead of including the full xPDK_BB.xml file and simplify the model development by design kit developers as the key information is defined locally. The alternative is to xinclude the full design kit itself and working with a few files.
This information for this section can be extracted using xsl/xPDK_BB_to_Simulation.xsl from the full xPDK_BB.xml file. Type pdaBBdefinition documentation: BB definitions including ports, parameters, attributes and views.

Basic fields

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

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

 <port label="in0">
   <domain>Optical</domain>
   <position> <!-- units for x,y,z: um; for angle,pitch,roll: degree -->
     <x>0</x><y>0</y>
     <angle>10</angle>
   </position>
   <width unit="um" min="2" max="100000">5</width>
   <radius unit="um" min="5" max="100000">50</radius>
 </port>
 <boundary>
   <rectangle portref="in0" width="10" length="20" x="0" y="0"/>
 </boundary>
</bb>

Documentation

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

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

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

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

Alignment

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

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

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

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

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

Check definition

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

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

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

from Geometry import Design
from pdk import *

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

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

changelog

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

database

This optional field is intended to define the reference(s) to data sources, for example measurement databases or file server directories. It can also have references to extraction script version / names and so on.
Its purpose is to be able to quickly find at a foundry or measurement group the scope of measurements and so on. It is therefore helpful in case data needs to be analyzed in more detail after the design kits have been send out for model creation by software vendors. Type pdaDatabaseReference documentation:

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.

model

Just s-matrix style model now, either as table or as series of functions. Type pdaModel documentation: Define a circuit model for a BB. The basic idea is to check the ports and parameters against the definition and thus have this meta data either in the file or included.

pdk_version

A single design kit version can be specified here. It is strongly recommended (but not required) to be able to check consistency of the files over time. 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.

timestamp

This optional field is intended to define the time of writing the file. This allows model creators to validate that the data is new or old. This helps in quickly scanning a design kit for model updates and helps in validating existing models against updates of data.

xPDK_CompactModel_List

Type xPDK_CompactModel_List documentation: This section in a xPDK extends from xPDK_Header.

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

attribute

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

doc

Type pdaDocumentation documentation:
This field allows some (short, few lines) documentation to be written. It can be a long string, but the idea is not to replace a design manual.
This fields is like tex which allows documentation in LaTex format; doc is restricted to plain text.

global

Type pdaNamedValue documentation:

groupRef

Type pdaIdentifier documentation:
Identifiers are used in the Python library for the getName() and setName() function and can thus be used to identify the different elements in list s.
In text the specification is a letter, followed by letters, numbers, underscore or dot. The XSD schema validation is a regular expression: [A-Za-z]([A-Za-z0-9_])*

license

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

mpw_run

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

pdk_name

under the same provider name.

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

provider

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

tex

Type pdaTexDocumentation documentation: doc , but tex can be a long text in LaTex format to document the layer in more detail if needed.

You can document anything relevant for the topic you want to define.

Multiple paragraphs is fine. Format is Latex, so more complex content is possible.

version

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