Run and understand PhotonForge circuit-level and time-domain simulations. Compose component S-matrices into a whole-circuit frequency response with pf.CircuitModel, or drive the circuit with real waveforms (modulator bit patterns, laser turn-on, ramps) and watch the output evolve with pf.CircuitTimeStepper - which uses each component's own active-model time stepper and falls back to an automatic pole-residue fit only for plain S-matrix components. For a standalone S-matrix (e.g. measured Touchstone) use pf.pole_residue_fit + pf.TimeDomainModel directly. Covers pf.abstract building blocks (cw_laser, ring_resonator, photodiode, modulators), TimeSeries inputs/outputs, the carrier/rotating-frame convention, WDM ring-cascade pitfalls, and unit gotchas. Use when the user simulates modulators, ring/MRM links, WDM ring cascades, eye diagrams, transients, or photodiode detection, or asks what circuit vs time-domain simulation is.
Drive and verify the PhotonForge cloud GUI (photonforge.simulation.cloud) from an AI coding session. Make the edits programmatically with the PhotonForge PDA SDK - create and update projects, components, and versions - then drive a real web browser with the Playwright MCP server to open, screenshot, and confirm what the user actually sees in the GUI (the project list, a schematic, port placement, wire routing). The established pattern is 'PDA SDK controls, Playwright verifies': treat the GUI as a verification surface, not a control surface. Use when the user wants to build, edit, or visually verify schematics and applications on the cloud GUI, position a circuit correctly in a schematic, confirm port placement or wiring by screenshot, or reconnect the local photonforge-server so the GUI comes back online.
Assemble, route, inspect, and verify PhotonForge photonic layouts from schematic or netlist intent. Use when the user is working with component_from_netlist, Reference placement, physical connections, virtual connections, pf.parametric.route, routing errors, port or terminal exposure, get_netlist, LVS-style checks, schematic-to-layout conversion, or layout overlap/intersection sanity checks.
The PhotonForge LiveViewer is a local, interactive 2D layout viewer for pf.Component and circuits: `from photonforge.live_viewer import LiveViewer`, point it at a component, and it serves a browser view that redraws as you edit the design - the primary visual feedback loop while building layouts. Covers the Python lifecycle (open on a fixed port, push updates, show several components together, fit large devices, release the port) and the browser-side window.lvApi that lets an AI agent drive the viewer headlessly: zoom/pan/fit the camera, toggle layers, inspect the shape at a point, measure distances, and read the layer list, cell hierarchy, and camera state. Use when the user wants to see or iterate on a PhotonForge layout, run a viewer script, drive or inspect the viewer programmatically, or fix a stuck/port-in-use LiveViewer.
Author, review, and repair PhotonForge parametric components (PCells), custom technologies, ports, hierarchy, and schema-aware component definitions. Use when the user is creating or debugging PhotonForge components, using @pf.parametric_component or @pf.parametric_technology, building geometry with PhotonForge APIs, exposing ports, working with Reference hierarchy, preparing components for GUI/schema serialization, or exporting layout previews.
Version-control PhotonForge projects and use the API that creates and edits projects you can open, edit, and simulate in the browser GUI. Set up photonforge-server so the cloud GUI runs the user's own Python locally (recomputing their parametric components at new parameters and submitting their simulations); create and load projects, snapshot immutable versions and named tags, import PDK libraries, share with a team, and back a GUI schematic with a custom component so a teammate can open a link and click Run. This is the PhotonForge project and collaboration layer, also called PDA (Photonic Design Automation), used through `photonforge.pda` and the `photonforge-server` command. Use when the user runs photonforge-server, connects the cloud GUI to local Python, calls photonforge.pda, versions/tags/shares a project, seeds a PDK library, or hits a GUI recompute error such as 'No module named' or 'has no active model'.
Save and load PhotonForge designs, and understand how they are represented on disk. Full-state PHF files (pf.write_phf / pf.load_phf / pf.load_full_phf) preserve the component, hierarchy, ports, technology, and simulation models; layout export/import (pf.write_layout / pf.load_layout) handles GDS/OASIS mask geometry for the foundry; pf.load_snp imports Touchstone S-parameters; and Component.get_netlist() inspects circuit connectivity. Use when the user saves or loads a design, moves it between sessions or machines, exports a mask for fabrication, imports measured S-parameters, debugs round-trip fidelity, or asks how PhotonForge stores components, references, ports, technologies, coordinates, and transforms.
Variation-aware yield and tolerance analysis for photonic circuits with PhotonForge + Tidy3D. Build validated parametric surrogates of every subcomponent over process corners (silicon thickness, waveguide width/CD, optionally etch/sidewall/temperature) from a bounded one-time FDTD budget, then Monte-Carlo hundreds of virtual chips across wafers and lots to get functional statistics — resonance/passband shift, Q, linewidth, extinction ratio, insertion loss — as box plots, yield numbers, and lot/wafer/chip variance decompositions. Use when the user asks how fabrication variations, process corners, or wafer/lot variability affect a circuit, or asks for yield prediction, design for manufacturability (DFM), tolerance analysis, process-corner Monte Carlo over a PDK, or 'will this design survive the fab'.