FE-1536: Contour surface for optimization studies with local recompute (#9398)

Author: kube

.changeset/optimization-surface.md

@@ -0,0 +1,6 @@
+---
+"@hashintel/petrinaut": patch
+"@hashintel/ds-components": patch
+---
+
+Optimization studies with two or more optimized numeric parameters gain a Surface section: a contour of the objective over two chosen parameters, computed locally against the study's frozen model, with the study's trials as markers. Sliders and clicks move the selected point, which refines with escalating batches. `Slider` accepts `step` and `onChangeEnd`.

libs/@hashintel/ds-components/src/components/Slider/slider.tsx

@@ -23,27 +23,33 @@ export interface SliderProps {
   style?: React.CSSProperties;
   min?: number;
   max?: number;
+  step?: number;
   value?: number;
   defaultValue?: number;
   label?: string;
   showValueText?: boolean;
   onChange?: (value: number) => void;
+  /** Fires once when a drag or keyboard interaction settles. */
+  onChangeEnd?: (value: number) => void;
 }
 
 export const Slider: React.FC<SliderProps> = ({
   className,
   style,
   min,
   max,
+  step,
   value,
   defaultValue,
   label,
   showValueText = false,
   onChange,
+  onChangeEnd,
 }) => {
   return (
     <BaseSlider.Root
       min={min}
+      step={step}
       className={cx(
         css({
           position: "relative",
@@ -64,6 +70,12 @@ export const Slider: React.FC<SliderProps> = ({
           onChange?.(newValue);
         }
       }}
+      onValueChangeEnd={(details) => {
+        const newValue = details.value[0];
+        if (newValue !== undefined) {
+          onChangeEnd?.(newValue);
+        }
+      }}
     >
       {label && (
         <BaseSlider.Label

libs/@hashintel/petrinaut/docs/optimization.md

@@ -88,6 +88,25 @@ connection reports how many of the requested trials had completed and includes
 a diagnostic identifier for support. Trials received before the failure are
 kept, and a **Retry** action starts a fresh run with the same settings.
 
+## The surface view
+
+A study with two or more optimized numeric parameters grows a **Surface**
+section at the bottom of its drawer: an Optuna-style contour of the objective
+over two parameters you pick. The study's own trials appear as rings (the best
+trial highlighted), and the filled contour comes from points **computed
+locally on your machine** — the study's model snapshot runs on a background
+worker, a few runs per point, and the plot fills in coarse shape first.
+
+One slider per optimized parameter navigates the space; parameters not shown
+on the plot hold at their slider position, which starts at the best trial's
+value. Move a slider or **click the plot** and the selected point recomputes
+with escalating batches while the readout streams the objective's mean and
+median. Points you have visited are cached, so returning to them is instant.
+
+Log-scale domains slide in log space, and integer domains snap to their step.
+Local points always reflect the model as it was when the study launched, even
+if you have edited the net since.
+
 ## Connection drops and reloads
 
 An optimization runs on the server, not in your browser tab. If the connection

libs/@hashintel/petrinaut/src/react/experiments/context.ts

@@ -7,6 +7,7 @@ import type {
 import type { SweepCellSnapshot, SweepSelection } from "./sweep-session";
 import type {
   AdHocScenarioState,
+  SDCPN,
   MonteCarloExpressionMetricSpec,
   MonteCarloMetricSpec,
   MonteCarloUserDefinedMetricFrame,
@@ -201,9 +202,37 @@ export type ExperimentsContextValue = {
    */
   sampleSweepCell: (
     experimentId: string,
-    parameterValues: Readonly<Record<string, number>>,
+    position: Readonly<Record<string, number>>,
     minRuns: number,
   ) => Promise<SweepCellSnapshot | null>;
+  /**
+   * Computes one metric sample against an arbitrary net snapshot, on the
+   * background single-worker lane — the optimization surface's local compute
+   * path, which must run a study's frozen model rather than the live editor
+   * net. Batches are serialized; compilation is cached per `cacheKey`.
+   * Resolves null when the batch is refused or fails (a hole in the surface,
+   * not an error).
+   */
+  sampleDetachedObjective: (
+    request: DetachedObjectiveRequest,
+  ) => Promise<SweepCellSnapshot | null>;
+};
+
+/** One local compute batch for an optimization study's objective. */
+export type DetachedObjectiveRequest = {
+  /** Compile-cache identity; one study keeps one compiled snapshot. */
+  cacheKey: string;
+  /** The frozen model snapshot to run (not the live editor net). */
+  definition: SDCPN;
+  scenarioId: string;
+  /** Parsed values for every scenario parameter (bindings plus navigation). */
+  scenarioParameterValues: Readonly<Record<string, number | boolean>>;
+  /** The study's objective metric, evaluated as an expression metric. */
+  metric: { id: string; label: string; code: string };
+  seed: number;
+  runCount: number;
+  dt: number;
+  maxTime: number;
 };
 
 const DEFAULT_CONTEXT_VALUE: ExperimentsContextValue = {
@@ -216,6 +245,7 @@ const DEFAULT_CONTEXT_VALUE: ExperimentsContextValue = {
   removeExperiment: () => {},
   setSweepSelection: () => {},
   sampleSweepCell: () => Promise.resolve(null),
+  sampleDetachedObjective: () => Promise.resolve(null),
 };
 
 export const ExperimentsContext = createContext<ExperimentsContextValue>(

libs/@hashintel/petrinaut/src/react/experiments/provider.tsx

@@ -16,6 +16,7 @@ import {
   type MonteCarloExperimentState,
   getDefaultMonteCarloShardCount,
   type WorkerFactory,
+  DEFAULT_PETRINAUT_EXTENSIONS,
   type Scenario,
   type ScenarioParameter,
 } from "@hashintel/petrinaut-core";
@@ -48,6 +49,7 @@ import {
   type ExperimentsContextValue,
   isExperimentActive,
   isTerminalExperimentStatus,
+  type DetachedObjectiveRequest,
 } from "./context";
 import {
   buildParameterAxis,
@@ -58,6 +60,7 @@ import {
 import {
   createSweepSession,
   type SweepSession,
+  type SweepCellSnapshot,
   type SweepSessionUpdate,
 } from "./sweep-session";
 
@@ -259,6 +262,24 @@ export const ExperimentsProvider: React.FC<ExperimentsProviderProps> = ({
     new Map<string, PendingExperimentRegistration>(),
   );
   const sweepSessionsRef = useRef(new Map<string, SweepSession>());
+  /** Serializes detached objective batches on one background worker. */
+  const detachedChainRef = useRef<Promise<unknown>>(Promise.resolve());
+  const detachedCpuBackendRef = useRef<ExperimentBackend | null>(null);
+  const detachedCompileCacheRef = useRef(
+    new Map<
+      string,
+      Promise<{
+        scenario: Scenario;
+        scenarioHir: Awaited<ReturnType<typeof requestScenarioHir>>;
+        artifacts: Awaited<ReturnType<typeof requestHirArtifacts>>["artifacts"];
+        metricArtifact: NonNullable<
+          Awaited<
+            ReturnType<typeof requestHirArtifacts>
+          >["artifacts"]["metrics"][string]
+        >;
+      }>
+    >(),
+  );
   const [experiments, setExperiments] = useState<ExperimentRecord[]>([]);
   const selectedExperimentId =
     navigation.state.simulateResource?.type === "experiment"
@@ -1019,6 +1040,145 @@ export const ExperimentsProvider: React.FC<ExperimentsProviderProps> = ({
       .get(experimentId)
       ?.sampleCell(parameterValues, minRuns) ?? Promise.resolve(null);
 
+  const runDetachedObjectiveBatch = async (
+    request: DetachedObjectiveRequest,
+  ): Promise<SweepCellSnapshot | null> => {
+    try {
+      // One compiled snapshot per study: the frozen definition, its scenario
+      // HIR, and its HIR artifacts never change for a given cacheKey.
+      let compiled = detachedCompileCacheRef.current.get(request.cacheKey);
+      if (!compiled) {
+        compiled = (async () => {
+          const scenario = (request.definition.scenarios ?? []).find(
+            (candidate: Scenario) => candidate.id === request.scenarioId,
+          );
+          if (!scenario) {
+            throw new Error(
+              `Scenario ${request.scenarioId} is not in the model snapshot`,
+            );
+          }
+          // The snapshot runs under default extensions, as it does on the
+          // optimizer service — the live editor's toggles do not apply to a
+          // frozen study.
+          const { artifacts, failures } = await requestHirArtifacts(
+            request.definition,
+            DEFAULT_PETRINAUT_EXTENSIONS,
+            { includeHir: false },
+          );
+          const metricArtifact = getOwn(artifacts.metrics, request.metric.id);
+          if (!metricArtifact) {
+            throw new Error(
+              failures
+                .map((failure) => failure.diagnostics[0]?.message)
+                .filter(Boolean)
+                .join("; ") || "The objective metric did not compile",
+            );
+          }
+          const scenarioHir = await requestScenarioHir(scenario);
+          return { scenario, scenarioHir, artifacts, metricArtifact };
+        })();
+        detachedCompileCacheRef.current.set(request.cacheKey, compiled);
+        compiled.catch(() => {
+          // A failed compile is retried on the next sample rather than cached.
+          detachedCompileCacheRef.current.delete(request.cacheKey);
+        });
+      }
+      const { scenario, scenarioHir, artifacts, metricArtifact } =
+        await compiled;
+
+      const compiledScenario = compileScenario(
+        scenario,
+        scenarioHir,
+        request.definition.parameters,
+        request.definition.places,
+        request.definition.types,
+        {
+          // Scenario compilation is numeric; boolean bindings arrive as their
+          // 0/1 encoding, matching how the engine stores boolean parameters.
+          scenarioParameterValues: Object.fromEntries(
+            Object.entries(request.scenarioParameterValues).map(
+              ([identifier, value]) => [
+                identifier,
+                typeof value === "boolean" ? (value ? 1 : 0) : value,
+              ],
+            ),
+          ),
+        },
+      );
+      if (!compiledScenario.ok) {
+        return null;
+      }
+
+      detachedCpuBackendRef.current ??= createWorkerPoolExperimentBackend({
+        createWorker: workerFactoryRef.current,
+        shardCount: 1,
+      });
+      const backend = detachedCpuBackendRef.current;
+
+      const abortController = new AbortController();
+      const assessment = await backend.assess({
+        sdcpn: request.definition,
+        extensions: DEFAULT_PETRINAUT_EXTENSIONS,
+        initialMarking: compiledScenario.result.initialState,
+        parameterValues: compiledScenario.result.parameterValues,
+        seed: request.seed,
+        dt: request.dt,
+        maxTime: request.maxTime,
+        runCount: request.runCount,
+        metricSpecs: [
+          {
+            kind: "expression",
+            id: request.metric.id,
+            label: request.metric.label,
+            code: request.metric.code,
+            sampleRuns: "all",
+            runOutput: { type: "distribution" },
+            artifact: metricArtifact,
+          },
+        ],
+        hirArtifacts: artifacts,
+      });
+      if (!assessment.eligible) {
+        return null;
+      }
+      const instantiated = await assessment.instantiate({
+        signal: abortController.signal,
+      });
+      if (!instantiated.ok) {
+        return null;
+      }
+      const handle = instantiated.handle;
+
+      const done = new Promise<boolean>((resolve) => {
+        const offEvents = handle.events.subscribe((event) => {
+          offEvents();
+          resolve(event.type === "complete");
+        });
+      });
+      handle.start();
+      const completed = await done;
+      const frames = handle.metrics.get().frames;
+      handle.dispose();
+      if (!completed) {
+        return null;
+      }
+      return { runsCompleted: request.runCount, metricFrames: frames };
+    } catch {
+      // A refused or failed batch is a hole in the surface, not an error the
+      // optimization view should surface.
+      return null;
+    }
+  };
+
+  const sampleDetachedObjective: ExperimentsContextValue["sampleDetachedObjective"] =
+    (request) => {
+      const next = detachedChainRef.current.then(() =>
+        runDetachedObjectiveBatch(request),
+      );
+      detachedChainRef.current = next.catch(() => null);
+      return next;
+    };
+
   const selectedExperiment =
     experiments.find((experiment) => experiment.id === selectedExperimentId) ??
     null;
@@ -1033,6 +1193,7 @@ export const ExperimentsProvider: React.FC<ExperimentsProviderProps> = ({
     removeExperiment: useStableCallback(removeExperiment),
     setSweepSelection: useStableCallback(setSweepSelection),
     sampleSweepCell: useStableCallback(sampleSweepCell),
+    sampleDetachedObjective: useStableCallback(sampleDetachedObjective),
   };
 
   return (