Metadata-Version: 2.2
Name: photonforge
Version: 2.0.0
Summary: PhotonForge is a design tool that integrates with foundry PDKs to speed up the design, simulation, and verification cycle for optical components and systems.
Author-Email: "Flexcompute Inc." <support@flexcompute.com>
Project-URL: homepage, https://www.flexcompute.com/
Project-URL: documentation, https://docs.flexcompute.com/projects/photonforge/
Requires-Python: >=3.10
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.15
Requires-Dist: tidy3d[trimesh]<2.13,>=2.12.0
Requires-Dist: cryptography==48.0.1; platform_system == "Darwin" and platform_machine == "x86_64"
Requires-Dist: pydantic<3,>=2.9
Requires-Dist: packaging>=23
Requires-Dist: uvicorn>=0.34
Requires-Dist: fastapi>=0.115
Requires-Dist: automerge==0.2.0.dev4
Requires-Dist: base58
Requires-Dist: httpx[http2]>=0.28
Requires-Dist: websockets>=16.0
Provides-Extra: dev
Requires-Dist: build>=1.3; extra == "dev"
Requires-Dist: ipykernel>=6.10; extra == "dev"
Requires-Dist: ipywidgets>=8.0; extra == "dev"
Requires-Dist: jsonschema>=4.25; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.2; extra == "test"
Requires-Dist: gdstk>=0.9.61; extra == "test"
Requires-Dist: scipy>=1.7; extra == "test"
Requires-Dist: httpx>=0.28; extra == "test"
Provides-Extra: xarray
Requires-Dist: xarray; extra == "xarray"
Provides-Extra: plotting
Requires-Dist: matplotlib; extra == "plotting"
Provides-Extra: numba
Requires-Dist: numba>=0.60; extra == "numba"
Provides-Extra: docs
Requires-Dist: sphinx<8.2.0; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: nbformat; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: ipython; extra == "docs"
Requires-Dist: ipywidgets; extra == "docs"
Requires-Dist: scikit-rf; extra == "docs"
Requires-Dist: bayesian-optimization>=2.0.0; extra == "docs"
Provides-Extra: notebooks
Requires-Dist: ipython; extra == "notebooks"
Requires-Dist: ipywidgets>=8.0; extra == "notebooks"
Requires-Dist: luxtelligence-lnoi400-forge>=2.0; extra == "notebooks"
Requires-Dist: matplotlib; extra == "notebooks"
Requires-Dist: optax; extra == "notebooks"
Requires-Dist: pandas; extra == "notebooks"
Requires-Dist: rich; extra == "notebooks"
Requires-Dist: scikit-rf; extra == "notebooks"
Requires-Dist: siepic-forge<1.3,>=1.2.1; extra == "notebooks"
Description-Content-Type: text/markdown

# PhotonForge

PhotonForge is a design tool that integrates with foundry PDKs to speed up the
design, simulation, and verification cycle for optical components and systems. 


## Documentation

The online documentation can be found
[here](https://docs.flexcompute.com/projects/photonforge/).


## Installation

```sh
pip install photonforge
```

Circuit time steppers run on the built-in C++ kernel. With numba installed,
`pip install "photonforge[numba]"`, and a [license](#license), setup compiles
each circuit structure into one numba function instead, which steps faster
with the same results.
numba is optional because each release supports a bounded range of numpy
versions and some platforms (musllinux, and Intel macOS for recent releases)
have no numba wheels. `photonforge.config.compile_circuit_time_steppers`
turns compilation off.


## License

Native time stepping, Verilog-A export and Calibre DRC need a PhotonForge
Photonic Canvas license. Native time stepping runs whole time series in
compiled code: time steppers in C++, circuits calling their instances
directly, and circuits compiled with numba. Without the license, time steppers
compute the same results one sample at a time, more slowly, and
`CircuitTimeStepper(require_native=True)` raises `PermissionError`.


## Layout Verification

`drc_check` and `lvs_check` run KLayout (0.29.12 or newer) DRC and LVS, or
Calibre DRC, on a component or layout file and return the markers, netlists and
comparison results as Python objects. The LVS schematic can be written from the
component's own netlist. The `engine` argument selects the verification engine.
See [docs/verification.md](docs/verification.md).


## Notebook LiveViewer

LiveViewer accepts Components, References, 2D structures, and GDSII/OASIS paths
and renders native viewport packets with WebGL2. References and structures are
held in a `LiveViewer Support` component; references retain their technology,
array repetitions, and element identity, while standalone structures use an
empty technology. In IPython, the most recent Component is rebuilt 100 ms after
successful cell execution. A following
cell cancels the pending rebuild, so queued runs publish only their final state.
Direct mutations and rebinding its public notebook variable both update the
viewer. Configure the delay with
`LiveViewer(auto_refresh_delay=0.1)`, or disable refresh with
`LiveViewer(auto_refresh=False)`. `LiveViewer(verbose=False)` prints nothing,
including port and refused-edit notices. An untouched viewer has no Component and does
not select a default technology; its first design edit creates one. Opening a
file path, including from the browser, stops Component auto-refresh only after
that file scene publishes
successfully; canceled and failed opens resume any pending refresh.
Server host, proxy allowlist, and edit autosave defaults live in tidy3d's
`[plugins.photonforge]` configuration as `live_viewer_host`,
`live_viewer_allowed_hosts`, and `live_viewer_autosave`. Environment overrides
use `TIDY3D_PLUGINS__PHOTONFORGE__<KEY>`. In VS Code in the browser (code-server),
the viewer also allows the host in `VSCODE_PROXY_URI` and prints its address under
that proxy.
The Component Library's PDKs button lists the PDKs installed in the
environment, found when its dialog first opens: packages with a
`photonforge.pdk` entry point, or `*-forge` packages that require photonforge
or the Cadence connector. Nothing loads until added there, the abstract blocks
included. Public PDKs not installed can be installed from the dialog, pinned
to the running photonforge version.
Small cell instances switch from exact vectors at a fixed 8-CSS-pixel threshold
to subtree-atlas and density rendering. Over-budget placement-free flat layouts
use a bounded layer-aware field while close views remain exact. File-backed
axis-aligned rectangles use compact PHVS storage and first-touch checked mmap
chunks without changing exact
rendering or picking. Middle-tier cells use complete exact boundaries when
available; isolated atlas levels preserve subpixel tiles without cross-cell
bleed. Nonresident boundary assets remain bounded. After interaction settles,
bounded native raster tiles
progressively replace previews only when complete; failed or incomplete regions
retain the preview. Exact vectors and refined tiles preserve native scene-layer
order. Layout-file paths are not watched.

The inspector's DRC section (`photonforge/_live_viewer/drc.py`,
`live-viewer/src/js/drc.js`):

- **Run DRC** runs `pf.drc_check` on the design on screen with the runset
  chosen for the engine: KLayout's `.drc` or `.lydrc`, or Calibre's SVRF rule
  deck (any suffix). The design is saved as GDS (the file the engine checks)
  and the results (a `.lyrdb`, or Calibre's ASCII `.db`) are written beside it
  in `./drc/`. Calibre runs hierarchically (`-hier`), checking the design from
  its top cell (`top_level`), and a GDS file on screen from the deck's
  `LAYOUT PRIMARY`, else its top cell.
  Arguments, other paths and a marker limit are `pf.drc_check`'s, from Python
  (or `/api/drc/run`). The message bar shows the run's progress, as it does a
  route's, and editing goes on meanwhile: the check is of the GDS saved when
  the run started. When it ends, the results load in the page that ran it and
  the bar says what they hold, or why the run failed.
- **Engine** chooses KLayout or Calibre (first: `default_drc_lvs_engine` when
  found, else the first found), each with its own runset, and shows the version
  of the executable a run uses (path on hover), found as `pf.drc_check` finds
  it. Without one, Run DRC is disabled under the message saying so (and a link
  to KLayout's downloads).
- **Results** reads a KLayout (`.lyrdb`) or Calibre (`.db`, told by its
  contents; no Calibre needed) DRC report with `pf.load_drc_results`,
  from this layout or another, and lists its markers by rule or by cell, under
  the style they are drawn in (stroke color and width, fill color). Boxes and
  paths are drawn as polygons, a text as a dot, and a marker that is a bare
  value is listed nowhere. Nothing is drawn until a rule, cell or marker is
  picked; an edge pair is drawn as the loop its edges make, and a marker too
  small to see as a dot. The arrow keys step through the list.
- A deep (hierarchical) run reports a marker once, in its cell: it is drawn at
  every placement of that cell in the design, except in a cell variant (one
  KLayout split off for a magnified placement, or by orientation), drawn at the
  report's example placement (`DRCResults.cells`), as KLayout's marker browser
  draws it. A cell placed more than 1,000 times (an array, say) is drawn at the
  first 1,000, its markers repeating at the rest: the panel gives the count of
  all. A GDS file opened to view has no design to search: its cells are drawn
  at the report's example placements.
- A marker picked is visited, for as long as the report is shown; the report's
  file is not changed.
- A report stays with the design it was found on, through edits and undo.
  Another design or file shown (opened, displayed or refreshed from the
  notebook) puts it away, and a run's results are not loaded onto one shown
  after the run started: loading their file by path draws them on it.
- Agents use `/api/drc`, `/api/drc/run`, `/api/drc/dismiss`, `/api/drc/load`,
  `/api/drc/report`, `/api/drc/markers` and `/api/drc/flags` (see `/api/help`).


## Usage Data

PhotonForge sends usage data to Flexcompute when it is imported and when a
license check fails: the PhotonForge, operating system and Python versions, and
the license required. It is sent with your Tidy3D API key when one is
configured; otherwise it is anonymous. Set `remote_logging = false` in the
`[plugins.photonforge]` section of tidy3d's configuration to stop sending it.


## Development docs:

- [docs/development.md](docs/development.md): local development setup.
- [docs/architecture.md](docs/architecture.md): general code structure and
  architecture.
- [docs/spice.md](docs/spice.md): configured `TimeStepper` Verilog-A export guide.
- [docs/verification.md](docs/verification.md): DRC and LVS checks with KLayout
  and Calibre.
- [docs/testing.md](docs/testing.md): testing infrastructure.
- [docs/deployment.md](docs/deployment.md): how to release a new version.
