Preface

Who this is for

You’re a chip designer - photonic, electronic, or both - who wants to write layouts in Python instead of clicking around a layout editor. You know what a GDS file is. You probably know what a port is. You may already know one of the existing layout DSLs and are looking for either a faster authoring experience, a tighter design-tool integration, or both.

You don’t need to be a Python expert. The library is shaped to read like English: c.add(...), c.Place(thing).at(...), c.Route(a, b).go("E", by=200). Where the names are unusual, this guide explains why.

What’s covered

• Getting started (Chapters 1–2): the bundled runtime, the smallest possible script, the core nouns and verbs of the API.
• Building layouts (Chapters 3–6): placement, routing (auto and manual), route profiles, Bookmarks, and Notes.
• Working with PDKs (Chapter 7): using a process design kit’s layers and components.
• Cookbook (Chapter 9): full recipes for an MZI, a ring resonator, and a fanout bus.
• Agent workflows (Chapter 10): Phoebe reference lookup, project inspection, and action permissions.
• Packages and environments (Chapter 8): consuming local/Git engineering packages through explicit project dependencies.
• Appendices: a compact cheat sheet, errors and warnings, a glossary, and generated API signatures.

What’s not covered

• Writing your own PDK - that lives in the PDK Authoring Guide, which also covers the @route_profile builder for custom cross-sections.
• The Lumicron Mac viewer’s GUI - see the in-app help.
• Internal architecture - this guide focuses on the public authoring API.

Conventions

Code blocks appear as:

import lumicron as lm
c = lm.CELL("Hello")

Three callout styles signal different intents:

How to read

Chapters 1 and 2 build vocabulary; everything after is reference plus recipes. Skim the cheat sheet (Appendix A) once before reading the rest - it tells you which idioms to expect.