feat(plotnine): implement phase-diagram

[github-actions]

Implementation: phase-diagram - plotnine

Implements the plotnine version of phase-diagram.

File: plots/phase-diagram/implementations/plotnine.py

Parent Issue: #3004

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot shows a phase diagram (state space plot) displaying a damped harmonic oscillator trajectory. The visualization features a spiral pattern starting from the outer edge (at position x≈2, velocity≈0) and spiraling inward towards the origin (equilibrium point). The color gradient transitions from dark blue (early time t=0) through greenish tones to yellow (later time t≈8), clearly showing the time evolution. A dark blue circular marker indicates the starting point, and a yellow square marker shows the endpoint near the origin. Dashed reference lines mark the x=0 and dx/dt=0 axes. The title "phase-diagram · plotnine · pyplots.ai" appears at the top. Axis labels show "Position x" and "Velocity dx/dt". A colorbar legend on the right shows "Time (s)" ranging from 0 to 8. The background is clean with subtle gray gridlines.

Quality Score: 93/100

Criteria Checklist

Visual Quality (38/40 pts)

• VQ-01: Text Legibility (10/10) - Title, axis labels, and tick labels are all clearly readable at full size with appropriate font sizing
• VQ-02: No Overlap (8/8) - No overlapping text elements anywhere in the plot
• VQ-03: Element Visibility (7/8) - Trajectory line is clearly visible with good thickness; start/end markers clearly distinguishable; slight deduction as the trajectory gets quite dense near origin
• VQ-04: Color Accessibility (5/5) - Blue-to-yellow gradient is colorblind-friendly (viridis-like)
• VQ-05: Layout Balance (5/5) - Plot fills canvas appropriately with balanced margins
• VQ-06: Axis Labels (1/2) - Descriptive labels but missing units (could be "Position x (m)" and "Velocity dx/dt (m/s)")
• VQ-07: Grid & Legend (2/2) - Grid is subtle with appropriate alpha, legend is well positioned

Spec Compliance (25/25 pts)

• SC-01: Plot Type (8/8) - Correct phase diagram showing x vs dx/dt trajectory
• SC-02: Data Mapping (5/5) - Position on x-axis, velocity on y-axis as required
• SC-03: Required Features (5/5) - Shows damped oscillator trajectory, spiral convergence to equilibrium, time evolution via color gradient, reference lines at zero crossings
• SC-04: Data Range (3/3) - Axes properly show all data points
• SC-05: Legend Accuracy (2/2) - Time legend is accurate and descriptive
• SC-06: Title Format (2/2) - Correct format: "phase-diagram · plotnine · pyplots.ai"

Data Quality (17/20 pts)

• DQ-01: Feature Coverage (6/8) - Shows damped oscillator well but spec mentions "multiple trajectories from different initial conditions" as an option that could enhance the visualization
• DQ-02: Realistic Context (7/7) - Damped harmonic oscillator is a classic physics example, exactly as suggested in the spec
• DQ-03: Appropriate Scale (4/5) - Values are physically reasonable; 800 points provides smooth trajectory

Code Quality (10/10 pts)

• CQ-01: KISS Structure (3/3) - Clean linear flow: imports → data → plot → save
• CQ-02: Reproducibility (3/3) - Uses np.random.seed(42)
• CQ-03: Clean Imports (2/2) - All imports are used
• CQ-04: No Deprecated API (1/1) - Modern plotnine API
• CQ-05: Output Correct (1/1) - Saves as plot.png

Library Features (3/5 pts)

• LF-01: Uses distinctive library features (3/5) - Good use of plotnine grammar (ggplot, aes, geom_path, scale_color_gradient, theme customization), but could leverage more advanced features like annotations or faceting

Strengths

• Excellent visualization of damped harmonic oscillator phase portrait with clear spiral convergence to equilibrium
• Effective use of color gradient to show time evolution (blue to yellow)
• Well-marked start and end points with distinct markers (circle and square)
• Reference lines at x=0 and dx/dt=0 help identify equilibrium and zero-crossing points
• Clean, professional appearance with proper plotnine grammar of graphics implementation
• Mathematically correct derivative calculation for damped oscillator

Weaknesses

• Axis labels could include physical units (e.g., "Position x (m)", "Velocity dx/dt (m/s)")
• Only single trajectory shown; spec notes that multiple trajectories from different initial conditions could reveal basin of attraction structure

Verdict: APPROVED