updated docs

README.md

@@ -4,11 +4,12 @@
 [![Conda Version](https://img.shields.io/conda/vn/conda-forge/sympy_plot_backends.svg)](https://anaconda.org/conda-forge/sympy_plot_backends)
 [![Documentation Status](https://readthedocs.org/projects/sympy-plot-backends/badge/?version=latest)](http://sympy-plot-backends.readthedocs.io/)
 ![Coverage](https://github.com/Davide-sd/sympy-plot-backends/blob/master/coverage.svg)
+[![](https://img.shields.io/static/v1?label=Github%20Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/Davide-sd)
 
 
 This module contains a few plotting backends that can be used with [SymPy](github.com/sympy/sympy) and [Numpy](https://github.com/numpy/numpy). A backend represents the plotting library: it provides the necessary functionalities to quickly and easily plot the most common types of symbolic expressions (line plots, surface plots, parametric plots, vector plots, complex plots, control system plots).
 
-The following plotting libraries are supported: [Matplolib](https://matplotlib.org/), [Plotly](https://plotly.com/), [Bokeh](https://github.com/bokeh/bokeh), [K3D-Jupyter](https://github.com/K3D-tools/K3D-jupyter), [Mayavi](https://github.com/enthought/mayavi).
+The following plotting libraries are supported: [Matplolib](https://matplotlib.org/), [Plotly](https://plotly.com/), [Bokeh](https://github.com/bokeh/bokeh), [K3D-Jupyter](https://github.com/K3D-tools/K3D-jupyter).
 
 <div>
 <img src="https://raw.githubusercontent.com/Davide-sd/sympy-plot-backends/master/imgs/iplot_bokeh.png" width=250/>
@@ -30,24 +31,30 @@ On top of the usual plotting functions exposed by SymPy (`plot`,
 * visualize 2D/3D vector fields with quivers or streamlines.
 * visualize complex functions with [domain coloring](https://en.wikipedia.org/wiki/Domain_coloring).
 * visualize entities from the `sympy.geometry` module.
-* visualize control systems' response to input signals, visualize Bode, Nyquist and Nichols plots.
+* visualize control systems' response to input signals, root locus, as well as Bode, Nyquist and Nichols diagrams.
 * create parametric-interactive plots using widgets
   (sliders, buttons, etc.) with *ipywidgets* or *Holoviz's Panel*.
-* combine multiple plots into a grid-like layout.
 
 Please, read the
 [following documentation page](https://sympy-plot-backends.readthedocs.io/en/latest/overview.html#differences-with-sympy-plotting)
 to understand the differences between this module and ``sympy.plotting``.
 
-If you feel like some feature could be implemented, open an issue or create
-a PR.
 
+## Development and Support
 
-## Explore the Capabilities
+If you feel like a feature could be implemented, open an issue or create a PR.
 
-[Read the documentation](https://sympy-plot-backends.readthedocs.io/) to 
-explore the capabilities before the installation, which contains plenty of
-examples.
+If you really want a new feature but you don't have the capabilities or the
+time to make it work, I'm willing to help; but first, open an issue or send
+me an email so that we can discuss a sponsorship strategy.
+
+Developing this module and its documentation was no easy job. Implementing
+new feature and fixing bugs requires time and energy too. If you found this
+module useful, you can show your appreciation by sponsoring this project:
+
+[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/davide_sd)
+or
+[![](https://img.shields.io/static/v1?label=Github%20Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/Davide-sd)
 
 
 ## Installation
@@ -72,7 +79,14 @@ plotly, k3d, vtk, execute the following command:
 pip install sympy_plot_backends[all]
 ```
 
-Or:
+If you are using zshell, the above `pip` command is going to fail.
+Use the following instead:
+
+```
+pip install "sympy_plot_backends[all]"
+```
+
+Or, if you are using `conda`:
 
 ```
 conda install -c anaconda scipy notebook colorcet
@@ -84,15 +98,9 @@ conda install -c bokeh ipywidgets_bokeh
 conda install -c conda-forge k3d msgpack-python
 conda install -c plotly plotly
 conda install -c conda-forge vtk
+conda install -c conda-forge control slycot
 ```
 
-Finally, if you are using zshell, the above `pip` command is going to fail.
-Use the following instead:
-
-```
-pip install "sympy_plot_backends[all]"
-```
-
 
 ## Warnings
 

TODO.md

@@ -1,6 +1,6 @@
 ## TODO
 
-- [ ] enable the user to provide existing figures and plot over them.
+In no particular order:
 
 - [ ] Implement parallel evaluation when `modules="mpmath"` or
   `modules="sympy"`. [Motivational example](https://stackoverflow.com/a/77163667/2329968).
@@ -11,10 +11,10 @@
 - [ ] `plot_implicit`: decouple `And` expressions and plot them with contours
   following a strategy similar to sage.
 
-- [ ] 3D vector fields discretizing the volume with two polar parameters, or
+- [ ] 3D vector fields: discretize the volume with two polar parameters, or
   two cylindrical parameters.
 
-- [ ] `plot_nyquist` and `plot_nichols` for Plotly/Bokeh.
+- [ ] Control system plotting for Plotly.
 
 - [ ] implement parametric-widgets support for `xlim, ylim, zlim` and
   `xlabel, ylabel, zlabel`.
@@ -24,8 +24,10 @@
 - [ ] Create a way to apply rotation/translation/scaling transformation to 3D
   entities (obviously, with interactive plotting in mind).
 
-- [ ] custom legend position with keyword argument.
+- [ ] Custom legend position with keyword argument.
 
-- [ ] wireframe lines for iso-modulus, iso-phase on `analytic_landscape`.
+- [ ] Apply `pi` tick format to axis labels.
 
-- [ ] asymptotes on 3D plots: probably requires to break mesh connectivity.
+- [ ] Wireframe lines for iso-modulus, iso-phase on `analytic_landscape`.
+
+- [ ] Asymptotes on 3D plots: probably requires to break mesh connectivity.

doc/source/conf.py

@@ -66,7 +66,8 @@
     'sphinx_plotly_directive',
     'sphinx_panel_screenshot',
     'sphinx_k3d_screenshot',
-    'sphinx_math_dollar'
+    'sphinx_math_dollar',
+    'sphinx_design'
 ]
 
 # nbsphinx_allow_errors = True

doc/source/index.rst

@@ -9,9 +9,9 @@ Welcome to Sympy Plotting Backends's documentation!
 This Python module contains a few plotting backends that can be used with
 `SymPy <http://github.com/sympy/sympy/>`_ and `Numpy <https://github.com/numpy/numpy>`_.
 A backend represents the plotting library:
-it provides the necessary functionalities to quickly creates the most common
-types of plots, such as line plots, surface plots, parametric plots,
-vector plots, complex plots, geometric plots.
+it provides the necessary functionalities to quickly and easily plot the most
+common types of symbolic expressions (line plots, surface plots,
+parametric plots, vector plots, complex plots, control system plots).
 
 Most of the plotting functions can also automatically generates widgets
 (sliders, buttons, ...) starting from symbolic expressions. It allows to
@@ -30,8 +30,33 @@ without the knowledge of complicated widget libraries.
   :width: 220
   :alt: 3D surface
 
+
+Development and Support
+=======================
+
+If you feel like a feature could be implemented, open an issue or create a PR.
+
+If you really want a new feature but you don't have the capabilities or the
+time to make it work, I'm willing to help; but first, open an issue or send
+me an email so that we can discuss a sponsorship strategy.
+
+Developing this module and its documentation was no easy job. Implementing
+new feature and fixing bugs requires time and energy too. If you found this
+module useful, you can show your appreciation by sponsoring this project:
+
+.. button-link:: https://www.buymeacoffee.com/davide_sd
+    :color: primary
+
+    :fas:`mug-hot;fa-xl` Buy me a Coffee
+
+.. button-link:: https://github.com/sponsors/Davide-sd
+    :color: primary
+
+    :fab:`github;fa-xl` Github Sponsor :fas:`heart;fa-xl`
+
+
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
    overview.rst

doc/source/modules/backends/index.rst

@@ -3,33 +3,32 @@ Backends
 
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    plot.rst
    matplotlib.rst
    bokeh.rst
    plotly.rst
    k3d.rst
-   mayavi.rst
 
-This module allows the user to chose between 5 different backends.
+This module allows the user to chose between 4 different backends.
 The use case is summarized in the following table.
 
-+------------------------+-----------+-------+--------+------+--------+
-|                        | Matplolib | Bokeh | Plotly |  K3D | Mayavi |
-+========================+===========+=======+========+======+========+
-|           2D           |     Y     |   Y   |    Y   |   N  |    N   |
-+------------------------+-----------+-------+--------+------+--------+
-|           3D           |     Y     |   N   |    Y   |   Y  |    Y   |
-+------------------------+-----------+-------+--------+------+--------+
-|      Latex Support     |     Y     |   N   |    Y   |   Y  |    Y   |
-+------------------------+-----------+-------+--------+------+--------+
-|       Jupyter NB       |     Y     |   Y   |    Y   |   Y  |    Y   |
-+------------------------+-----------+-------+--------+------+--------+
-|   Python Interpreter   |     Y     |   Y   |    Y   |   N  |    Y   |
-+------------------------+-----------+-------+--------+------+--------+
-|   Interactive Widgets  |     Y     |   Y   |    Y   |   Y  |    N   |
-+------------------------+-----------+-------+--------+------+--------+
++------------------------+-----------+-------+--------+------+
+|                        | Matplolib | Bokeh | Plotly |  K3D |
++========================+===========+=======+========+======+
+|           2D           |     Y     |   Y   |    Y   |   N  |
++------------------------+-----------+-------+--------+------+
+|           3D           |     Y     |   N   |    Y   |   Y  |
++------------------------+-----------+-------+--------+------+
+|      Latex Support     |     Y     |   N   |    Y   |   Y  |
++------------------------+-----------+-------+--------+------+
+|       Jupyter NB       |     Y     |   Y   |    Y   |   Y  |
++------------------------+-----------+-------+--------+------+
+|   Python Interpreter   |     Y     |   Y   |    Y   |   N  |
++------------------------+-----------+-------+--------+------+
+|   Interactive Widgets  |     Y     |   Y   |    Y   |   Y  |
++------------------------+-----------+-------+--------+------+
 
 In particular:
 
@@ -48,7 +47,6 @@ In particular:
   * Lack of gradient lines.
   * Doesn't support ``plot_implicit``.
   * Contour capabilities are limited in comparison to Matplotlib.
-  * No wireframe support for 3D plots.
 
 * Bokeh: interactivity and data exploration are great. It supports auto-update
   while panning the plot (only works with 2D lines), however:
@@ -65,10 +63,6 @@ In particular:
   scale the visualization. What you see is the object as you would see it in
   reality.
 
-* Mayavi only support 3D plots. Differently from K3D, a custom aspect ratio
-  can be used. However, it offers much more customization options after the
-  plot has been created.
-
 We can choose the appropriate backend for our use case at runtime by setting the keyword argument ``backend=`` in the function call. We can also
 set the default backends for 2D and 3D plots in a configuration file by using
 the :doc:`Defaults module <../defaults>` .

doc/source/modules/renderers.rst

@@ -7,7 +7,3 @@ Renderers
 
 .. autoclass:: Renderer
 
-
-.. module:: spb.backends.matplotlib.renderers.renderer
-
-.. autoclass:: MatplotlibRenderer

doc/source/overview.rst

@@ -22,9 +22,7 @@ libraries):
 `Matplotlib <https://matplotlib.org/>`_,
 `Plotly <https://plotly.com/>`_,
 `Bokeh <https://github.com/bokeh/bokeh>`_,
-`K3D-Jupyter <https://github.com/K3D-tools/K3D-jupyter>`_,
-`Mayavi <https://docs.enthought.com/mayavi/mayavi/>`_ (support for this backend
-is limited).
+`K3D-Jupyter <https://github.com/K3D-tools/K3D-jupyter>`_.
 
 The 3 most important reasons for supporting multiple backends are:
 
@@ -37,10 +35,7 @@ The 3 most important reasons for supporting multiple backends are:
    translates to better data exploration and visualization (especially when
    working with Jupyter Notebook).
 
-#. To use the **plotting library we are most comfortable with**. The backend
-   can be used as a starting point to plot symbolic expressions; then, we could
-   use the figure object to add numerical (or experimental) results using the
-   commands associated to the specific plotting library.
+#. To use the **plotting library we are most comfortable with**.
 
 More information about the backends can be found at:
 :doc:`Backends </modules/backends/index>` .
@@ -51,9 +46,7 @@ Examples
 
 The following code blocks shows a few examples about the capabilities of
 this module. Please, try them on a Jupyter Notebook to explore the interactive
-figures. Alternatively, consider loading the ``html`` output when available:
-note that changing the state of widgets won't update the plot as there is no
-active Python kernel running on this web page.
+figures.
 
 
 Interactive-Parametric 2D plot of the magnitude of a second order transfer
@@ -264,21 +257,14 @@ Differences with sympy.plotting
 * While the backends implemented in this module might resemble the ones from
   the `sympy.plotting` module, they are not interchangeable.
 
-* `sympy.plotting` also provides a ``Plotgrid`` class to combine multiple plots
-  into a grid-like layout. This module replaces that class with the
-  ``plotgrid`` function. Again, they are not interchangeable.
-
 * The ``plot_implicit`` function uses a mesh grid algorithm and contour plots
   by default (in contrast to the adaptive algorithm used by `sympy.plotting`).
   It is going to automatically switch to an adaptive algorithm if
   Boolean expressions are found. This ensures a better visualization for
   non-Boolean implicit expressions.
 
-* ``experimental_lambdify``, used by `sympy.plotting`, has been completely
-  removed.
-
 * `sympy.plotting` is unable to visualize summations containing infinity in
-  their lower/upper bounds. The new module introduces the ``sum_bound`` keyword
+  their lower/upper bounds. This module introduces the ``sum_bound`` keyword
   argument into the ``plot`` function: it substitutes infinity with a large
   integer number. As such, it is possible to visualize summations.
 

spb/backends/base_backend.py

@@ -17,20 +17,23 @@ class Plot:
 
     1. The user creates the symbolic expressions and calls one of the plotting
        functions.
-    2. The plotting functions generate a list of instances of the `BaseSeries`
-       class, containing the necessary information to plot the expressions
-       (eg the expression, ranges, series name, ...). Eventually, these
-       objects will generate the numerical data to be plotted.
-    3. The plotting functions instantiate the `Plot` class, which stores the
+    2. The plotting functions generate a list of instances of ``BaseSeries``,
+       containing the necessary information to generate the appropriate
+       numerical data and create the proper visualization
+       (eg the expression, ranges, series name, ...).
+    3. The plotting functions instantiate the ``Plot`` class, which stores the
        list of series and the main attributes of the plot (eg axis labels,
-       title, etc.). Among the keyword arguments, there must be `backend`,
-       a subclass of `Plot` which specify the backend to be used.
-    4. The backend will render the numerical data to a plot and (eventually)
-       show it on the screen. The figure is populated with numerical data once
-       the `show()` method or the `fig` attribute are called.
+       title, etc.). Among the keyword arguments, there must be ``backend=``,
+       where a subclass of ``Plot`` can be specified in order to use a
+       particular plotting library.
+    4. Each data series will be associated to a corresponding renderer, which
+       receives the numerical data and add it to the figure. A renderer is also
+       responsible to keep objects up-to-date when interactive-widgets plots
+       are used. The figure is populated with numerical data when the
+       ``show()`` method or the ``fig`` attribute are called.
 
     The backend should check if it supports the data series that it's given.
-    Please, explore the `MatplotlibBackend` source code to understand how a
+    Please, explore ``MatplotlibBackend`` source code to understand how a
     backend should be coded.
 
     Also note that setting attributes to plot objects or to data series after
@@ -48,7 +51,7 @@ class Plot:
     * ``save(self, path, **kwargs)``: used to save the current plot to the
       specified file path.
     * ``self._fig``: an instance attribute to store the backend-specific plot
-      object, which can be retrieved with the `Plot.fig` attribute. This
+      object, which can be retrieved with the ``Plot.fig`` attribute. This
       object can then be used to further customize the resulting plot, using
       backend-specific commands.
     * ``update_interactive(self, params)``: this method receives a dictionary