feat(invariant-set-approximation): add invariant set approximation from initial point circle

Author: namvdo

frontend/src/Anton.tsx

@@ -78,13 +78,15 @@ import {
 import {
     CONTINUOUS_BOUNDARY_FLOW_SETTINGS,
     DEFAULT_GEOMETRIC_OFFSET_SETTINGS,
+    DEFAULT_INVARIANT_SET_SETTINGS,
     DEFAULT_MANIFOLD_SETTINGS,
     DEFAULT_ULAM_SETTINGS,
     INVERSE_OFFSET_POSITION_TOLERANCE_RULE,
     ULAM_OPERATOR_SETTINGS,
     continuousUlamIntegrationTime,
     inverseOffsetPositionTolerance
 } from './config/numericalSettings';
+import { randomHenonInvariantSeed } from './utils/invariantSetSeed';
 import {
     buildExperimentBundle,
     experimentConfigurationToUiState,
@@ -105,6 +107,7 @@ import type {
     ExtendedPointTuple,
     ExtendedState,
     GeometricOffsetState,
+    InvariantSetState,
     Manifold,
     ManifoldBranch,
     ManifoldState,
@@ -510,6 +513,16 @@ const SetValuedViz = () => {
         };
     });
 
+    const [invariantSetState, setInvariantSetState] = useState<InvariantSetState>({
+        seedMode: 'manual',
+        boundaryPointCount: DEFAULT_INVARIANT_SET_SETTINGS.boundaryPointCount,
+        forwardIterations: DEFAULT_INVARIANT_SET_SETTINGS.forwardIterations,
+        showResult: true,
+        isComputing: false,
+        result: null,
+        error: null,
+    });
+
     const boundarySourceManifolds = manifoldState.manifolds;
 
     const verifiedBoundaryCycles = useMemo(
@@ -697,6 +710,7 @@ const SetValuedViz = () => {
     const periodicComputationRevisionRef = useRef(0);
     const geometricOffsetRequestIdRef = useRef(0);
     const inverseOffsetRequestIdRef = useRef(0);
+    const invariantSetRequestIdRef = useRef(0);
     const ulamDebounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
     const ulamSupportRef = useRef<SupportGrid | null>(null);
     const ulamTransitionsRequestRef = useRef(0);
@@ -2189,6 +2203,83 @@ const SetValuedViz = () => {
         }
     }, [recordingState.recordingEnabled]);
 
+    const computeForwardInvariantSet = useCallback(async () => {
+        if (dynamicSystem !== 'henon') return;
+        let seed: ExtendedState;
+        try {
+            if (invariantSetState.seedMode === 'manual') {
+                seed = { ...manifoldState.startPoint };
+            } else {
+                const position = randomHenonInvariantSeed(
+                    viewRange,
+                    params.a,
+                    params.b,
+                    params.epsilon,
+                );
+                seed = {
+                    ...position,
+                    nx: manifoldState.startPoint.nx,
+                    ny: manifoldState.startPoint.ny,
+                };
+            }
+        } catch (error) {
+            setInvariantSetState(previous => ({
+                ...previous,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+            return;
+        }
+
+        const requestId = ++invariantSetRequestIdRef.current;
+        setInvariantSetState(previous => ({
+            ...previous,
+            isComputing: true,
+            result: null,
+            error: null,
+        }));
+        try {
+            const result = await runComputeTask('computeForwardInvariantSet', {
+                seed,
+                params: { a: params.a, b: params.b, epsilon: params.epsilon },
+                domain: viewRange,
+                settings: {
+                    boundaryPointCount: invariantSetState.boundaryPointCount,
+                    forwardIterations: invariantSetState.forwardIterations,
+                },
+            });
+            if (requestId !== invariantSetRequestIdRef.current) return;
+            setInvariantSetState(previous => ({
+                ...previous,
+                isComputing: false,
+                showResult: true,
+                result,
+                error: null,
+            }));
+        } catch (error) {
+            if (requestId !== invariantSetRequestIdRef.current) return;
+            setInvariantSetState(previous => ({
+                ...previous,
+                isComputing: false,
+                result: null,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    }, [
+        dynamicSystem,
+        invariantSetState.boundaryPointCount,
+        invariantSetState.forwardIterations,
+        invariantSetState.seedMode,
+        manifoldState.startPoint.x,
+        manifoldState.startPoint.y,
+        manifoldState.startPoint.nx,
+        manifoldState.startPoint.ny,
+        params.a,
+        params.b,
+        params.epsilon,
+        runComputeTask,
+        viewRange,
+    ]);
+
     const computeGeometricOffsets = useCallback(async () => {
         if (dynamicSystem !== 'henon' || calculatedBoundaryBranches.length === 0) {
             setGeometricOffsetState(prev => ({
@@ -2420,6 +2511,31 @@ const SetValuedViz = () => {
         transitionViewRange
     ]);
 
+    useEffect(() => {
+        invariantSetRequestIdRef.current += 1;
+        setInvariantSetState(previous => ({
+            ...previous,
+            isComputing: false,
+            result: null,
+            error: null,
+        }));
+    }, [dynamicSystem, params.a, params.b, params.epsilon, viewRange]);
+
+    useEffect(() => {
+        if (invariantSetState.seedMode !== 'manual') return;
+        invariantSetRequestIdRef.current += 1;
+        setInvariantSetState(previous => ({
+            ...previous,
+            isComputing: false,
+            result: null,
+            error: null,
+        }));
+    }, [
+        invariantSetState.seedMode,
+        manifoldState.startPoint.x,
+        manifoldState.startPoint.y,
+    ]);
+
     useEffect(() => {
         geometricOffsetRequestIdRef.current += 1;
         inverseOffsetRequestIdRef.current += 1;
@@ -2445,7 +2561,7 @@ const SetValuedViz = () => {
 
         const toRemove: THREE.Object3D[] = [];
         scene.traverse(child => {
-            if (child.userData.type === 'trajectory' || child.userData.type === 'manifold' || child.userData.type === 'boundaryLayer' || child.userData.type === 'boundarySamplePoints' || child.userData.type === 'noiseBall' || child.userData.type === 'geometricOffset' || child.userData.type === 'inverseGeometricOffset' || child.userData.type === 'fixedPoint' || child.userData.type === 'bde') {
+            if (child.userData.type === 'trajectory' || child.userData.type === 'manifold' || child.userData.type === 'boundaryLayer' || child.userData.type === 'boundarySamplePoints' || child.userData.type === 'noiseBall' || child.userData.type === 'geometricOffset' || child.userData.type === 'inverseGeometricOffset' || child.userData.type === 'forwardInvariantSet' || child.userData.type === 'fixedPoint' || child.userData.type === 'bde') {
                 toRemove.push(child);
             }
         });
@@ -2511,6 +2627,37 @@ const SetValuedViz = () => {
             scene.add(samples);
         };
 
+        if (invariantSetState.showResult && invariantSetState.result?.point_sets.length) {
+            // Iteration zero is the construction circle, not a forward-projected result.
+            const projectedPointSets = invariantSetState.result.point_sets.filter(pointSet => (
+                pointSet.iteration > 0
+            ));
+            const projectedPoints = projectedPointSets.flatMap(pointSet => pointSet.points);
+            if (projectedPoints.length > 0) {
+                const geometry = new THREE.BufferGeometry().setFromPoints(
+                    projectedPoints.map(point => new THREE.Vector3(point.x, point.y, 0.31)),
+                );
+                const material = new THREE.PointsMaterial({
+                    color: new THREE.Color('#70a7c4'),
+                    size: 4,
+                    sizeAttenuation: false,
+                    transparent: true,
+                    opacity: 0.9,
+                    depthTest: false,
+                    depthWrite: false,
+                });
+                const samples = new THREE.Points(geometry, material);
+                samples.renderOrder = 15;
+                samples.userData = {
+                    type: 'forwardInvariantSet',
+                    role: 'projected-point-samples',
+                    pointSetCount: projectedPointSets.length,
+                    pointCount: projectedPoints.length,
+                };
+                scene.add(samples);
+            }
+        }
+
         if (manifoldState.showUnstableManifold && hasBoundarySamples) {
             boundaryLayers.invariantBranches.forEach(branch => {
                 if (manifoldState.showBoundarySamplePoints) {
@@ -2947,7 +3094,7 @@ const SetValuedViz = () => {
             scene.add(sphere);
         }
 
-    }, [manifoldState, geometricOffsetState, bdeState, dynamicSystem, type, viewRange, viewportRange, readViewportSize, boundaryLayers, hasBoundarySamples, hasVerifiedBoundaryCycles, params.epsilon, filters, periodicState.isReady, periodicState.orbits]);
+    }, [manifoldState, geometricOffsetState, invariantSetState, bdeState, dynamicSystem, type, viewRange, viewportRange, readViewportSize, boundaryLayers, hasBoundarySamples, hasVerifiedBoundaryCycles, params.epsilon, filters, periodicState.isReady, periodicState.orbits]);
 
     useEffect(() => {
         if (!sceneRef.current) return;
@@ -3886,6 +4033,9 @@ const SetValuedViz = () => {
                 setManifoldState={setManifoldState}
                 geometricOffsetState={geometricOffsetState}
                 setGeometricOffsetState={setGeometricOffsetState}
+                invariantSetState={invariantSetState}
+                setInvariantSetState={setInvariantSetState}
+                computeForwardInvariantSet={computeForwardInvariantSet}
                 hasBoundarySamples={hasBoundarySamples}
                 boundaryLayerError={boundaryLayers.error}
                 boundarySampling={{
@@ -3931,6 +4081,7 @@ const SetValuedViz = () => {
                 tooltip={tooltip}
                 manifoldState={manifoldState}
                 geometricOffsetState={geometricOffsetState}
+                invariantSetState={invariantSetState}
                 ulamState={ulamState}
                 hasBoundarySamples={hasBoundarySamples}
                 displayRange={viewportRange}

frontend/src/components/layout/Sidebar.test.tsx

@@ -9,6 +9,7 @@ vi.mock('../sidebar/EquationDisplay', () => ({ EquationDisplay: () => <div data-
 vi.mock('../sidebar/ParametersPanel', () => ({ ParametersPanel: () => <div data-testid="parameters-panel" /> }));
 vi.mock('../sidebar/ManifoldsPanel', () => ({ ManifoldsPanel: () => <div data-testid="manifolds-panel" /> }));
 vi.mock('../sidebar/GeometricOffsetsPanel', () => ({ GeometricOffsetsPanel: () => <div data-testid="geometric-offsets-panel" /> }));
+vi.mock('../sidebar/InvariantSetsPanel', () => ({ InvariantSetsPanel: () => <div data-testid="invariant-sets-panel" /> }));
 vi.mock('../sidebar/VisualizationPanel', () => ({ VisualizationPanel: () => <div data-testid="visualization-panel" /> }));
 vi.mock('../sidebar/StartingPoint', () => ({ StartingPoint: () => <div data-testid="starting-point" /> }));
 vi.mock('../sidebar/PeriodicOrbitsPanel', () => ({ PeriodicOrbitsPanel: () => <div data-testid="periodic-orbits" /> }));
@@ -134,6 +135,17 @@ const baseProps = {
   canComputeInverseGeometricOffsets: false,
   computeInverseGeometricOffsets: vi.fn(),
   fitInverseGeometricOffsets: vi.fn(),
+  invariantSetState: {
+    seedMode: 'random',
+    boundaryPointCount: 256,
+    forwardIterations: 100,
+    showResult: true,
+    isComputing: false,
+    result: null,
+    error: null,
+  },
+  setInvariantSetState: vi.fn(),
+  computeForwardInvariantSet: vi.fn(),
   ORBIT_COLORS: { manifold: '#e67e22', stableManifold: '#3498db' },
   filters: {
     period1: true,
@@ -231,7 +243,7 @@ describe('Sidebar', () => {
   });
 
   it('shows the starting point panel for discrete systems', () => {
-    render(<Sidebar {...baseProps} type="discrete" dynamicSystem="henon" />);
+    render(<Sidebar {...baseProps} type="discrete" dynamicSystem="duffing" />);
     expect(screen.getByTestId('starting-point')).toBeInTheDocument();
   });
 
@@ -248,6 +260,13 @@ describe('Sidebar', () => {
     expect(screen.queryByTestId('geometric-offsets-panel')).toBeNull();
   });
 
+  it('shows forward invariant-set controls only for the Hénon map', () => {
+    const { rerender } = render(<Sidebar {...baseProps} type="discrete" dynamicSystem="henon" />);
+    expect(screen.getByTestId('invariant-sets-panel')).toBeInTheDocument();
+    rerender(<Sidebar {...baseProps} type="discrete" dynamicSystem="duffing" />);
+    expect(screen.queryByTestId('invariant-sets-panel')).toBeNull();
+  });
+
   it('passes recompute controls into the bottom controls bar', () => {
     const onRecompute = vi.fn();
     render(<Sidebar {...baseProps} applyInputsAndRecompute={onRecompute} hasPendingInputChanges={true} />);

frontend/src/components/layout/Sidebar.tsx

@@ -12,6 +12,7 @@ import { AnimationPanel } from '../sidebar/AnimationPanel';
 import { ParameterSweepPanel } from '../sidebar/ParameterSweepPanel';
 import { GeometricOffsetsPanel } from '../sidebar/GeometricOffsetsPanel';
 import { ExperimentPanel } from '../sidebar/ExperimentPanel';
+import { InvariantSetsPanel } from '../sidebar/InvariantSetsPanel';
 import { InfoStrip } from './InfoStrip';
 import { ControlsBar } from './ControlsBar';
 import { BIST_VERSION } from '../../config/systems';
@@ -25,6 +26,7 @@ import type {
   CustomParameter,
   ExperimentStatus,
   GeometricOffsetState,
+  InvariantSetState,
   ManifoldState,
   OrbitFilters,
   PeriodicSearchSettings,
@@ -79,6 +81,9 @@ interface SidebarProps {
   canComputeInverseGeometricOffsets: boolean;
   computeInverseGeometricOffsets: () => void;
   fitInverseGeometricOffsets: () => void;
+  invariantSetState: InvariantSetState;
+  setInvariantSetState: StateSetter<InvariantSetState>;
+  computeForwardInvariantSet: () => void;
   ORBIT_COLORS: { manifold: string; stableManifold: string };
   filters: OrbitFilters;
   setFilters: StateSetter<OrbitFilters>;
@@ -182,15 +187,27 @@ export const Sidebar = (props: SidebarProps) => {
           resetViewRange={props.resetViewRange}
         />
 
-        <StartingPoint
-          type={props.type}
-          startPoint={props.manifoldState.startPoint}
-          updateStartPoint={props.updateStartPoint}
-          disabled={props.manifoldState.isRunning || animationLocksConfiguration}
-        />
+        {!(props.type === 'discrete' && props.dynamicSystem === 'henon') && (
+          <StartingPoint
+            type={props.type}
+            startPoint={props.manifoldState.startPoint}
+            updateStartPoint={props.updateStartPoint}
+            disabled={props.manifoldState.isRunning || animationLocksConfiguration}
+          />
+        )}
 
         {props.type === 'discrete' && (
           <>
+            {props.dynamicSystem === 'henon' && (
+              <InvariantSetsPanel
+                state={props.invariantSetState}
+                setState={props.setInvariantSetState}
+                initialState={props.manifoldState.startPoint}
+                updateInitialState={props.updateStartPoint}
+                epsilon={(props.appliedParams || props.params).epsilon}
+                compute={props.computeForwardInvariantSet}
+              />
+            )}
             <ManifoldsPanel
               manifoldState={props.manifoldState}
               setManifoldState={props.setManifoldState}

frontend/src/components/layout/Viewport.test.tsx

@@ -74,6 +74,26 @@ describe('Viewport', () => {
     expect(screen.getByTestId('geometric-offset-point-swatch')).not.toHaveClass('lg-line');
   });
 
+  it('labels forward-projected invariant set samples', () => {
+    render(<Viewport {...baseProps} type="discrete" invariantSetState={{
+      showResult: true,
+      result: {
+        seed: { x: 0, y: 0, nx: 1, ny: 0 },
+        deterministic_image: { x: 1, y: 0 },
+        epsilon: 0.1,
+        boundary_point_count: 8,
+        requested_iterations: 1,
+        completed_iterations: 1,
+        stop_reason: 'requested_iterations_completed',
+        point_sets: [
+          { iteration: 0, points: [] },
+          { iteration: 1, points: [] },
+        ],
+      },
+    }} />);
+    expect(screen.getByText('Forward-projected samples')).toBeInTheDocument();
+  });
+
   it('labels unstable, deterministic-image, noise-ball, and mapped-point layers', () => {
     render(<Viewport {...baseProps} type="discrete" hasBoundarySamples manifoldState={{
       ...baseProps.manifoldState,