Quickstart

This guide walks through running your first PIC verification with Photoniq — from installation to reading your verification report. Estimated time: 20–30 minutes.

You'll need an active Photoniq account (sign up free) and a GDS-II layout file with a SPICE netlist to follow along.

Step 1 — Install the CLI

The Photoniq CLI is the fastest way to submit verification jobs from your terminal. It also installs the Python SDK as a dependency.

# Install via pip (Python 3.9+)
pip install photoniq

# Verify installation
photoniq --version
# → photoniq-cli 1.4.2

Step 2 — Authenticate

Generate an API key from your Photoniq dashboard under Settings → API Keys. Then authenticate the CLI:

photoniq auth login --api-key YOUR_API_KEY

# Or set as environment variable
export PHOTONIQ_API_KEY=YOUR_API_KEY

The API key is stored in ~/.photoniq/credentials. To verify your authentication:

photoniq auth status
✓ Authenticated as: [email protected]
✓ Plan: Starter (5 runs remaining this month)

Step 3 — Import your GDS and run verification

Point the CLI at your GDS-II layout file, SPICE netlist, and PDK identifier. The verify command handles import and job submission in one step:

photoniq verify \
  --gds ./layout/pic_top.gds \
  --netlist ./sim/pic_top.spi \
  --pdk AIM_300mm_v3.1 \
  --wait

# --wait polls until complete and prints summary

Output during verification:

✓ GDS parsed: 847 cells, 12 top-level ports
✓ Netlist loaded: 14 nets, 8 devices
Job PNQ-2A8F queued — estimated 8–12 min
● Running LVS engine...
✓ LVS complete (3m 12s)
● Running optical loss engine...
⚠ 2 warnings found
✗ 1 error found
Report ready: PNQ-2A8F (10m 44s total)

Step 4 — Read the verification report

Download the full report in your preferred format:

# Download JSON report (for CI/CD integration)
photoniq report download PNQ-2A8F --format json

# Download HTML report (for team review)
photoniq report download PNQ-2A8F --format html

# Open HTML report in browser immediately
photoniq report open PNQ-2A8F

Understanding the report

The report summary shows three counts: errors (blocking — must resolve before tape-out), warnings (review recommended), and passed checks.

Each error entry includes:

error_type — the specific rule that failed (e.g. MODE_MISMATCH)
cell — full hierarchy path in the GDS (e.g. TOP/edge_coupler_v2/wg_taper)
layer — GDS layer name and number (e.g. Si_core (1/0))
coordinate — GDS coordinate in microns
message — plain-language description of the violation
suggested_fix — actionable geometry fix recommendation

Next steps

Now that you've run your first verification:

Read the API Reference for programmatic integration
Set up CI/CD integration for automated verification on every layout commit
Configure a custom PDK if you're using a process not in the standard library