Host prediction tools

This runnable example adds deterministic charges, dipole arrows, density and a six-frame trajectory to an unchanged input crystal in a Web Worker. Set a delay to try cancelling or restarting work, or enable failure to verify that the previous result remains available. No model download or server is needed.

Integrate a host tool

Import structure_host_tool and StructureToolProps from matterviz/structure (also exported from matterviz). Register your Svelte component before mounting viewers, and restore the registration when your host unmounts.

const run = start_run({
  model: 'my-model', version: '1.0',
  units: { charge: 'e', density: 'e/A^3' },
  settings: { seed: 0 },
})
const result = await predict(run.structure, { signal: run.signal })
run.on_overlay({
  site_properties: result.site_properties,
  volumes: result.volumes, // each field needs a stable, unique field_id
  color_property: 'charge',
})

Each run receives a snapshot of its input; treat it as read-only. Each new run aborts the previous run. Its callbacks cannot change or clear newer results, and input changes or viewer unmounting invalidate it. Use run.cancel() to abort and clear, run.clear() to clear its outputs, and run.on_view(null) to return from a host view. Supply show_host_tool: false to nested structure viewers.

Use the export pane to download the prediction JSON, including the captured input, properties, density grids and provenance, or export the original structure in the usual formats. Reuse a field ID only while its physical quantity, units and normalization stay compatible; change the ID when those semantics change. Labels, order and grid resolution can change without losing surface appearance, including extra or deliberately removed layers. Reset prediction surfaces restores defaults. Hidden-density notices offer direct cell and supercell recovery actions.

Prediction metadata must contain plain JSON objects, arrays, strings, booleans, finite numbers or null. Undefined object fields are omitted. Convert Maps, Sets, Dates and typed arrays explicitly; unsupported values report their field path. Density values use Float64Array, are copied on publication, and must not be written concurrently while copying shared storage. Grid geometry is validated and cached statistics are recomputed.

Drop an exported prediction JSON onto any Structure viewer to reopen its input, properties, density and provenance. Hosts can also import prediction_from_json from matterviz/structure and pass its result as the viewer's prediction prop. Import accepts version 1 only and restores the original cell and 1×1×1 scaling.

To measure larger grids locally, open /test/isosurface-performance?size=128 and click Benchmark prediction. The page records three publication timings, export time and bytes, alongside the existing geometry/render timings and heap sampling.