openEPDA uPDK ™ Blocks - Version 0.2

This page contains specification for the uPDK ™ block description standard. For general information about uPDK including the licensing terms, see openEPDA uPDK ™ Blocks.

General format info

The standard building block schema is defined in a json/yaml compatible style as these are:

  • very commonly used/standard formats

  • open and accessible to everybody

  • human readable

  • hierarchical

  • label based

Any logical yaml features like linking are omitted to keep the schemas as generic and format independent as possible. We omit the brackets of a json style format for readability. Note that it is straightforward to read this schema as yaml and convert it between yaml, json and/or xml as you see a need for it. Here we convert it to html tables as well for documentation purposes.

SBB schema example

Before discussing a more formal SBB definition, we first show an example of two blocks in the SBB schema, i.e. a MMI power coupler mmi and an optical amplifier soa. They are grouped under the blocks label. Licensing and background information is organized under the header label.

# SBB example for describing a layout for a MMI block and a SOA block

header:
  description: uPDK example of building blocks
  file_version: 0.1
  openEPDA:
    version: openEPDA-uPDK-SBB-v0.2
    link: "https://openEPDA.org"
  schema_license:
    license: CC BY-ND 4.0
    attribution: "openEPDA-uPDK-SBB-v0.2, Copyright (c) 2017-2019, Ronald Broeke"
  pdk_license: null

blocks:
  mmi:
    bbox: [[0.0, -10.0], [50.0, -10.0], [50.0, 10.0], [0.0, 10.0]]
    doc: "A 1x2 multi-mode interference (MMI) coupler."
    parameters: null
    pins:
      a0:
        doc: optical
        width: 1.5
        xsection: GUIDE
        xya: [0, 0, 180]
      b0:
        doc: optical
        width: 1.5
        xsection: GUIDE
        xya: [50, 2, 0]
      b1:
        doc: optical
        width: 1.5
        xsection: GUIDE
        xya: [50, -2, 0]
    pin_in: a0
    pin_out: b0
    drc: null
  soa:
    bbox: [[0.0, -0.5*width], [length, -0.5*width], [length, 0.5*width], [0, 0.5*width]]
    doc: "A semiconductor optical amplifier (SOA)"
    parameters:
      length:
        doc: "Length of the SOA."
        type: float
        max: 2500.0
        min: 150.0
        value: 400
        unit: um
      width:
        doc: "Waveguide width of the SOA."
        type: float
        max: 5.0
        min: 0.5
        value: 1.0
        unit: um
    pins:
      a0:
        doc: optical
        width: 1.5
        xsection: ACTIVE
        xya: [0, 0, 180]
      b0:
        doc: optical
        width: 1.5
        xsection: ACTIVE
        xya: [length, 0, 0]
    pin_in: a0
    pin_out: b0
    drc:
      angle:
        values: [0, 180]

SBB schema description

The standard building block schema description in table form is printed below. Alternatively, download the SBB schema description below in csv format. More information on the label <…> notation is found below the table. The columns have the following meaning:

  • label: shows the label hierarchy by indentation (or by number in csv).

  • type: the datatype of each label. A datatype is int, float, str, object, or subschema. See the SSB metadata schema for more detail.

  • required: A bullet value indicates that a label must be present in the SBB to have a minimum set of data to describe the block. If not present the default value must be assumed. If there is no default the schema is incomplete.

  • documentation: describes the purpose of the label

  • default: default value where applicable. If a value is missing the default must be assumed.

  • allowed_values: list of allowed values, if applicable

  • example: example data

Defined top labels are

  • header: license and background information on the schema

  • blocks: standard black blocks (SBB)

  • subschemas: subschemas that may be called from other parts of the schema. Note that a subschema may contain another subschema as long as there are no circular references.

SBB scheme in table form

label

type

required

documentation

default

allowed_values

example

header:

object

Contains licensing and usage information

· description:

str

Short info on the purpose of this scheme

schema to describe a uPDK.

· file_version:

str

version of the SBB file

1.0

· openEPDA:

object

openEPDA related information.

· · version:

str

openEPDA version of this scheme

openEPDA-uPDK-SBB-v0.2

· · link:

str

Link to openEPDA site.

https://www.openEPDA.org

· schema_license:

object

License information for using this superscheme and the derived scheme

· · license:

str

CC BY-ND 4.0 - Mandatory Creative Commons license condition

CC BY-ND 4.0

· · attribution:

str

openEPDA–uPDK-SBB-v0.2, Ronald Broeke (c) 2017-2019 - Mandatory attribution required under the Creative Commons license

openEPDA-uPDK-SBB-v0.2, Ronald Broeke (c) 2017-2019

· pdk_license:

str

License conditions of the content in the YAML.

under NDA, Joe & sons #123-1999

xsections:

object

Contains zero or more cross section definitions.

· <xsection_name>:

object

Define a cross section reference named <xsection_name>.

· · width:

float

Define the default width of a structure in this xsection <xsection_name>.

· · width_min:

float

Define the minimum width of a structure in this xsection <xsection_name>.

· · radius:

float

Define the default radius of a structure in this xsection <xsection_name>.

· · radius_min:

float

Define the minimum radius of a structure in this xsection <xsection_name>.

· · models:

object

Contains zero or more compact models for xsection <xsection_name>.

· · · models:

subschema

models

blocks:

object

Contains zero or more BB definitions.

· <block_name>:

object

Define a BB reference named <block_name>.

· · id:

str

Reference to the unique ID used for this block across PDK version.

None

· · version:

str

BB version number set by the foundry.

· · license:

str

Licensing conditions of this BB.

Block may be licensed.

Licensed by foundry X under Y.

· · cellname:

str

Cellname of the BB. If no cellname label is found, the <block_name> is the cell name.

· · doc:

str

Short sentence to describe the BB to the user.

· · bbox:

list

Array of points (x, y) defining the bbox outline as a polygon. The polygon does not have to be closed.

None

[[0, 0], [10, 0], [10, 5], [0, 5]]

· · bb_width:

float

Width of the BB cell in um.

· · bb_length:

float

Length of the BB cell in um.

· · pin_in:

str

Name of default input pin of the BB.

· · pin_out:

str

Name of default output pin of the BB.

· · pins:

object

Contains one or more pin definitions for <block_name>.

· · · <pin_name>:

object

Define a pin named <pin_name>.

· · · · id:

int

unique identifier

· · · · width:

float

Width of the pin.

2.0

· · · · width_unit:

str

Unit of the pin width.

um

list of allowed values

um

· · · · xsection:

str

Cross section name.

WAVEGUIDE

· · · · alias:

str

Alias for <pin_name>.

input1

· · · · doc:

str

Short description of the pin.

optical input

· · · · xya:

list

Pin coordinate (x, y, a) with respect to <block_name> origin.

[0, 0, 0]

· · · · xya_unit:

list

Units of the (x, y, a) coordinate

[‘um’, ‘um’, ‘deg’]

· · · · direction:

str

pin direction of xya w.r.t. the block; outward ‘out’ or inward ‘in’.

out

[‘in’, ‘out’]

· · · · radius:

float

radius of curvature at pin (0 or null is no curvature).

· · models:

object

Define zero or more compact models.

None

· · · models:

subschema

models

· · drc:

object

Define zero or more DRC rules.

None

· · · drc_rules:

subschema

drc rules

· · parameters:

object

Pcell only. Contains one or more BB parameter definitions.

· · · <parameter_name>:

object

Define a BB parameter.

· · · · doc:

str

Short parameter description.

No documentation provided

· · · · type:

str

Data type

[‘float’, ‘int’, ‘str’]

· · · · unit:

str

Unit of the parameter

list of allowed values

[‘um’]

· · · · min:

see type

Minimum value.

None

· · · · max:

see type

Maximum value.

None

· · · · value:

see type

Default value.

None

list of allowed values if applicable

· · · · alias:

str

Alias for <parameter_name>.

· · keywordparameters:

list

List of <parameter_name> used in the BB function call (subset of parameters). If the label is not present, all parameters are considered to be keyword parameters.

[‘a’, ‘b’, ‘c’]

· · cellnameparameters:

list

List of <parameter_name> for more descriptive cell names (subset of keywordparameters).

b, x

· · call:

str

name of function call that creates the BB

· · groupname:

str

Name for grouping BB.

· · ip_block:

object

Define ip_block data as ip_block

· · · ip_block:

subschema

i- block information

· · icon:

object

Define an icon for <block_name>.

· · · function:

str

Name of the function that returns a cell with the icon.

· · · parameters:

object

Parameters for which default will be overridden.

· · · · bufx:

float

Buffer in the x-direction in um.

· · · · bufy:

float

Buffer in the y-direction in um.

· · · · length:

float

Icon length in the x-direction in um.

· · · · width:

float

Icon length in the y-direction in um.

subschemas:

object

Describe zero or more subschemas

· drc-rules:

object

Describe one or more <<drc-rules>>

· · angle:

object

angle DRC rule for instantiation w.r.t the mask

· · · values_and_domains:

subschema

values and domains

· · angle_mirror:

object

angle DRC rule for instantiation w.r.t the mask with mirroring status

· · · flip:

object

group rules that apply for a flip=true state

· · · · values_and_domains:

subschema

values and domains

· · · noflip:

object

group rules that apply for a flip=false state

· · · · values_and_domains:

subschema

values and domains

· values_and_domains:

object

Describe one or more <<values_and_domains>>.

· · values:

list

list of allowed angles

[0, 90, 270]

· · domains:

list

list of allowed angle domains

[[0, 90], [180, 270]]

· models:

object

Describe one or models.

· · <model_name>:

object

Define a compact model reference named <model_name>.

model_1

· · · id:

int

compact model unique identifier.

· · · name:

str

Reference to a compact model description.

· · · parameters:

object

Contains one or more parameter assignments.

{‘a’: 4.0, ‘x’: 10}

· · · · <parameter_name>:

str

Assign a value to <parameter_name>.

· ip_block:

object

Describe ip-block data.

· · license:

str

License information

CC BY-ND 4.0

· · owner:

str

IP_Block owner

Bright Photonics

· · pgp_file:

str

Name of pgp encrypted ip_block file.

· · pgp_key:

str

Hash of public pgp key used to encrypt the IP-Block.

· · md5:

str

md5 hash of decrypted pgp ip_block.

<label>

Labels expressed with the syntax <label> denote that the text <label> has to be replaced with one or more explicit label name(s), e.g. pin1, myblock5. It also denotes that there can be more than one label at the same hierarchy level.

Using subschemas

Labels with type subschema point to a label under the top-level label “subschema”. The subschema structure is to be inserted at the label of type subschema: This allows for reuse of hierarchical data structures and/or indicate that different structures are possible depending on the context. For example

# label with a subschema reference to "ruleset":
rules:
  ruleset

# subschema:
ruleset:
  label1: data1
  label2: data2

# expansion in SBB schema:
rules:
  label1: data1
  label2: data2

Special values

  • true: logical true

  • false: logical false

  • null: null, void, None

Coordinates

Geometrical coordinates are described in the Cartesian coordinate system.

SBB superschema

The SBB schema is defined by a SBB superschema, which is defined in the same json/yaml format as the SBB schema. It can be downloaded in yaml. The superschema describes the labels and structure of the SBB schema along with its metadata. Metadata can be identified by the superschema labels that start with an _ character. Labels without a _ as first character represent labels of the SBB schema as discussed in the previous sections.

Metadata labels

The following metadata labels are defined:

Labels that are always present under a SBB label:

  • _type: datatype of the label:

    • str: a string: “I am a string”

    • list: a list of elements, e.g. values, strings or other lists: [1.0, 10.0, 100.0]

    • object: hierarchically nested data, i.e. more levels exist under this label

    • subschema: a label reference to a subschema object stored directly under the top-label ‘subschema’.

  • _required: true, if the label is mandatory, false otherwise. Note the _required label is only relevant specific cases where the parent in the hierarchy SBB exists.

  • _doc: description of the purpose of the label

Situational labels:

  • _properties: start the description of a new hierarchy level, i.e. a new level of labels

  • _example: example of the data content of a label

  • _default: default data value

  • _allowed_values: list of allowed data values of the label, e.g. [um, nm, pm]

Below an example of the metadata labels in a superschema. Note that the metadata labels reside at the odd hierarchy level 1, 3, 5, …, where as the normal labels occupy the even levels 0, 2, 6, …

# Snippets of the SBB superschema showing the metadata labels in action.

blocks:
  ...
    ...
    <block_name>:
      ...
        ...
        pins:
          _type: object
          _required: true
          _doc: Contains one or more pin definitions for <block_name>.
          _properties:
            <pin_name>:
              _type: object
              _required: true
              _doc: Define a pin named <pin_name>.
              _properties:
                width:
                  _type: float
                  _required: true
                  _doc: Width of the pin.
                  _example: 2.0
                width_unit:
                   _type: str
                   _required: false
                   _doc: Unit of the pin width.
                   _allowed_values: list of allowed values
                   _default: um
                   _example: um
                ...
        drc:
          _type: object
          _required: true
          _doc: Define zero or more DRC rules.
          _default: null
          _properties:
            drc_rules:
              _type: subschema
              _required: false
              _doc: drc rules