feat(plotnine): implement phase-diagram (#3053)

## Implementation: `phase-diagram` - plotnine

Implements the **plotnine** version of `phase-diagram`.

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

**Parent Issue:** #3004

---
:robot: *[impl-generate
workflow](https://github.com/MarkusNeusinger/pyplots/actions/runs/20617670372)*

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

plots/phase-diagram/implementations/plotnine.py

@@ -0,0 +1,68 @@
+""" pyplots.ai
+phase-diagram: Phase Diagram (State Space Plot)
+Library: plotnine 0.15.2 | Python 3.13.11
+Quality: 93/100 | Created: 2025-12-31
+"""
+
+import numpy as np
+import pandas as pd
+from plotnine import (
+    aes,
+    element_line,
+    element_text,
+    geom_hline,
+    geom_path,
+    geom_point,
+    geom_vline,
+    ggplot,
+    labs,
+    scale_color_gradient,
+    theme,
+    theme_minimal,
+)
+
+
+# Data: Damped harmonic oscillator (spiral trajectory converging to equilibrium)
+np.random.seed(42)
+
+# System parameters
+omega = 2 * np.pi  # Natural frequency
+gamma = 0.15  # Damping coefficient
+
+# Time array for smooth trajectory
+t = np.linspace(0, 8, 800)
+
+# Solution for damped harmonic oscillator: x = A * exp(-gamma*t) * cos(omega*t)
+A = 2.0  # Initial amplitude
+x = A * np.exp(-gamma * t) * np.cos(omega * t)
+dx_dt = A * np.exp(-gamma * t) * (-gamma * np.cos(omega * t) - omega * np.sin(omega * t))
+
+# Create DataFrame with time for color gradient
+df = pd.DataFrame({"x": x, "dx_dt": dx_dt, "t": t})
+
+# Create phase diagram
+plot = (
+    ggplot(df, aes(x="x", y="dx_dt", color="t"))
+    + geom_path(size=1.5, alpha=0.9)
+    + geom_point(data=df.iloc[[0]], size=5, color="#306998", show_legend=False)  # Start point
+    + geom_point(data=df.iloc[[-1]], size=5, color="#FFD43B", shape="s", show_legend=False)  # End point (equilibrium)
+    + geom_hline(yintercept=0, linetype="dashed", alpha=0.4, size=0.5)
+    + geom_vline(xintercept=0, linetype="dashed", alpha=0.4, size=0.5)
+    + scale_color_gradient(low="#306998", high="#FFD43B", name="Time (s)")
+    + labs(x="Position x", y="Velocity dx/dt", title="phase-diagram · plotnine · pyplots.ai")
+    + theme_minimal()
+    + theme(
+        figure_size=(16, 9),
+        text=element_text(size=14),
+        axis_title=element_text(size=20),
+        axis_text=element_text(size=16),
+        plot_title=element_text(size=24),
+        legend_text=element_text(size=14),
+        legend_title=element_text(size=16),
+        panel_grid_major=element_line(alpha=0.3),
+        panel_grid_minor=element_line(alpha=0.15),
+    )
+)
+
+# Save
+plot.save("plot.png", dpi=300, verbose=False)

plots/phase-diagram/metadata/plotnine.yaml

@@ -0,0 +1,28 @@
+library: plotnine
+specification_id: phase-diagram
+created: '2025-12-31T11:06:50Z'
+updated: '2025-12-31T11:16:03Z'
+generated_by: claude-opus-4-5-20251101
+workflow_run: 20617670372
+issue: 3004
+python_version: 3.13.11
+library_version: 0.15.2
+preview_url: https://storage.googleapis.com/pyplots-images/plots/phase-diagram/plotnine/plot.png
+preview_thumb: https://storage.googleapis.com/pyplots-images/plots/phase-diagram/plotnine/plot_thumb.png
+preview_html: null
+quality_score: 93
+review:
+  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