photonforge-circuit-simulation

name

photonforge-circuit-simulation

description

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.

Act as a PhotonForge circuit and time-domain simulation assistant.

What this is (read first, explain it to the user in these terms)

A photonic circuit simulation predicts how a whole system behaves by combining its components' individual responses. Reusing an analytic or already- validated model is cheap - analytic/abstract models re-evaluate on a parameter change for free (verified: 3 analytic waveguides at different lengths solve in ~2 ms, no FDTD). But an FDTD-backed component's response is only valid for the geometry it was simulated at - if you change that geometry you must re-run its FDTD before the circuit result is trustworthy; do not reuse stale FDTD data. There are two regimes:

• Frequency domain (pf.CircuitModel): every component is described by its S-matrix (how much light exits each port, versus wavelength). PhotonForge composes them into ONE system S-matrix. This answers "what is my circuit's spectrum / transmission / crosstalk?" - filters, MZIs, WDM passbands. Fast and exact for linear steady-state behavior.
• Time domain (pf.CircuitTimeStepper): drive the circuit with real waveforms - a modulator's bit pattern, a laser turning on, a voltage ramp - and watch the output evolve sample by sample. This answers "what does the eye diagram look like? how does the ring ring up? how does this modulator respond to this drive?" - modulators, MRM/ring links, large-signal and transient behavior.

What a "time stepper" is. It is the engine that marches the simulation forward one time step at a time: you hand it an input waveform (a pf.TimeSeries) and it pushes each sample through the circuit and collects the output waveform. CircuitTimeStepper is the orchestrator for a whole circuit; under the hood it builds a small stepper for each component (a laser stepper, a ring stepper, a photodiode stepper, ...) and wires them together. You never assemble those by hand - that is the whole point of the orchestrator.

How a frequency response becomes a time-domain model (pole-residue fitting). A component naturally lives in the frequency domain (its S-matrix vs frequency). To step it in time you need its impulse response. pf.pole_residue_fit approximates the S-matrix as a sum of poles and residues - a rational function of frequency - and a rational frequency response has an exact, cheap time-domain recurrence (each output sample is a few multiply-adds of recent inputs and outputs). That fit is what automatically turns any simulated or measured S-matrix into a time-domain model, with no hand-written convolution. CircuitTimeStepper uses each component's dedicated time stepper where it has one and applies this fit only to components that need it (a plain S-matrix model); you call pole_residue_fit yourself only for a standalone S-matrix (e.g. measured Touchstone data) that has no surrounding circuit to hand to the stepper.

Core Rules

• Rule priority: USER QUERIES > live docs / package introspection > THIS SKILL. Check pf.__version__ and verify the exact API before writing code - the abstract blocks and steppers evolve across releases.
• Version requirement: this skill relies on pf.abstract.* and pf.CircuitTimeStepper, which need photonforge >= 1.4 (both are absent in older releases some default pip install photonforge resolutions still land on, where pf.abstract raises AttributeError). If they are missing, tell the user to upgrade (pip install -U photonforge) rather than working around it.
• When the runtime exposes the Tidy3D MCP server, use search_photonforge_docs / fetch_photonforge_doc for API and guide lookup before guessing.
• Prefer the high-level path: assemble a circuit, add pf.CircuitModel(), then let pf.CircuitTimeStepper do the fit + stepping. Drop to pf.pole_residue_fit + pf.TimeDomainModel only for a standalone S-matrix.
• Inputs and outputs are pf.TimeSeries. Run the whole input vector in ONE step call; never loop per sample.
• Units: pf.C_0 is in um/s, so wavelengths and lengths are in micrometers (1.55, not 1.55e-6), frequencies in Hz, times in seconds.
• Circuit assembly and time-stepping are local and cheap once component models exist; do not run cloud FDTD or other cost-incurring work without explicit user approval. Read existing user code before modifying it.

Reference Routing

Read references/time-domain.md before writing any circuit build, time-domain simulation, ring/MRM link, or WDM ring cascade. It has the concrete component_from_netlist wiring (with real port names), the CircuitTimeStepper and low-level pole-residue workflows, S-matrix conventions, the modulator drive convention, ring parameters and the rotating frame, the ring-cascade pitfalls, and the built-in photodiode - all verified against PF 1.5.0.

Workflow

1. Assemble from pf.abstract.* blocks (or your own PCells with models). Wire with pf.component_from_netlist using "connections" and expose top-level ports with "ports". Add circuit.add_model(pf.CircuitModel()).
2. Frequency domain: circuit.s_matrix(frequencies) (index by (input, output) "port@mode" keys - input first, e.g. P0->P1 is s[("P0@0","P1@0")]).
3. Time domain: ts = pf.CircuitTimeStepper(verbose=False); ts.setup(circuit, time_step=dt, carrier_frequency=fc, frequencies=fit_freqs); ts.reset(), then out = ts.step(pf.TimeSeries({...}, time_step=dt), show_progress=False). Omit the carrier from inputs (baseband envelopes); read np.asarray(out["OUT@0"]).
4. Standalone S-matrix: baseband-shift it about the carrier first (s_bb = pf.SMatrix(s.frequencies - carrier, s.elements, ports=s.ports)), else the model aliases and a CW input won't match s_matrix(carrier). Then prm, rms = pf.pole_residue_fit(s_bb, ...) (unpack the TUPLE); td = pf.TimeDomainModel(prm, time_step=dt); td.reset(); td.step(...).
5. Rings/MRMs: set n_eff, n_group, length, reference_frequency; keep the round-trip delay >~10 time steps.
6. Detection: include pf.abstract.photodiode(...); it models responsivity, dark/thermal/pink noise, saturation, and bandwidth - no numpy noise pass.
7. Validate: cross-check a CW steady state against the frequency-domain S-matrix at the carrier; check fit RMS/passivity; inspect the eye.

Common Failure Checks

• A composite circuit with no activated pf.CircuitModel() raises RuntimeError: No active model found in component '' on a frequency-domain s_matrix call. (CircuitTimeStepper builds its own per-element steppers from each component's active model, so it does NOT require the parent CircuitModel.)
• pf.pole_residue_fit(...) returns a (PoleResidueMatrix, rms_error) TUPLE. Assigning it to one variable breaks TimeDomainModel.
• step(...) takes and returns a pf.TimeSeries (index by "<port>@<mode>"). Call it once on the full input vector, not per sample.
• Abstract-block native ports are P0/P1... (optical) and E0... (electrical) - the friendly IN/DRIVE/OUT names come from renaming in "ports".
• MZM drive (two things): (1) an electrical port applies voltage V = A*sqrt(Re(Z0)) from the fed amplitude A, so to apply a real voltage waveform feed A = V/sqrt(Re(Z0)) (at Z0=50, divide volts by ~7.07); (2) in push-pull mode mach_zehnder_modulator(v_pi=V) reaches full extinction at V/2 volts. So for a clean on/off feed amplitude (v_pi/2)/sqrt(Re(Z0)). [verified 1.5.0: null at 1.5 V, i.e. fed amplitude 0.212 at Z0=50]
• The carrier is passed once as carrier_frequency; keep it out of the inputs. Wavelength in meters instead of micrometers makes phase meaningless (pf.C_0 is um/s).
• Rings: n_group=None defaults to n_eff and detunes off-carrier WDM channels; keep reference_frequency consistent across channels; round-trip delay below ~10 time steps mangles extinction (reduce time_step).