feat(seaborn): implement phase-diagram (#3050)

## Implementation: `phase-diagram` - seaborn

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

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

**Parent Issue:** #3004

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

---------

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/seaborn.py

@@ -0,0 +1,108 @@
+""" pyplots.ai
+phase-diagram: Phase Diagram (State Space Plot)
+Library: seaborn 0.13.2 | Python 3.13.11
+Quality: 91/100 | Created: 2025-12-31
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import seaborn as sns
+
+
+# Data: Damped harmonic oscillator phase trajectories
+np.random.seed(42)
+
+# System parameters for damped oscillator: d²x/dt² + 2*zeta*omega*dx/dt + omega²*x = 0
+omega = 2 * np.pi  # Natural frequency
+zeta = 0.15  # Damping ratio (underdamped)
+
+# Generate multiple trajectories from different initial conditions
+t = np.linspace(0, 5, 500)
+trajectories = []
+initial_conditions = [
+    (2.0, 0.0),  # Large displacement, zero velocity
+    (0.0, 8.0),  # Zero displacement, positive velocity
+    (-1.5, -5.0),  # Negative displacement, negative velocity
+    (1.0, 4.0),  # Mixed positive
+]
+
+for x0, v0 in initial_conditions:
+    # Analytical solution for underdamped oscillator
+    omega_d = omega * np.sqrt(1 - zeta**2)  # Damped frequency
+    A = np.sqrt(x0**2 + ((zeta * omega * x0 + v0) / omega_d) ** 2)
+    phi = np.arctan2(omega_d * x0, zeta * omega * x0 + v0)
+
+    # Position and velocity (derivative)
+    x = A * np.exp(-zeta * omega * t) * np.sin(omega_d * t + phi)
+    dx_dt = (
+        A
+        * np.exp(-zeta * omega * t)
+        * (-zeta * omega * np.sin(omega_d * t + phi) + omega_d * np.cos(omega_d * t + phi))
+    )
+
+    trajectories.append((x, dx_dt, f"({x0}, {v0})"))
+
+# Create DataFrame for seaborn
+data = []
+for x, dx_dt, label in trajectories:
+    for i in range(len(x)):
+        data.append({"Position (x)": x[i], "Velocity (dx/dt)": dx_dt[i], "Initial Condition": label, "Time": t[i]})
+df = pd.DataFrame(data)
+
+# Plot
+sns.set_style("whitegrid")
+fig, ax = plt.subplots(figsize=(16, 9))
+
+# Use seaborn lineplot for trajectories with color gradient by hue
+palette = ["#306998", "#FFD43B", "#E24A33", "#348ABD"]
+sns.lineplot(
+    data=df,
+    x="Position (x)",
+    y="Velocity (dx/dt)",
+    hue="Initial Condition",
+    palette=palette,
+    linewidth=2.5,
+    alpha=0.9,
+    legend=True,
+    ax=ax,
+    sort=False,
+)
+
+# Add starting points as larger markers
+for i, (x, dx_dt, _label) in enumerate(trajectories):
+    ax.scatter(x[0], dx_dt[0], s=250, color=palette[i], zorder=5, edgecolor="white", linewidth=2)
+
+# Add fixed point (equilibrium at origin)
+ax.scatter(0, 0, s=300, color="black", marker="x", linewidth=4, zorder=6, label="Equilibrium")
+
+# Add direction arrows on trajectories
+for i, (x, dx_dt, _label) in enumerate(trajectories):
+    # Add arrows at several points along trajectory
+    arrow_indices = [50, 150, 300]
+    for idx in arrow_indices:
+        if idx < len(x) - 1:
+            dx = x[idx + 1] - x[idx]
+            dy = dx_dt[idx + 1] - dx_dt[idx]
+            ax.annotate(
+                "",
+                xy=(x[idx] + dx * 0.5, dx_dt[idx] + dy * 0.5),
+                xytext=(x[idx], dx_dt[idx]),
+                arrowprops={"arrowstyle": "->", "color": palette[i], "lw": 2},
+            )
+
+# Styling
+ax.set_xlabel("Position (x)", fontsize=20)
+ax.set_ylabel("Velocity (dx/dt)", fontsize=20)
+ax.set_title("phase-diagram · seaborn · pyplots.ai", fontsize=24)
+ax.tick_params(axis="both", labelsize=16)
+
+# Adjust legend
+ax.legend(fontsize=14, loc="upper right", title="Initial Condition", title_fontsize=16)
+
+# Add zero lines for reference
+ax.axhline(y=0, color="gray", linestyle="--", linewidth=1.5, alpha=0.5)
+ax.axvline(x=0, color="gray", linestyle="--", linewidth=1.5, alpha=0.5)
+
+plt.tight_layout()
+plt.savefig("plot.png", dpi=300, bbox_inches="tight")

plots/phase-diagram/metadata/seaborn.yaml

@@ -0,0 +1,30 @@
+library: seaborn
+specification_id: phase-diagram
+created: '2025-12-31T11:05:40Z'
+updated: '2025-12-31T11:15:30Z'
+generated_by: claude-opus-4-5-20251101
+workflow_run: 20617609208
+issue: 3004
+python_version: 3.13.11
+library_version: 0.13.2
+preview_url: https://storage.googleapis.com/pyplots-images/plots/phase-diagram/seaborn/plot.png
+preview_thumb: https://storage.googleapis.com/pyplots-images/plots/phase-diagram/seaborn/plot_thumb.png
+preview_html: null
+quality_score: 91
+review:
+  strengths:
+  - Excellent visualization of phase space dynamics with clear spiral trajectories
+    converging to equilibrium
+  - Well-chosen physics example (damped harmonic oscillator) that perfectly demonstrates
+    the plot type
+  - Starting points clearly marked with large scatter markers distinguishing each
+    trajectory
+  - Direction arrows effectively show time evolution along the trajectories
+  - Reference lines (dashed gray at x=0 and y=0) help identify equilibrium crossing
+  - Proper use of seaborn lineplot with hue for trajectory differentiation
+  - Clean readable code with analytical solution for underdamped oscillator
+  weaknesses:
+  - Legend positioning and styling could be improved - the Equilibrium marker is added
+    separately and its legend entry appears disconnected
+  - Inner portions of spirals become dense and harder to distinguish near the origin
+  - Could benefit from using a colorblind-friendly palette instead of custom colors