Install¶

The Python SDK¶

The SDK is Apache-2.0 and published on PyPI. Python 3.11 or newer is required. Check the version before creating .venv. If Python is missing or the version is older than 3.11, install Python 3.11 or newer, open a new terminal, and check again. If .venv was created with an older Python, delete it before trying again; creating it over the old directory keeps the old interpreter. On macOS or Linux, run rm -rf .venv. On Windows, run rmdir /s /q .venv in Command Prompt or Remove-Item -Recurse -Force .venv in PowerShell. The .venv folder is hidden in Finder because its name starts with a dot.

On macOS or Linux, check:

python3 --version

If the newer Python has a versioned name (for example python3.12), use that name in the version check and environment command instead of python3.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install photonhub

For this published package, pip on an older Python reports No matching distribution found for photonhub.

On Windows, in Command Prompt or PowerShell, check:

py -3 --version

If py is not found, install Python from python.org with its launcher. py -3 --version must report 3.11 or newer.

py -3 -m venv .venv

Run Python as .venv\Scripts\python.exe, or activate the environment with .venv\Scripts\activate.bat in Command Prompt or .venv\Scripts\Activate.ps1 in PowerShell (which the default script policy may refuse); the path form always works.

.venv\Scripts\python.exe -m pip install photonhub

For later pip commands on Windows, use .venv\Scripts\python.exe -m pip. Run photonhub as .venv\Scripts\photonhub.exe unless the environment is activated.

The same source is mirrored at Leapfield/photonhub-sdk; use the mirror's source installation instructions when you need a revision that has not been released yet.

Verify: start python in the activated environment, or .venv\Scripts\python.exe on Windows, then enter:

import photonhub as ph
print(ph.__version__, ph.SCHEMA_VERSION)

The printed values describe your install. These guides require photonhub 0.1.4 or later; upgrade with python -m pip install -U photonhub after activation, or .venv\Scripts\python.exe -m pip install -U photonhub on Windows. The reference is generated from the current source and can list features newer than the latest release. Use the public source mirror only when you need that revision.

Optional extras¶

The base install covers scene construction, validation, cost estimation, mode solving, and result handling. Extras unlock specific workflows:

Extra	Pulls in	Needed for
`gds`	`gdstk`	`ph.import_gds`, `ph.export_gds`
`hdf5`	`h5py`	`ph.convert_to_hdf5`
`viz`	`plotly`, `ipywidgets`, `shapely`	3D plots, `interactive_preview`
`mcp`	`mcp`	the `photonhub-mcp` agent-tool server
`server`	`fastapi`, `uvicorn`	the `photonhub-serve-viz` HTTP viewer service (loopback, unauthenticated; single-user machines only)
`notebook`	`nbformat`	notebook generation
`replicate`	`pyyaml`	YAML paper specs
`app`	`plotly`, `fastapi`, `uvicorn`, `mcp`, `h5py`, `gdstk`	everything the desktop app opens

Install one with the active environment:

python -m pip install "photonhub[gds]"

Connect an AI agent¶

Install the MCP server in the active environment:

python -m pip install "photonhub[mcp]"

Add this server entry to an MCP client's configuration:

{"mcpServers": {"photonhub": {"command": "photonhub-mcp"}}}

Call capabilities first to see the local solver and device support. Then use validate_spec before a run. See Agents and the MCP server for the full workflow.

The solver¶

Executing a simulation needs phsolver, the compiled FDTD engine. It is proprietary and distributed separately. Installing or importing the SDK does not automatically download it. An explicit photonhub install-solver --url command makes a network request to obtain an invited headless archive. Local CPU simulation does not contact the cloud service.

ph.find_solver() locates it, in this order:

An explicit solver_path= argument.
The PHOTONHUB_SOLVER environment variable.
A recorded solver install or link.
PATH.
An eligible build/phsolver in an engine source checkout.

An invalid explicit path or environment override raises SolverRunError rather than trying the next entry. The source-build eligibility check can require the current checkout revision.

print(ph.find_solver())  # selected path, or None if no engine is available

If that returns None, you have the SDK but no engine. Everything that does not step fields still works.

Getting a solver binary

Packaged solver archives are distribution-gated: they go to invited beta participants, with a SHA-256 checksum, under the Community Beta terms included in the archive. See Headless solver for the verify-and-install steps, or Desktop app for the GUI bundle, which carries its own solver.

Access is requested at leapfield.ai. There is no uninvited public signup.

Remote GPU¶

No extra install: ph.cloud ships in the base SDK. It needs a service URL and an API key, issued to an already-authenticated beta account. See Cloud GPU runs.

Checking your install¶

import photonhub as ph

print(ph.__version__, ph.SCHEMA_VERSION)
print(ph.find_solver())              # None if no engine is installed
print(len(ph.materials.MATERIALS))   # built-in dispersive materials

If setup fails, see Troubleshooting. Check Known limitations before comparing engines. Beta help: beta@leapfield.ai.