updated documentation for phaseplot module

lkies · lkies · commit 81d9c1e2ecd3 · 2025-02-09T22:52:12.000+01:00
diff --git a/doc/phaseplot.rst b/doc/phaseplot.rst
@@ -12,7 +12,7 @@ functionality is supported by a set of mapping functions that are part of
 the `phaseplot` module.
 
 The default method for generating a phase plane plot is to provide a
-2D dynamical system along with a range of coordinates and time limit:
+2D dynamical system along with a range of coordinates in phase space:
 
 .. testsetup:: phaseplot
 
@@ -27,8 +27,7 @@ The default method for generating a phase plane plot is to provide a
         sys_update, states=['position', 'velocity'],
 	inputs=0, name='damped oscillator')
     axis_limits = [-1, 1, -1, 1]
-    T = 8
-    ct.phase_plane_plot(sys, axis_limits, T)
+    ct.phase_plane_plot(sys, axis_limits)
 
 .. testcode:: phaseplot
     :hide:
@@ -39,12 +38,12 @@ The default method for generating a phase plane plot is to provide a
 .. image:: figures/phaseplot-dampedosc-default.png
    :align: center
 
-By default, the plot includes streamlines generated from starting
-points on limits of the plot, with arrows showing the flow of the
-system, as well as any equilibrium points for the system.  A variety
+By default the plot includes streamlines infered from function values
+on a grid, equilibrium points and separatrices if they exist. A variety
 of options are available to modify the information that is plotted,
-including plotting a grid of vectors instead of streamlines and
-turning on and off various features of the plot.
+including plotting a grid of vectors instead of streamlines, plotting
+streamlines from arbitrary starting points and turning on and off
+various features of the plot. 
 
 To illustrate some of these possibilities, consider a phase plane plot for
 an inverted pendulum system, which is created using a mesh grid:
@@ -62,9 +61,7 @@ an inverted pendulum system, which is created using a mesh grid:
     invpend = ct.nlsys(invpend_update, states=2, inputs=1, name='invpend')
 
     ct.phase_plane_plot(
-        invpend, [-2 * np.pi, 2 * np.pi, -2, 2], 5,
-        gridtype='meshgrid', gridspec=[5, 8], arrows=3,
-        plot_equilpoints={'gridspec': [12, 9]},
+        invpend, [-2 * np.pi, 2 * np.pi, -2, 2],
         params={'m': 1, 'l': 1, 'b': 0.2, 'g': 1})
     plt.xlabel(r"$\theta$ [rad]")
     plt.ylabel(r"$\dot\theta$ [rad/sec]")
@@ -79,16 +76,17 @@ an inverted pendulum system, which is created using a mesh grid:
 
 This figure shows several features of more complex phase plane plots:
 multiple equilibrium points are shown, with saddle points showing
-separatrices, and streamlines generated along a 5x8 mesh of initial
-conditions.  At each mesh point, a streamline is created that goes 5 time
-units forward and backward in time.  A separate grid specification is used
-to find equilibrium points and separatrices (since the course grid spacing
-of 5x8 does not find all possible equilibrium points).  Together, the
-multiple features in the phase plane plot give a good global picture of the
-topological structure of solutions of the dynamical system.
+separatrices, and streamlines generated generated from a rectangular 25x25
+grid (default) of function evaluations. Together, the multiple features in
+the phase plane plot give a good global picture of the topological structure
+of solutions of the dynamical system.
 
 Phase plots can be built up by hand using a variety of helper functions that
-are part of the :mod:`phaseplot` (pp) module:
+are part of the :mod:`phaseplot` (pp) module. For more precise control, the
+streamlines can also generated by integrating the system forwads or backwards
+in time from a set of initial conditions. The initial conditions can be chosen
+on a rectangular grid, rectangual boundary, circle or from an arbitrary set of
+points.
 
 .. testcode:: phaseplot
     :hide:
@@ -105,7 +103,8 @@ are part of the :mod:`phaseplot` (pp) module:
     oscillator = ct.nlsys(
         oscillator_update, states=2, inputs=0, name='nonlinear oscillator')
 
-    ct.phase_plane_plot(oscillator, [-1.5, 1.5, -1.5, 1.5], 0.9)
+    ct.phase_plane_plot(oscillator, [-1.5, 1.5, -1.5, 1.5], 0.9,
+        plot_streamlines=True)
     pp.streamlines(
         oscillator, np.array([[0, 0]]), 1.5,
         gridtype='circlegrid', gridspec=[0.5, 6], dir='both')
@@ -129,6 +128,7 @@ The following helper functions are available:
    phaseplot.separatrices
    phaseplot.streamlines
    phaseplot.vectorfield
+   phaseplot.streamplot
 
 The :func:`phase_plane_plot` function calls these helper functions
 based on the options it is passed.
