OpenParable
Skip to content
← Back to skills

Gdsfactory Component Designer

Design
gdsfactory-component-designer

Gdsfactory Component Designer is an Agent Skill for design published in the gdsfactory/gdsfactory repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Expert photonic IC designer using gdsfactory. ALWAYS use this skill for ANY task involving silicon photonics, photonic integrated circuits (PICs), GDS layout design, or component visualization. Trigger this skill whenever the user mentions photonic components (waveguides, MMIs, rings, gratings, MZIs), layout design, or asks to "design", "generate", "visualize", "tweak", or "assemble" photonic structures. Do not wait for an explicit mention of "gdsfactory" – if the task involves photonic layout or PICs, this is the required tool.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/gdsfactory/gdsfactory/blob/HEAD/.agents/skills/gdsfactory-component-designer/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/gdsfactory-component-designer, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

gdsfactory Component Designer Skill

This skill lets an LLM agent generate, visualize, and iteratively modify photonic-IC components using the gdsfactory Python library.


When to use this skill

Activate this skill when the user:

  • Asks to create or generate a photonic component (waveguide, MMI, ring resonator, coupler, grating coupler, spiral, taper, MZI, etc.).
  • Wants to see what a component looks like (requests a plot, image, or preview).
  • Wants to tweak component parameters (width, length, radius, gaps, layers, cross-sections, etc.) and see the result.
  • Mentions GDS, photonic layout, or a specific PDK.
  • Asks to compose multiple components together into a larger circuit.

1 — Setting up the environment

Choosing the right Python command

The examples below use bare python, but you must adapt the invocation to whatever Python environment the user has set up. Common alternatives:

SetupCommand
System / venv / condapython
uv projectuv run python
pipx-installed gdsfactorypipx run --spec gdsfactory python
Nix shellnix develop -c python

Probe the environment first (e.g. check for a pyproject.toml with [tool.uv], or an active virtualenv) and pick the appropriate command. When in doubt, try python -c "import gdsfactory" — if it fails, fall back to uv run python or ask the user.

Activating the PDK

Before generating any component, make sure the PDK is activated. The generic PDK ships with gdsfactory and is always available:

import gdsfactory as gf

# Activate the built-in generic PDK (always available)
gf.gpdk.PDK.activate()

If the user specifies a third-party PDK (e.g. cspdk, ubcpdk, sky130, gf45spclo), import and activate it instead.

Always clear the cell cache between independent component generations to avoid stale state: gf.clear_cache().


2 — Generating a component

2.1 From the built-in component library

gdsfactory ships with 300+ parametric component factory functions under gf.components. To instantiate a component, call its factory function:

import gdsfactory as gf
gf.gpdk.PDK.activate()

# Example: 1×2 MMI splitter
c = gf.components.mmi1x2(width_mmi=5.0, length_mmi=25.0, gap_mmi=0.25)

2.2 Inspecting component parameters

Every component factory function is a standard Python callable with typed parameters. Use help() or inspect.signature() to discover the parameters.


3 — Visualizing a component (Proactive Workflow)

Visualization is essential: render and inspect the component after creating or modifying it to verify the result.

3.1 Save a plot image to disk and display it

Use the helper script bundled with this skill for reliable headless rendering. From a bash tool or Python subprocess:

python .agents/skills/gdsfactory-component-designer/scripts/visualize_component.py \
    "gf.components.mmi1x2(width_mmi=5.0, length_mmi=25.0)" \
    /tmp/mmi1x2.png

After saving, always import the image into context so you and the user can see it.

  • Be Proactive: If the user's intent is clear (e.g., "Create an MMI then change its width"), do not stop for permission after the first step. Perform the generation, visualization, and modification in a single turn if possible.
  • Concise Reporting: Describe the component briefly (ports, size). If the change is minor, just confirm the update and point to the new image. Avoid repeating the entire component description multiple times.

4 — Modifying a component

4.1 Adjusting parameters

The simplest modification is changing the factory-function arguments. Always call gf.clear_cache() before regenerating to avoid stale data.

4.2 Composing components

Build a custom component by placing and connecting sub-components. Use the @gf.cell decorator for proper naming and caching.


5 — Exporting the component

# Write to GDS file
gdspath = c.write_gds("/tmp/my_component.gds")

6 — Proactive Design Loop (Best Practices)

When the user asks for a component, follow this streamlined loop:

  1. Understand & Execute: Identify the component and parameters. If the user asks for a sequence of steps, execute them as a batch where logical.
  2. Generate & Visualize: Create the component and render the PNG.
  3. Show & Tell: Share the image and a short summary of what changed.
  4. Anticipate: If the next step is obvious, offer to perform it or just do it and show the result.
  5. Iterate Concisely: For small tweaks, don't repeat the full initial explanation. Just show the new image and highlight the specific change.

7 — Common component quick-reference

ComponentFactory functionKey parameters
Straight waveguidegf.components.straightlength, width
Euler bendgf.components.bend_eulerradius, angle
1×2 MMIgf.components.mmi1x2width_mmi, length_mmi
Ring resonatorgf.components.ring_singlegap, radius
Grating couplergf.components.grating_coupler_teperiod, n_periods

8 — When you are unsure: consult the docs and samples

The full gdsfactory docs are at https://gdsfactory.github.io/gdsfactory/. Browse tutorial notebooks under docs/notebooks/ or over 100 sample Python scripts under gdsfactory/samples/ for worked examples.

Don't guess – search the repo for examples first.


9 — KLayout API: transformations with DCplxTrans

gdsfactory's geometry backend is kfactory, built on KLayout's Python db module. Full API docs: https://www.klayout.de/doc-qt5/code/module_db.html

9.1 DCplxTrans constructor

klayout.db.DCplxTrans represents a rotation + mirror + translation on µm-unit coordinates. Positional and keyword arguments are both supported:

import klayout.db as kdb

# positional: DCplxTrans(mag, angle, mirror, u)
t = kdb.DCplxTrans(1.0, 45.0, True, kdb.DVector(10.0, 5.0))

# keyword (preferred for clarity):
t = kdb.DCplxTrans(mag=1.0, angle=45.0, mirror=True, u=kdb.DVector(10.0, 5.0))

Parameters (application order: mirror → rotate → translate):

ParameterTypeDescription
magfloatScaling factor — always 1.0; see warning below
anglefloatCCW rotation in degrees
mirrorboolMirror about x-axis before rotation
uDVectorTranslation in µm

⚠️ Never set mag != 1.0. No foundry accepts scaled instances. Use component factory parameters to create differently-sized variants.

ℹ️ ComponentReference.dcplx_trans snaps to the manufacturing grid via ICplxTrans, so off-grid placements are silently adjusted.

9.2 Setting ComponentReference.dcplx_trans

import gdsfactory as gf
import klayout.db as kdb

circuit = gf.Component("circuit")
ref = circuit.add_ref(gf.components.mmi1x2())

# rotate 45°, mirror, translate to (10, 5) µm
ref.dcplx_trans = kdb.DCplxTrans(mag=1.0, angle=45.0, mirror=True, u=kdb.DVector(10.0, 5.0))

9.3 Composing transformations

DCplxTrans objects compose with * (right-hand operand applied first):

rotate      = kdb.DCplxTrans(angle=90.0)
translation = kdb.DCplxTrans(u=kdb.DVector(20.0, 0.0))

ref.dcplx_trans = translation * rotate   # rotate first, then translate

9.4 Quick-reference

GoalExample
Translatekdb.DCplxTrans(u=kdb.DVector(dx, dy))
Rotate 90° CCWkdb.DCplxTrans(angle=90.0)
Mirror about x-axiskdb.DCplxTrans(mirror=True)
Rotate then translatetranslation * rotate
Read / modify in placeref.dcplx_trans / ref.dcplx_trans = t * ref.dcplx_trans