Engineering

Assistant control (MCP)

Photonica ships an MCP server, so an AI assistant can build benches, take measurements, run the optimiser and look at the result — on the copy of Photonica running in front of you.

Setup

Point your assistant at photonica-mcp.exe from the unzipped folder.

# Claude Code
claude mcp add photonica -- "C:\path\to\Photonica\photonica-mcp.exe"

// Claude Desktop — claude_desktop_config.json
"mcpServers": {
  "photonica": { "command": "C:\\path\\to\\Photonica\\photonica-mcp.exe" }
}

The bridge talks to a Photonica window that is already open, and starts one if it is not. Set PHOTONICA_EXE to point at a particular build if you keep more than one.

Conventions an assistant needs

Millimetres and degrees throughout. The source is at x = 0 firing along +x, the beam height is y = 100, z is sideways.
A part's optical axis is its local +x. yaw_deg turns about vertical, pitch_deg tips the axis up, roll_deg spins it.
R1/R2: 0 is flat, positive means the centre of curvature lies toward +x.
Focus distances are reported from the last lens's own position.

The tools

Tool	Does
`get_state`	The whole bench plus current measurements. Call it first, and after changes
`measure`	Just the numbers: focus per colour, spots, chromatic shift, detector
`get_report`	The full raw JSON report including traced ray paths and Monte-Carlo statistics
`load_demo`	Open one of the 17 demos by index or name
`new_bench`	Start empty
`add_part`	Add a lens, prism, mirror, polariser, grating… and set any of its fields
`update_part` + `remove_part`	Change or delete a part by index
`add_screen`	`update_screen`, `remove_screen` — up to four screens
`update_source`	Type, spectrum, wavelength, beam width, power, polarisation, placement
`set_camera` / `set_view`	Frame the viewport; toggle photo mode, haze, exposure, wave screens, panels
`light_in_flight`	Freeze or play the pulse, and choose what the screens show
`inspect_ray`	One ray, surface by surface: angles, Fresnel R/T, timing, Stokes vector
`autofocus`	Move the screen (or a lens) to best focus
`optimize`	Run damped least squares with your variables and operands
`tolerance`	Monte-Carlo tolerancing with yield and worst offenders
`screenshot`	Look at the bench — returns an image
`render_video`	Render the timeline to mp4
`add_key` / `clear_keys`	Camera keyframes
`save_project` / `open_project` / `set_bench`	Files and whole-bench replacement
`undo` / `redo`	Step the assistant’s own edits back and forward

Gotchas worth knowing

Angle conventions differ by element. A source's polarisation_deg is from horizontal; a polariser's or wave plate's axis_deg is from vertical.
inspect_ray angles are relative to the local surface normal, which tilts on a curved surface. Do not read an exit angle as an angle to the optical axis.
The detector block disappears when almost no light lands (fewer than 50 photons). That is the correct answer for crossed polarisers, not a bug.
Posts are solid. A part lifted high above the beam will be blocked by its own mounting post.