Skip to content

Schema and versioning

A Simulation serialises to JSON against a versioned schema. This solver-wire format is shared by the SDK, phsolver, cloud service and desktop application. They return the same RunResult structure. Numerical comparisons also require matching engine revisions and settings. See Engine provenance.

The schema this build documents is 1.22.0-alpha.1. Check your installed SDK:

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

Released SDKs can lag this reference, which is built from the current source.

The wire format

Use port_sim from the Quickstart's port example. Compare the solver inputs rather than the Python objects:

wire = port_sim.to_wire_json()
loaded = ph.Simulation.from_wire_json(wire)
assert loaded.to_wire_dict() == port_sim.to_wire_dict()

to_wire_json() and to_wire_dict() produce what the engine consumes. from_wire_json() reads it. Prefer these to generic model_dump_json() for solver inputs. sim.to_file() and Simulation.from_file() use the same wire contract with a JSON path, with one difference: to_file() keeps an explicit dft_shutoff=0, which to_wire_json() omits. A scene reloaded from to_wire_json() text therefore takes the default stop rule on a local CPU run, and one reloaded with from_file() keeps the rule it was saved with. The Workbench does not keep it: a file opened there takes the default rule in the Run dialog, and Save removes the value, even when the file holds it.

Preserve authoring state and results

Wire JSON is not a lossless authoring archive. It omits declarative setup fields such as domain, mesh, ports and wavelengths, plus origin_um. Sources and monitors are already resolved for the solver's corner frame. Loading that JSON does not recover the declared ports or the user's frame. Keep the Python construction script to rebuild and edit a declarative scene.

Current-source run_local writes client.json beside sim.json. Keep the whole output directory. RunResult(directory) uses that matching record to restore the frame, symmetry expansion and port readout. convert_to_hdf5 also packs the record. Cloud clients keep it beside the result cache, and resume restores it; from another machine pass simulation=sim. A mismatched record warns and is ignored. Older results without it retain wire-frame behavior. A restored result simulation refuses with_changes. Boundary helpers keep the saved setup only when they leave each open boundary layer unchanged. Changes to a layer kind or count, and mesh or source helpers, ask you to rebuild from the original inputs or apply the helper before running.

Desktop workspace recovery preserves applied edits and run history. It does not replace backups or the construction script. A portable simulation JSON is useful for solver inputs, but has the authoring-state limits above.

Versioning rules

  • Minor bump: additive optional wire fields. Defaults preserve previous meaning wherever compatibility is intended.
  • Major bump: a breaking wire change. It requires a documented migration path and client/engine tests.
  • Unknown or invalid fields fail validation. Typos are errors.

There is no migration module yet

The SDK does not ship photonhub.migrations. An incompatible major version is rejected. Do not rely on an automatic migration.

Validation

Construction checks structural and cross-field rules. The SDK resolves meshes, cell counts and timesteps, checks dispersion stability, and rejects unsupported full-tensor combinations. check_runnable() also checks sources, boundary slabs and monitor positions before local or cloud execution.

These checks do not replace phsolver validate. The selected engine is still authoritative, including backend-specific limits. Available device memory, capacity and entitlement need engine or cloud preflight. See Troubleshooting for the error types.

Pinning

The scene carries schema_version, so incompatible inputs fail validation. Also record the SDK version, engine provenance and numerical settings. Schema compatibility alone does not rule out engine-version skew.