# Copyright 2026 Helge Gehring, Simon Bilodeau and contributors.
# Licensed under the Apache License, Version 2.0.
# ---
# jupyter:
#   jupytext:
#     text_representation:
#       extension: .py
#       format_name: percent
#       format_version: '1.3'
#   kernelspec:
#     display_name: Python 3
#     language: python
#     name: python3
# ---

Hierarchical Netlist Extraction¶

This example demonstrates how extract_netlist handles multi-layered cell hierarchies. GDSwell performs single-level extraction, meaning it identifies connections between the immediate children of the cell you are analyzing.

Mixed Hierarchy with Alternating Bends¶

In this example, we build a mixed hierarchy where composite cells (Straights + Bends) are connected via top-level leaf components:

Straight: A simple straight waveguide component.
Bend: A circular bend component.
Composite Cell: Composed of a straight and a bend.
Top Cell: Composed of two Composite cells connected via a bridging Straight.

import gdswell as gw
from gdswell.components.bend_circular import bend_circular
from gdswell.components.straight import straight
from gdswell.netlist import extract_netlist

1. Define the PDK Cross-Section¶

A basic cross-section (e.g., 500nm wide SOI waveguide) used for all components.

xs = gw.CrossSection(layer_sections=(gw.LayerSection("core", gw.Layer(1, 0), width=0.5),))

2. Define a Composite cell¶

Composed of a straight and a bend.

@gw.cell
def composite_cell() -> gw.Cell:
    """A composite cell with a straight and a bend."""
    c = gw.Cell()
    s = c.add_ref(straight(xs, length=10.0))
    b = c.add_ref_connected(bend_circular(xs, radius=10.0, angle=90.0), "0", s["1"])

    # Expose outer ports
    c.add_port(s["0"].renamed("in"))
    c.add_port(b["1"].renamed("out"))
    return c

3. Define the Top cell¶

Composed of two composite cells and one leaf straight connected in a chain.

@gw.cell
def top_cell() -> gw.Cell:
    """A top cell with alternating composite and leaf components."""
    c = gw.Cell()
    c1 = c.add_ref(composite_cell())
    # Connect a leaf straight directly at the top level
    l1 = c.add_ref_connected(straight(xs, length=5.0), "0", c1["out"])
    # Connect another composite cell
    c2 = c.add_ref_connected(composite_cell(), "in", l1["1"])

    # Expose top-level ports
    c.add_port(c1["in"].renamed("TOP_IN"))
    c.add_port(c2["out"].renamed("TOP_OUT"))
    return c

4. Netlist Extraction¶

Extracting the netlist of the Top Cell shows connections between its immediate children: the two composite cells and the bridging leaf straight.

# Extract netlists at different levels of the hierarchy
print("=== Extracting Composite Cell Netlist ===")
comp = composite_cell()
print(extract_netlist(comp))

print("\n" + "=" * 40 + "\n")

print("=== Extracting Top Cell Netlist ===\n")
top = top_cell()
print(extract_netlist(top))

# Show the top cell interactively in the documentation
top

=== Extracting Composite Cell Netlist ===

Netlist(
  Instances:
    straight_25cff648_d09fc68c_0 (straight_25cff648_d09fc68c)
    bend_circular_a41ffb9b_d99a4e97_0 (bend_circular_a41ffb9b_d99a4e97)
  Connections:
    straight_25cff648_d09fc68c_0.1 <-> bend_circular_a41ffb9b_d99a4e97_0.0
  Exposed Ports:
    in -> straight_25cff648_d09fc68c_0.0
    out -> bend_circular_a41ffb9b_d99a4e97_0.1
)

========================================

=== Extracting Top Cell Netlist ===

Netlist(
  Instances:
    composite_cell_da39a3ee_627f9ecb_0 (composite_cell_da39a3ee_627f9ecb)
    straight_f322a8cd_d09fc68c_0 (straight_f322a8cd_d09fc68c)
    composite_cell_da39a3ee_627f9ecb_1 (composite_cell_da39a3ee_627f9ecb)
  Connections:
    composite_cell_da39a3ee_627f9ecb_0.out <-> straight_f322a8cd_d09fc68c_0.0
    straight_f322a8cd_d09fc68c_0.1 <-> composite_cell_da39a3ee_627f9ecb_1.in
  Exposed Ports:
    TOP_IN -> composite_cell_da39a3ee_627f9ecb_0.in
    TOP_OUT -> composite_cell_da39a3ee_627f9ecb_1.out
)