ENH/REF: split up plotting + add Bokeh plotting

.gitignore

@@ -115,3 +115,5 @@ venv.bak/
 .DS_Store
 
 /beamphysics/_version.py
+
+/tests/artifacts

beamphysics/__init__.py

@@ -25,6 +25,8 @@
     "Wavefront": ".wavefront",
     "WavefrontK": ".wavefront",
     "pmd_init": ".writers",
+    "set_default_backend": ".plot_dispatch",
+    "get_default_backend": ".plot_dispatch",
 }
 
 
@@ -35,6 +37,8 @@
     "particle_paths",
     "pmd_init",
     "single_particle",
+    "set_default_backend",
+    "get_default_backend",
     "Wavefront",
     "WavefrontK",
 ]

beamphysics/particles.py

@@ -21,7 +21,7 @@
 from .interfaces.lucretia import write_lucretia
 from .interfaces.opal import write_opal
 from .interfaces.simion import write_simion
-from .plot import density_plot, marginal_plot, slice_plot, wakefield_plot
+from .plot_dispatch import get_backend
 from .readers import particle_array, particle_paths
 from .species import charge_of, mass_of
 from .statistics import (
@@ -1381,6 +1381,7 @@ def plot(
         tex=True,
         nice=True,
         ellipse=False,
+        backend=None,
         **kwargs,
     ):
         """
@@ -1397,7 +1398,7 @@ def plot(
 
         Parameters
         ----------
-        key1 : str, default = 't'
+        key1 : str, default = 'x'
             Key to bin on the x-axis
 
         key2 : str, default = None
@@ -1423,25 +1424,28 @@ def plot(
             2x2 sigma matrix
 
         return_figure : bool, default = False
-            If true, return a matplotlib.figure.Figure object
+            If true, return the figure/layout object
 
-        **kwargs
-            Any additional kwargs to send to the the plot in: plt.subplots(**kwargs)
+        backend : str, optional
+            Plot backend: ``'mpl'`` or ``'bokeh'``.
+            Defaults to the module-level setting (see ``set_default_backend``).
 
+        **kwargs
+            Additional keyword arguments passed to the backend plot function.
 
         Returns
         -------
-        None or fig: matplotlib.figure.Figure
-            This only returns a figure object if return_figure=T, otherwise returns None
-
+        None or figure object
+            Returns the figure only if ``return_figure=True``.
         """
+        be = get_backend(backend)
 
         if not key2:
-            fig = density_plot(
+            fig = be.density_plot(
                 self, key=key1, bins=bins, xlim=xlim, tex=tex, nice=nice, **kwargs
             )
         else:
-            fig = marginal_plot(
+            fig = be.marginal_plot(
                 self,
                 key1=key1,
                 key2=key2,
@@ -1514,6 +1518,7 @@ def slice_plot(
         return_figure=False,
         xlim=None,
         ylim=None,
+        backend=None,
         **kwargs,
     ):
         """
@@ -1533,20 +1538,23 @@ def slice_plot(
         nice : bool, optional
             Scale to nice units. Default is True.
         return_figure : bool, optional
-            If True, return the matplotlib Figure. Default is False.
+            If True, return the figure/layout object. Default is False.
         xlim : tuple of float, optional
             Manual x-axis limits in raw units.
         ylim : tuple of float, optional
             Manual y-axis limits in raw units.
+        backend : str, optional
+            Plot backend: ``'mpl'`` or ``'bokeh'``.
         **kwargs
-            Additional keyword arguments passed to ``plt.subplots``.
+            Additional keyword arguments passed to the backend plot function.
 
         Returns
         -------
-        None or matplotlib.figure.Figure
-            Returns a Figure only if ``return_figure=True``.
+        None or figure object
+            Returns the figure only if ``return_figure=True``.
         """
-        fig = slice_plot(
+        be = get_backend(backend)
+        fig = be.slice_plot(
             self,
             *keys,
             n_slice=n_slice,
@@ -1619,11 +1627,11 @@ def wakefield_plot(
         wake: WakefieldBase,
         key=None,
         nice=True,
-        ax=None,
         xlim=None,
         ylim=None,
         tex=True,
         bins=None,
+        backend=None,
         **kwargs,
     ):
         """
@@ -1647,9 +1655,6 @@ def wakefield_plot(
         nice : bool, default=True
             If True, applies unit-aware scaling using SI prefixes (e.g., mm, ns).
 
-        ax : matplotlib.axes.Axes, optional
-            An existing Axes to plot into. If None, a new figure and axes are created.
-
         xlim : tuple of float, optional
             Limits to apply to the x-axis, in native units.
 
@@ -1662,21 +1667,25 @@ def wakefield_plot(
         bins : int or str, optional
             Number of bins to use for the density histogram.
 
-        kwargs : dict
-            Additional keyword arguments passed to `plt.subplots()` if a new axis is created.
+        backend : str, optional
+            Plot backend: ``'mpl'`` or ``'bokeh'``.
+
+        ax : matplotlib.axes.Axes, optional
+            Matplotlib-only: An existing Axes to plot into. (part of **kwargs)
+
+        **kwargs
+            Additional keyword arguments passed to the backend plot function.
 
         Returns
         -------
-        fig : matplotlib.figure.Figure
-            The matplotlib figure containing the plot.
+        figure object
         """
-
-        wakefield_plot(
+        be = get_backend(backend)
+        return be.wakefield_plot(
             self,
             wake,
             key=key,
             nice=nice,
-            ax=ax,
             xlim=xlim,
             ylim=ylim,
             tex=tex,