Imported from CSProfKGD/gradient-descent-lab (AGENTS.md). Install upstream with npx skills add CSProfKGD/gradient-descent-lab. Copyright stays with the author.

AGENTS.md

Project goal

Build an interactive visualization of gradient descent on a two-dimensional objective function. The experience must show the same optimization run in two synchronized views:

• a freely orbitable 3D surface plot; and
• a 2D contour plot.

Each initial point moves according to the selected optimizer and keeps its complete trajectory visible in both views.

Product requirements

• Render the objective f(x, y) = 15 exp(-0.25 (x + 2)^2) + 0.5 exp(-2 (x - 2)^2) + x^2 + y^2.
• Use the same sampled domain, objective implementation, color scale, particles, and iteration state for the surface and contour views.
• Start with multiple points distributed uniformly over the visible (x, y) domain. Keep initialization deterministic when practical so optimizer comparisons are reproducible.
• On the contour view, draw each current point and the full tail of all of its earlier positions.
• On the surface view, place each corresponding point at (x, y, f(x, y)) and draw its full 3D trajectory on the surface.
• Let users freely orbit, pan, and zoom the visualization.
• Use a black plot background. Do not render the two vertical back walls visible in the first reference screenshot.
• Provide optimizer choices for:
  • gradient descent; and
  • gradient descent with classical momentum.
• Provide editable controls for:
  • step size eta, default 0.01;
  • momentum coefficient beta, default 0.8; and
  • iteration count, default 100.
• Momentum coefficient controls may be disabled or visually de-emphasized when plain gradient descent is selected, but their value must be preserved.
• Provide clear run/play, pause, reset, and restart behavior. Changing an input and starting again must produce a clean run from the original initial points.
• Keep controls usable across common desktop viewport sizes and maintain legible contrast on the dark background.

Mathematical behavior

Let p_k = [x_k, y_k].

Plain gradient descent:

p_(k+1) = p_k - eta * grad f(p_k)

Classical momentum, with v_0 = [0, 0]:

v_(k+1) = beta * v_k - eta * grad f(p_k)

p_(k+1) = p_k + v_(k+1)

For this objective:

• df/dx = -7.5 (x + 2) exp(-0.25 (x + 2)^2) - 2 (x - 2) exp(-2 (x - 2)^2) + 2x
• df/dy = 2y

Use one canonical objective and gradient implementation for simulation and rendering. Add numerical safeguards so unstable user-selected parameters do not freeze the interface or contaminate rendering with NaN/infinite coordinates.

Implementation guidance

• Keep optimization state and math separate from rendering and UI state.
• Prefer a browser-based interactive implementation unless later requirements establish a different platform.
• Keep animation timing independent from optimizer math: one rendered animation step should advance a well-defined integer iteration.
• Preserve camera state during play, pause, and parameter edits unless the user explicitly resets the view.
• Avoid unnecessary visual clutter. Favor a clean scientific visualization with distinct, consistently colored trajectories.
• Do not add opaque walls or panels behind the 3D surface. Axes and a ground plane/grid may be used only if they remain subtle against the black background.
• Treat context.md as the current product brief. Update it when requirements or resolved decisions change.

Quality bar

• Verify the analytic gradient against finite differences.
• Test both optimizer update rules and reset/restart semantics.
• Verify that every 2D point corresponds to the same (x, y) and iteration as its 3D point.
• Verify that 3D points and trail vertices use z = f(x, y).
• Check that complete trails remain visible through the final configured iteration.
• Check interaction and layout at multiple desktop viewport sizes.
• Run the repository's formatter, type checker, tests, and build before handoff once those commands exist.
• After the application exists, record its exact setup and validation commands here rather than guessing them.

Current commands:

• Install: pnpm install
• Develop: pnpm run dev
• Lint: pnpm run lint
• Build: pnpm run build

Scope discipline

• Do not silently change the objective function, optimizer equations, defaults, or required visual behavior.
• If a design detail is unspecified, choose a reversible default and document it in context.md.
• Preserve unrelated user changes and avoid destructive repository operations.