feat(bokeh): implement phase-diagram

[github-actions]

Implementation: phase-diagram - python/bokeh

Implements the python/bokeh version of phase-diagram.

File: plots/phase-diagram/implementations/python/bokeh.py

Parent Issue: #3004

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The plot displays four spiral trajectories of a damped harmonic oscillator system on a warm off-white background (#FAF8F1). The title "phase-diagram · bokeh · anyplot.ai" is clearly visible in dark text. The X-axis labeled "Position x (displacement)" and Y-axis labeled "Velocity dx/dt (m/s)" are both readable with appropriate font sizes. The trajectories spiral inward toward the origin, with each point colored using the viridis colormap to represent time progression. Starting points are marked with distinct Okabe-Ito colors (#009E73, #D55E00, #0072B2, #CC79A7), the equilibrium is marked with a red X at the origin, and a dashed horizontal line indicates zero velocity. The legend in the top-right displays all starting points with coordinates and the equilibrium marker. All text is readable against the light background. Legibility verdict: PASS

Dark render (plot-dark.png): The same plot rendered on a warm near-black background (#1A1A17). The title, axis labels, and tick labels are all rendered in light text that contrasts well against the dark surface. The data colors (viridis progression for time, Okabe-Ito colors for starting points) are identical to the light render - only the chrome has adapted. The trajectories, markers, and reference lines are all clearly visible. The legend with its dark background box and light text is readable. Legibility verdict: PASS

Score: 92/100

Category	Score	Max
Visual Quality	30	30
Design Excellence	14	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	8	10
Total	92	100

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) - Explicit font sizes at all levels; all readable in both themes
• VQ-02: No Overlap (6/6) - No overlapping elements; legend properly positioned with spacing
• VQ-03: Element Visibility (6/6) - Viridis time coloring clearly shows progression; markers well-differentiated
• VQ-04: Color Accessibility (2/2) - Okabe-Ito and viridis are CVD-safe; adequate contrast
• VQ-05: Layout & Canvas (4/4) - 4800x2700px; well-proportioned; nothing cut off
• VQ-06: Axis Labels & Title (2/2) - Title includes spec/library/source; axes descriptive with units
• VQ-07: Palette Compliance (2/2) - Starting points #009E73 (first), then Okabe-Ito order; viridis for continuous time data; correct backgrounds and theme adaptation

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (5/8) - Professional polish with theme-adaptive styling; good palette choices; functional but not exceptional
• DE-02: Visual Refinement (4/6) - Legend styled; subtle grid; theme-adaptive elements throughout; solid refinement
• DE-03: Data Storytelling (5/6) - Color gradient shows time evolution; clear focal point on equilibrium convergence; good visual hierarchy

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Correct phase diagram with x vs dx/dt; multiple trajectories show convergence
• SC-02: Required Features (4/4) - Fixed points shown; convergence behavior visible; time evolution colored; all spec requirements met
• SC-03: Data Mapping (3/3) - X=position, Y=velocity; axes appropriately scaled; all data visible
• SC-04: Title & Legend (3/3) - Title format correct; legend labels match data

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) - Multiple trajectories; damped oscillator physics; fixed point; time coloring
• DQ-02: Realistic Context (5/5) - Canonical pendulum example; realistic damping parameters (omega=2.0, gamma=0.3); appropriate initial conditions
• DQ-03: Appropriate Scale (4/4) - Position and velocity ranges sensible; axes labeled with units

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - No functions/classes; straightforward script
• CQ-02: Reproducibility (2/2) - Uses np.random.seed(42); deterministic
• CQ-03: Clean Imports (2/2) - All imports used; no dead code
• CQ-04: Code Elegance (2/2) - Well-structured; theme handling via environment; clean Bokeh patterns
• CQ-05: Output & API (1/1) - Saves as plot-{THEME}.html and plot-{THEME}.png; current API

Library Mastery (8/10)

• LM-01: Idiomatic Usage (5/5) - Proper figure(), scatter(), line() patterns; ColumnDataSource; HoverTool; Bokeh output best practices
• LM-02: Distinctive Features (3/5) - Uses LinearColorMapper with Viridis256, HoverTool with formatted tooltips, theme-adaptive styling

Score Caps Applied

• None — all criteria passed without triggering caps

Strengths

• Correct phase diagram visualization with multiple trajectories showing spiral convergence to equilibrium
• Theme-adaptive styling applied consistently throughout both light and dark renders
• Proper use of Okabe-Ito palette (positions 1-4 in order) for trajectory starting points
• Viridis colormap appropriately used for continuous time evolution data
• Excellent text legibility in both themes with explicit font size declarations
• Clean, reproducible code with proper seed management and deterministic behavior
• Idiomatic Bokeh usage with ColumnDataSource, LinearColorMapper, and HoverTool
• Realistic physics data (damped harmonic oscillator with reasonable parameters)
• No text overlap or collision issues; legend properly positioned
• Professional appearance with all required elements (fixed point, zero velocity line, trajectories)

Weaknesses

• Design excellence is at functional level rather than exceptional — could benefit from additional visual refinement
• No directional arrows on trajectories to explicitly show time evolution direction
• Fixed point at equilibrium could be more visually emphasized to draw focus

Verdict: APPROVED ✅

This is a strong, professional implementation that correctly visualizes phase diagram dynamics with clean code and excellent theme adaptation. All technical requirements are met and both renders are legible in their respective themes.