Manifest schema

Every .lumpdk contains manifest.json at its root. The supported producer is lumicron_pdk.packaging; it generates the manifest by importing the PDK package. Do not use the older flat schema with top-level name, module, or a layers array.

Top-level sections

meta, component_schema_version, and components are generated; other sections depend on what the package exports. Lumicron consumes the manifest for PDK inspection, layer rendering, schematic component fields and ports, and circuit-model selection. A usable app PDK must declare nonempty layers and valid display name, package name, and version.

meta

Recommended minimum:

{
  "meta": {
    "name": "TinyPhot Research PDK",
    "package-name": "tinyphot",
    "version": "0.1.0"
  }
}

package-name and name deliberately serve different purposes. The app requires a declared import identity; it does not derive one from the display name. Use the packer and declare both names explicitly.

layers

layers is an object keyed by the Python LayerTable name:

{
  "layers": {
    "SILC": {
      "layer": 9,
      "datatype": 0,
      "color": "#008000",
      "min_width": 0.2,
      "min_spacing": 0.2,
      "min_radius": 5.0
    },
    "MTL1": {
      "layer": 4,
      "datatype": 0,
      "color": "#ffd700"
    }
  }
}

Generate this object from LAYER; do not maintain a second hand-written layer list.

display contains optional fill_color and frame_color hex colors, opacity, and either a named pattern or eight pattern_rows. Its optional border object contains width_px, opacity, and style (solid, dashed, dotted, dash-dot, none, or custom). Custom borders additionally contain dashes_px. These lengths are drawable pixels. Omitted border fields preserve the one-pixel opaque solid outline. Older readers may ignore the new border options. Author these fields with lpdk.Stipple, lpdk.Border, and lpdk.Layer; see Chapter 2 for validation bounds.

stack

Each root STACK entry becomes an ordered object with name, GDS layer/datatype, thickness, z_start, and sidewall_angle_deg. Material index is encoded as constant n, a sellmeier object containing B and C arrays, or a tabulated descriptor with the declared samples. An unspecified material is not an inferred refractive-index model.

{
  "stack": [
    {
      "name": "core_si",
      "layer": 9,
      "datatype": 0,
      "thickness": 0.22,
      "z_start": 2.0,
      "sidewall_angle_deg": 90.0,
      "n": 3.48
    }
  ]
}

route_profiles

Each named profile records its port layer/datatype, port width, default radius, optional minimum radius, and the concrete continuous strokes returned by the profile. Where declared, bend identifies the default bend and propagation_model carries the circuit propagation descriptor. A profile’s routing radius is not evidence that an arbitrary bend PCell is circular or has a known physical radius. For example:

{
  "route_profiles": {
    "silicon_strip": {
      "layer": 9,
      "datatype": 0,
      "width": 0.5,
      "radius": 10.0,
      "radius_min": 5.0,
      "strokes": [
        {"layer": 9, "datatype": 0, "width": 0.5, "offset": 0.0}
      ]
    }
  }
}

simulation

The packer derives schema version 1 from STACK and RP. It contains:

• units and reference_wavelength_um;
• process defaults such as background/cladding and default sidewall angle;
• materials keyed by stack-layer name;
• extrusions connecting GDS layers to material and z extents;
• simulation-facing route-profile strokes.

This is technology metadata, not evidence that an electromagnetic solver has run. The supported circuit execution path is SAX; Maple execution remains disabled in this alpha. Keep tabulated material and propagation data tied to their original wavelength range and units.

components

The packer records each decorated factory’s name, module, qualname, schematic flag, symbol, ordered parameters (name, type, required status, and default), and optional description. The legacy params dictionary is retained for older consumers; new consumers use parameters. Layer defaults preserve the GDS pair and, when available, the declared layer name.

ports contains the actual resolved names, directions, cardinal sides, widths, kinds, layer names/GDS pairs, and attached route-profile names. The packer evaluates the default factory and up to 16 boolean parameter variants. Ports controlled by one boolean receive a when condition. Missing required arguments or unsupported conditional metadata produce a port_resolution_error; a component that fails resolution must not be treated as a fully described schematic component.

circuit_models contains the cell’s named model declarations, and default_circuit_model names its explicit default. Model declarations retain their engine, kind, reference, settings, port mapping, and source factory. Package-owned Python references are relocated to the installed lumicron.pdks.<package-name> namespace; declared data references remain package-relative and their files are included. Model-resolution failures are recorded in model_resolution_error. The packer does not infer a simulation model from a component’s name or geometry.

gds_sources, when present, records imported layout resource paths, content hashes, and top cells. The corresponding GDS assets are packaged and checked for changes before publication.

Compatibility and validation boundary

• The app requires a valid ZIP with root manifest.json, the required metadata, and nonempty layers. The current packer emits component_schema_version: 1.
• Invalid package-name values fail packing. The output filename must be <package-name>.lumpdk; release versions belong in metadata or parent directories.
• Archive entries must use safe relative paths. Code and referenced resources are materialized in a private cache, rather than a user-maintained global UserPDKs folder.
• The packer includes Python source, declared compact-model data, declared optical CSV sources, package-local GDS assets, and optional drc.json. It does not copy arbitrary documentation, EULAs, or unrelated assets merely because they are mentioned in metadata.
• Current limits include 4 MiB for the serialized manifest and 128 MiB for the archive. Optical CSV source files are limited to 16 MiB each. Oversized samples are not silently downsampled.
• lumicron_required is not an enforced compatibility gate. Test the package against the target app/API build and publish that identity in release notes.

Use the packer, inspect the resulting ZIP, load it with Load PDK, and run a clean canonical import and representative circuit/layout examples as the release gate.