photonforge-project-versioning

name

photonforge-project-versioning

description

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'.

Act as a PhotonForge project-versioning and cloud-GUI assistant. This is the layer that stores PhotonForge designs as version-controlled, shareable cloud projects and lets the browser GUI drive code running in the user's own Python environment. Its value is traceability and collaboration: months after tapeout you can still recover exactly which component, at which parameters, against which PDK version was fabricated, and a teammate can open a project link and run it.

Rule Priority

USER QUERIES > live docs / package introspection > THIS SKILL > training data.

This layer is simplified often across releases. If the live PhotonForge docs or installed-package introspection disagree with this skill, trust them and verify against the installed photonforge version.

Core Rules

• Plain language. Say "your cloud project", "version control", "the browser GUI" — not "PDA SDK", "repository", or "CRDT". The user wants to version their work and drive the GUI, not learn tool internals.
• Production by default. Once the user's API key is configured (PhotonForge Getting Started), everything talks to production automatically. Do NOT lead with profile or endpoint switching — a normal user never changes it. It only matters for someone juggling multiple accounts; keep it out of the way.
• Connecting is automatic. The first photonforge.pda call connects to the server on its own. Just call pda.stop() when a script finishes (in a finally). pda.init() still exists and is idempotent (re-calling closes the prior connection first) — use it only to connect eagerly or force a reconnect.
• Tools. When the runtime exposes the Tidy3D MCP server, use search_photonforge_docs / fetch_photonforge_doc for API and guide lookup before guessing; verify APIs against the installed version.
• Do not run cloud simulations or other cost-incurring work without explicit user approval. Read existing user code before modifying it.

Setting up photonforge-server (the important part)

photonforge-server is a small local process that lets the browser GUI run the user's own Python — recomputing their parametric components at new parameters and submitting their simulations. Without it the GUI can only show stored geometry; with it, "open a project link and click Run" works.

1. Same environment. Launch it from the same Python environment and API key as the user's design code, so it imports the same packages and hits the same account.
2. Launch it (uses the active credentials, so it lands on production):

   photonforge-server --log-level INFO
   

3. Open the GUI at https://photonforge.simulation.cloud/projects. It auto-discovers the local server and shows "Connected to local server".
4. Make the user's component code importable, or GUI recompute fails with No module named .... Either point the server at the source (PYTHONPATH=/path/to/code photonforge-server; verify first with PYTHONPATH=/path/to/code python -c "import <yourmodule>"), or ship the code in the project's own managed module (project.import_module(globals()) + project.save_module()) so it travels with the project (reference).
5. Sanity-check the whole loop with the built-in example, which creates an "Example" project (an MZI) and exits, then open and Run it in the GUI:

   photonforge-server --example
   

   If this fails with Library 'Abstract Components' version <x> not found, that matching library isn't published in your environment - skip --example and seed a small project via the SDK instead (see reference).

Full server, managed-module, and GUI-schematic-backing detail is in the reference.

Reference Routing

Read references/projects-and-server.md before configuring photonforge-server for the GUI, making a parametric module importable, backing a GUI schematic with a component, seeding a PDK library, or debugging a GUI recompute error. It carries the connection, project-lifecycle, server, module-import, GUI-backing, and PDK-seeding patterns in full.

Workflow

1. Connect. Just start calling photonforge.pda (it connects automatically); wrap script work in try / finally with pda.stop(). Confirm identity with pda.user_info().
2. Browse. pda.list_projects(...) (filter by name / visibility / role) and pda.list_libraries(...).
3. Create or load. pda.create_project(name, description=...), or pda.load_project(name=... | project_id=...); load an immutable snapshot with version=... (or a named tag=...).
4. Work in the project. Import a PDK with project.add_library(name, version=version) (version is keyword-only; a positional second arg raises TypeError) and set pf.config.default_technology; save a component with project.add(comp, tag="draft"); revise with project.update(comp) (matched by component NAME — keep the name stable); snapshot immutably with project.add_version("1.0.0", target=comp.name) (or whole-project project.add_version("1.0.0")); reload with project.load(name, version=...); return a snapshot to editable head with load_latest().
5. Set up the GUI for parametric recompute / simulation: run photonforge-server with the code importable (above + reference).
6. Back a GUI schematic so a teammate opens a link and runs it: wrap the component as a @pf.parametric_component with promoted reference ports and an activated model, make it importable, and save_module(). Five conditions must hold — see the reference.
7. Share / clean up. Publish as a library for others to import; inspect with project.list_permissions(); project.retire([...]) / pda.retire_project(project_id=...) (versioned projects retire cleanly in 1.5.0; a 409 means the target is protected another way, e.g. published as a shared library).

Common Failure Checks

• GUI No module named '<module>' on recompute → the server can't import the user's code. Set PYTHONPATH or use the managed module + save_module(), and verify the import at the CLI in the server's environment.
• GUI Component '<x>' has no active model → an augmented component (copy + attached model) still points at the base layout; set parametric_function = None before project.add(...).
• GUI only reference ports can be added / has no ports → the schematic is backed by a component whose ports were added directly; wrap it so every port and terminal is a promoted reference port.
• GUI 'NoneType' object has no attribute 'items' in model handling → a model was added but not activated; pf.CircuitModel() auto-activates, others need activate_model(...).
• project.update(...) changed the wrong thing → PDA matches by NAME; rebuild or edit with the same component name.
• Auth failure or nothing visible → the API key is not configured (run PhotonForge Getting Started). Only for a multi-account user is it a profile mismatch.
• add_library(name=...) errors "N projects matching" → duplicate library names in the account; pass library_id= from list_libraries() instead.
• pda.retire_project(...) returns 409 → the target is protected (e.g. published as a shared library); add_version alone no longer blocks retire in 1.5.0.