---
name: photonforge-schema-serialization
description: "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."
---

Act as a PhotonForge serialization assistant.

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

"Serialization" just means **saving your design to a file and loading it back.**
PhotonForge has three file formats for three different jobs:

- **PHF - your save file (full state).** `pf.write_phf` / `pf.load_phf` capture
  EVERYTHING needed to reopen the exact design later: the component and its whole
  hierarchy, its ports, the technology (layer stack), and the simulation models
  attached to it. Use PHF to move a design between sessions or machines, or to
  pick up and keep simulating later. It is the ONLY format that preserves models.
- **Layout - the mask (GDS / OASIS).** `pf.write_layout` / `pf.load_layout` save
  only the drawn geometry, for the foundry and other CAD tools (KLayout, etc.).
  Models and behavioral state are NOT kept and ports become plain layout markers.
  Use this to hand off to fab or exchange geometry - not to keep working.
- **Touchstone (.sNp).** `pf.load_snp` brings a component's frequency response
  (S-parameters) in from measurement or another simulator.

Plus **`component.get_netlist()`** to inspect how a circuit is wired (instances,
ports, connections) without touching files.

Rule of thumb: keep working -> PHF; send to fab -> GDS/OASIS; import measured
spectra -> Touchstone.

## Rule Priority

USER QUERIES > live docs / package introspection > THIS SKILL. Verify return
shapes against the installed version - the loaders return different container
types (below), and details change across releases.

## Core Rules

- **PHF is the only full-state format** (component + hierarchy + ports +
  technology + models). Save with `pf.write_phf(filename, *objects)`.
- **The loaders return CONTAINERS, not the bare object** - this is the most
  common mistake. Verified on PF 1.5.0:
  - `pf.load_phf(f)` -> **dict** `{'components': [...], 'technologies': [...]}`
    (each a list). Get your component with `pf.load_phf(f)["components"][0]`.
  - `pf.load_full_phf(f)` -> **tuple** of the top-level components; use `[0]`.
  - `pf.load_layout(f, technology=...)` -> **dict** `{cell_name: Component}`;
    get the top with `cells[top_name]`.
  - `pf.load_snp(f)` -> **tuple** `(S, frequencies)`, where `S` is a numpy array
    indexed `[frequency, output_port, input_port]`.
- Layout is **geometry-only** (no models; ports become markers) - use it for
  masks/fab, not to preserve state. Lengths are micrometers, angles degrees.
- Use the public `component.get_netlist()` for connectivity; do not depend on the
  private backend Node/Netlist schema helpers.
- When the runtime exposes the Tidy3D MCP server, use `search_photonforge_docs` /
  `fetch_photonforge_doc` before guessing. Don't run cost-incurring work without
  approval. Read existing user code before modifying it.

## Reference Routing

Read `references/serialization.md` before writing save/load code, diagnosing a
round-trip mismatch, or explaining the on-disk structure. It has the verified
return shapes, the PHF full-export layout, coordinate/transform representation,
the layout and Touchstone helpers, `get_netlist`, and how the internal GUI
Node/Netlist schema relates to the full export.

## Workflow

1. Pick the format by goal: keep working -> PHF; mask/fab -> GDS/OASIS; measured
   spectra -> Touchstone; inspect wiring -> `get_netlist`.
2. Save: `pf.write_phf("design.phf", component)` (pass more top-level objects as
   extra positional args).
3. Load and UNPACK the container:
   `comp = pf.load_phf("design.phf")["components"][0]` (or
   `pf.load_full_phf("design.phf")[0]`). Pass `set_config=False` to avoid
   changing the active session's default technology.
4. Round-trip verify: compare `name`, `set(ports)`, technology, and `bounds()`
   to the original before trusting the file.
5. Masks: `pf.write_layout("m.gds", component)`; then
   `cells = pf.load_layout("m.gds", technology=tech); top = cells[name]`.
   Confirm the layers resolved as intended.
6. Touchstone: `s, freqs = pf.load_snp("meas.s2p")`.

## Common Failure Checks

- **Wrong container assumption (the #1 mistake).** `load_phf` -> dict
  `{'components','technologies'}` (lists), not a component or a plain list;
  `load_full_phf` -> tuple; `load_layout` -> `{cell_name: Component}`;
  `load_snp` -> `(S_array, frequencies)`. Index into the container. [verified 1.5.0]
- `set_config=True` (default) lets a loaded file overwrite the active default
  technology/config; pass `set_config=False` to protect a live session.
- `write_layout` drops models and turns ports into markers - not a PHF substitute.
- After `load_layout`, layer mapping depends on the `technology=` you pass -
  verify the layers.
- There is no `pf.write_snp` in 1.5.0; `load_snp` is import-only.
- A `.phf` on disk is a BINARY file (magic bytes `FLEX`), not JSON - do not
  `json.loads` it or hand-edit it. Internally coordinates are scaled integers, not
  micrometers - query the live object (`ref.origin`, `ref[port].center`) instead
  of parsing raw numbers.