# pyswarms.utils.plotters package

The mod:pyswarms.utils.plotters module implements various visualization capabilities to interact with your swarm. Here, ou can plot cost history and animate your swarm in both 2D or 3D spaces.

## pyswarms.utils.plotters.plotters module

Plotting tool for Optimizer Analysis

This module is built on top of `matplotlib` to render quick and easy plots for your optimizer. It can plot the best cost for each iteration, and show animations of the particles in 2-D and 3-D space. Furthermore, because it has `matplotlib` running under the hood, the plots are easily customizable.

For example, if we want to plot the cost, simply run the optimizer, get the cost history from the optimizer instance, and pass it to the `plot_cost_history()` method

    import pyswarms as ps
    from pyswarms.utils.functions.single_obj import sphere
    from pyswarms.utils.plotters import plot_cost_history

    # Set up optimizer
    options = {'c1':0.5, 'c2':0.3, 'w':0.9}
    optimizer = ps.single.GlobalBestPSO(n_particles=10, dimensions=2,
                                        options=options)

    # Obtain cost history from optimizer instance
    cost_history = optimizer.cost_history

    # Plot!
    plot_cost_history(cost_history)
    plt.show()

In case you want to plot the particle movement, it is important that either one of the `matplotlib` animation `Writers` is installed. These doesn’t come out of the box for `pyswarms`, and must be installed separately. For example, in a Linux or Windows distribution, you can install `ffmpeg` as

    >>> conda install -c conda-forge ffmpeg

Now, if you want to plot your particles in a 2-D environment, simply pass the position history of your swarm (obtainable from swarm instance):

    import pyswarms as ps
    from pyswarms.utils.functions.single_obj import sphere
    from pyswarms.utils.plotters import plot_cost_history

    # Set up optimizer
    options = {'c1':0.5, 'c2':0.3, 'w':0.9}
    optimizer = ps.single.GlobalBestPSO(n_particles=10, dimensions=2,
                                        options=options)

    # Obtain pos history from optimizer instance
    pos_history = optimizer.pos_history

    # Plot!
    plot_contour(pos_history)

You can also supply various arguments in this method: the indices of the specific dimensions to be used, the limits of the axes, and the interval/ speed of animation.

pyswarms.utils.plotters.plotters.plot_contour(pos_history, canvas=None, title='Trajectory', mark=None, designer=None, mesher=None, animator=None, n_processes=None, **kwargs)

  Draw a 2D contour map for particle trajectories

  Here, the space is represented as a flat plane. The contours indicate the elevation with respect to the objective function. This works best with 2-dimensional swarms with their fitness in z-space.

  Parameters:

    - pos_history (numpy.ndarray or list) – Position history of the swarm with shape `(iteration, n_particles, dimensions)`

    - canvas ((`matplotlib.figure.Figure`, `matplotlib.axes.Axes`),) – The (figure, axis) where all the events will be draw. If `None` is supplied, then plot will be drawn to a fresh set of canvas.

    - title (str, optional) – The title of the plotted graph. Default is Trajectory

    - mark (tuple, optional) – Marks a particular point with a red crossmark. Useful for marking the optima.

    - designer (`pyswarms.utils.formatters.Designer`, optional) – Designer class for custom attributes

    - mesher (`pyswarms.utils.formatters.Mesher`, optional) – Mesher class for mesh plots

    - animator (`pyswarms.utils.formatters.Animator`, optional) – Animator class for custom animation

    - n_processes (int) – number of processes to use for parallel mesh point calculation (default: None = no parallelization)

    - **kwargs (dict) – Keyword arguments that are passed as a keyword argument to `matplotlib.axes.Axes` plotting function

  Returns:

    The drawn animation that can be saved to mp4 or other third-party tools

  Return type:

    `matplotlib.animation.FuncAnimation`

pyswarms.utils.plotters.plotters.plot_cost_history(cost_history, ax=None, title='Cost History', designer=None, **kwargs)

  Create a simple line plot with the cost in the y-axis and the iteration at the x-axis

  Parameters:

    - cost_history (array_like) – Cost history of shape `(iters, )` or length `iters` where each element contains the cost for the given iteration.

    - ax (`matplotlib.axes.Axes`, optional) – The axes where the plot is to be drawn. If `None` is passed, then the plot will be drawn to a new set of axes.

    - title (str, optional) – The title of the plotted graph. Default is Cost History

    - designer (`pyswarms.utils.formatters.Designer`, optional) – Designer class for custom attributes

    - **kwargs (dict) – Keyword arguments that are passed as a keyword argument to `matplotlib.axes.Axes`

  Returns:

    The axes on which the plot was drawn.

  Return type:

    `matplotlib.axes._subplots.AxesSubplot`

pyswarms.utils.plotters.plotters.plot_surface(pos_history, canvas=None, title='Trajectory', designer=None, mesher=None, animator=None, mark=None, n_processes=None, **kwargs)

  Plot a swarm’s trajectory in 3D

  This is useful for plotting the swarm’s 2-dimensional position with respect to the objective function. The value in the z-axis is the fitness of the 2D particle when passed to the objective function. When preparing the position history, make sure that the:

  - first column is the position in the x-axis,

  - second column is the position in the y-axis; and

  - third column is the fitness of the 2D particle

  The `pyswarms.utils.plotters.formatters.Mesher` class provides a method that prepares this history given a 2D pos history from any optimizer.

      import pyswarms as ps
      from pyswarms.utils.functions.single_obj import sphere
      from pyswarms.utils.plotters import plot_surface
      from pyswarms.utils.plotters.formatters import Mesher

      # Run optimizer
      options = {'c1':0.5, 'c2':0.3, 'w':0.9}
      optimizer = ps.single.GlobalBestPSO(n_particles=10, dimensions=2, options)

      # Prepare position history
      m = Mesher(func=sphere)
      pos_history_3d = m.compute_history_3d(optimizer.pos_history)

      # Plot!
      plot_surface(pos_history_3d)

  Parameters:

    - pos_history (numpy.ndarray) – Position history of the swarm with shape `(iteration, n_particles, 3)`

    - objective_func (callable) – The objective function that takes a swarm of shape `(n_particles, 2)` and returns a fitness array of `(n_particles, )`

    - canvas ((`matplotlib.figure.Figure`, `matplotlib.axes.Axes`),) – The (figure, axis) where all the events will be draw. If `None` is supplied, then plot will be drawn to a fresh set of canvas.

    - title (str, optional) – The title of the plotted graph. Default is Trajectory

    - mark (tuple, optional) – Marks a particular point with a red crossmark. Useful for marking the optima.

    - designer (`pyswarms.utils.formatters.Designer`, optional) – Designer class for custom attributes

    - mesher (`pyswarms.utils.formatters.Mesher`, optional) – Mesher class for mesh plots

    - animator (`pyswarms.utils.formatters.Animator`, optional) – Animator class for custom animation

    - n_processes (int) – number of processes to use for parallel mesh point calculation (default: None = no parallelization)

    - **kwargs (dict) – Keyword arguments that are passed as a keyword argument to `matplotlib.axes.Axes` plotting function

  Returns:

    The drawn animation that can be saved to mp4 or other third-party tools

  Return type:

    `matplotlib.animation.FuncAnimation`

## pyswarms.utils.plotters.formatters module

Plot Formatters

This module implements helpful classes to format your plots or create meshes.

class pyswarms.utils.plotters.formatters.Animator(interval: int = 80, repeat_delay=None, repeat: bool = True)

  Bases: `object`

  Animator class for specifying animation behavior

  You can use this class to modify options on how the animation will be run in the `pyswarms.utils.plotters.plot_contour()` and `pyswarms.utils.plotters.plot_surface()` methods.

      from pyswarms.utils.plotters import plot_contour
      from pyswarms.utils.plotters.formatters import Animator

      # Do not repeat animation
      my_animator = Animator(repeat=False)

      # Assuming we already had an optimizer ready
      plot_contour(pos_history, animator=my_animator)

  interval

    Sets the interval or speed into which the animation is played. Default is 80

    Type:

      int

  repeat_delay

    Sets the delay before repeating the animation again.

    Type:

      int or float, optional

  repeat

    Pass False if you don’t want to repeat the animation. Default is True

    Type:

      bool, optional

class pyswarms.utils.plotters.formatters.Designer(figsize: tuple = (10, 8), title_fontsize='large', text_fontsize='medium', legend='Cost', label=['x-axis', 'y-axis', 'z-axis'], limits=[(-1, 1), (-1, 1), (-1, 1)], colormap=<matplotlib.colors.ListedColormap object>)

  Bases: `object`

  Designer class for specifying a plot’s formatting and design

  You can use this class for specifying design-related customizations to your plot. This can be passed in various functions found in the `pyswarms.utils.plotters` module.

      from pyswarms.utils.plotters import plot_cost_history
      from pyswarms.utils.plotters.formatters import Designer

      # Set title_fontsize into 20
      my_designer = Designer(title_fontsize=20)

      # Assuming we already had an optimizer ready
      plot_cost_history(cost_history, designer=my_designer)

  figsize

    Overall figure size. Default is (10, 8)

    Type:

      tuple

  title_fontsize

    Size of the plot’s title. Default is large

    Type:

      str, int, or float

  text_fontsize

    Size of the plot’s labels and legend. Default is medium

    Type:

      str, int, or float

  legend

    Label to show in the legend. For cost histories, it states the label of the line plot. Default is Cost

    Type:

      str

  label

    Label to show in the x, y, or z-axis. For a 3D plot, please pass an iterable with three elements. Default is `['x-axis', 'y-axis', 'z-axis']`

    Type:

      array_like

  limits

    The x-, y-, z- limits of the axes. Pass an iterable with the number of elements representing the number of axes. Default is `[(-1, 1), (-1, 1), (-1, 1)]`

    Type:

      list

  colormap

    Colormap for contour plots. Default is cm.viridis

    Type:

      matplotlib.cm.Colormap

class pyswarms.utils.plotters.formatters.Mesher(func, delta: float = 0.001, limits=[(-1, 1), (-1, 1)], levels: list = array([-2., -1.93, -1.86, -1.79, -1.72, -1.65, -1.58, -1.51, -1.44, -1.37, -1.3, -1.23, -1.16, -1.09, -1.02, -0.95, -0.88, -0.81, -0.74, -0.67, -0.6, -0.53, -0.46, -0.39, -0.32, -0.25, -0.18, -0.11, -0.04, 0.03, 0.1, 0.17, 0.24, 0.31, 0.38, 0.45, 0.52, 0.59, 0.66, 0.73, 0.8, 0.87, 0.94, 1.01, 1.08, 1.15, 1.22, 1.29, 1.36, 1.43, 1.5, 1.57, 1.64, 1.71, 1.78, 1.85, 1.92, 1.99]), alpha: float = 0.3)

  Bases: `object`

  Mesher class for plotting contours of objective functions

  This class enables drawing a surface plot of a given objective function. You can customize how this plot is drawn with this class. Pass an instance of this class to enable meshing.

      from pyswarms.utils.plotters import plot_surface
      from pyswarms.utils.plotters.formatters import Mesher
      from pyswarms.utils.functions import single_obj as fx

      # Use sphere function
      my_mesher = Mesher(func=fx.sphere)

      # Assuming we already had an optimizer ready
      plot_surface(pos_history, mesher=my_mesher)

  func

    Objective function to plot a surface of.

    Type:

      callable

  delta

    Number of steps when generating the surface plot Default is 0.001

    Type:

      float

  limits

    The range, in each axis, where the mesh will be drawn. Default is `[(-1,1), (-1,1)]`

    Type:

      list or tuple

  levels

    Levels on which the contours are shown. If `int` is passed, then matplotlib automatically computes for the level positions. Default is `numpy.arange(-2.0, 2.0, 0.070)`

    Type:

      list or int, optional

  alpha

    Transparency of the surface plot. Default is 0.3

    Type:

      float, optional

  limits

    The x-, y-, z- limits of the axes. Pass an iterable with the number of elements representing the number of axes. Default is `[(-1, 1), (-1, 1)]`

    Type:

      list, optional

  compute_history_3d(pos_history, n_processes=None)

    Compute a 3D position matrix

    The first two columns are the 2D position in the x and y axes respectively, while the third column is the fitness on that given position.

    Parameters:

      - pos_history (numpy.ndarray) – Two-dimensional position matrix history of shape `(iterations, n_particles, 2)`

      - n_processes (int)

      - (default (number of processes to use for parallel mesh point calculation)

    Returns:

      3D position matrix of shape `(iterations, n_particles, 3)`

    Return type:

      numpy.ndarray