@menu
* Introduction to plotdf::
* Functions and Variables for plotdf::
@end menu

@node Introduction to plotdf, Functions and Variables for plotdf, plotdf, plotdf
@section Introduction to plotdf

The function @code{plotdf} creates a plot of the direction field of a
first-order Ordinary Differential Equation (ODE) or a system of two
autonomous first-order ODE's.

Since this is an additional package, in order to use it you must first
load it with @code{load("plotdf")}. Plotdf requires Openmath, which is
provided by the package Xmaxima (Xmaxima is not only used as a graphical
console for Maxima but also to plot graphs in the Openmath format).

To plot the direction field of a single ODE, the ODE must be written in
the form:
@ifnottex
@example
       dy
       -- = F(x,y)
       dx
@end example
@end ifnottex
@tex
$${{dy}\over{dx}} = F(x,y)$$
@end tex

and the function @var{F} should be given as the argument for
@code{plotdf}. If the independent and dependent variables are not @var{x},
and @var{y}, as in the equation above, then those two variables should
be named explicitly in a list given as an argument to the plotdf command
(see the examples).

To plot the direction field of a set of two autonomous ODE's, they must
be written in the form
@ifnottex
@example
       dx             dy
       -- = G(x,y)    -- = F(x,y) 
       dt             dt
@end example
@end ifnottex
@tex
$${{dx}\over{dt}} = G(x,y) \qquad {{dy}\over{dt}} = F(x,y)$$
@end tex

and the argument for @code{plotdf} should be a list with the two
functions @var{G} and @var{F}, in that order; namely, the first
expression in the list will be taken to be the time derivative of the
variable represented on the horizontal axis, and the second expression
will be the time derivative of the variable represented on the vertical
axis. Those two variables do not have to be @var{x} and @var{y}, but if
they are not, then the second argument given to plotdf must be another
list naming the two variables, first the one on the horizontal axis and
then the one on the vertical axis.

If only one ODE is given, @code{plotdf} will implicitly admit
@code{x=t}, and @code{G(x,y)=1}, transforming the non-autonomous
equation into a system of two autonomous equations.

@opencatbox
@category{Differential equations} @category{Share packages} @category{Package plotdf}
@closecatbox

@node Functions and Variables for plotdf,  , Introduction to plotdf, plotdf
@section Functions and Variables for plotdf

@deffn {Function} plotdf (@var{dydx}, ...options...)
@deffnx {Function} plotdf (@var{dvdu}, @code{[}@var{u},@var{v}@code{]}, ...options...)
@deffnx {Function} plotdf (@code{[}@var{dxdt},@var{dydt}@code{]}, ...options...)
@deffnx {Function} plotdf (@code{[}@var{dudt},@var{dvdt}@code{]}, @code{[}@var{u},@var{v}@code{]}, ...options...)

Displays a direction field in two dimensions @var{x} and @var{y}.

@var{dydx}, @var{dxdt} and @var{dydt} are expressions that depend on
@var{x} and @var{y}. @var{dvdu}, @var{dudt} and @var{dvdt} are
expressions that depend on @var{u} and @var{v}. In addition to those two
variables, the expressions can also depend on a set of parameters, with
numerical values given with the @code{parameters} option (the option
syntax is given below), or with a range of allowed values specified by a
@var{sliders} option.

Several other options can be given within the command, or selected in
the menu. Integral curves can be obtained by clicking on the plot, or
with the option @code{trajectory_at}. The direction of the integration
can be controlled with the @code{direction} option, which can have
values of @emph{forward}, @emph{backward} or @emph{both}. The number of
integration steps is given by @code{nsteps} and the time interval
between them is set up with the @code{tstep} option. The Adams Moulton
method is used for the integration; it is also possible to switch to an
adaptive Runge-Kutta 4th order method.

@b{Plot window menu:}

The menu in the plot window has the following options: @emph{Zoom}, will
change the behavior of the mouse so that it will allow you to zoom in on
a region of the plot by clicking with the left button. Each click near a
point magnifies the plot, keeping the center at the point where you
clicked. Holding the @key{Shift} key while clicking, zooms out to the
previous magnification. To resume computing trajectories when you click
on a point, select @emph{Integrate} from the menu.

The option @emph{Config} in the menu can be used to change the ODE(s) in
use and various other settings. After configuration changes are made,
the menu option @emph{Replot} should be selected, to activate the new
settings.  If a pair of coordinates are entered in the field
@emph{Trajectory at} in the @emph{Config} dialog menu, and the
@key{enter} key is pressed, a new integral curve will be shown, in
addition to the ones already shown. When @emph{Replot} is selected, only
the last integral curve entered will be shown.

Holding the right mouse button down while the cursor is moved, can be
used to drag the plot sideways or up and down. Additional
parameters such as the number of steps, the initial value of @var{t}
and the x and y centers and radii, may be set in the Config menu.

A copy of the plot can be saved as a postscript file, using the menu
option @emph{Save}.

@b{Plot options:}

The @code{plotdf} command may include several commands, each command is
a list of two or more items.  The first item is the name of the option,
and the remainder comprises the value or values assigned to the option.

The options which are recognized by @code{plotdf} are the following:

@itemize @bullet
@item
@dfn{tstep} defines the length of the increments on the
independent variable @var{t}, used to compute an integral curve. If only
one expression @var{dydx} is given to @code{plotdf}, the @var{x}
variable will be directly proportional to @var{t}.
The default value is 0.1.

@item
@dfn{nsteps} defines the number of steps of length @code{tstep}
that will be used for the independent variable, to compute an integral
curve.
The default value is 100.

@item
@dfn{direction} defines the direction of the independent
variable that will be followed to compute an integral curve. Possible
values are @code{forward}, to make the independent variable increase
@code{nsteps} times, with increments @code{tstep}, @code{backward}, to
make the independent variable decrease, or @code{both} that will lead to
an integral curve that extends @code{nsteps} forward, and @code{nsteps}
backward. The keywords @code{right} and @code{left} can be used as
synonyms for @code{forward} and @code{backward}.
The default value is @code{both}.

@item
@dfn{tinitial} defines the initial value of variable @var{t} used
to compute integral curves. Since the differential equations are
autonomous, that setting will only appear in the plot of the curves as
functions of @var{t}. 
The default value is 0.

@item
@dfn{versus_t} is used to create a second plot window, with a
plot of an integral curve, as two functions @var{x}, @var{y}, of the
independent variable @var{t}. If @code{versus_t} is given any value
different from 0, the second plot window will be displayed. The second
plot window includes another menu, similar to the menu of the main plot
window.
The default value is 0.

@item
@dfn{trajectory_at} defines the coordinates @var{xinitial} and
@var{yinitial} for the starting point of an integral curve.
The option is empty by default.

@item
@dfn{parameters} defines a list of parameters, and their
numerical values, used in the definition of the differential
equations. The name and values of the parameters must be given in a
string with a comma-separated sequence of pairs @code{name=value}.

@item
@dfn{sliders} defines a list of parameters that will be changed
interactively using slider buttons, and the range of variation of those
parameters. The names and ranges of the parameters must be given in a
string with a comma-separated sequence of elements @code{name=min:max}

@item
@dfn{xfun} defines a string with semi-colon-separated sequence
of functions of @var{x} to be displayed, on top of the direction field.
Those functions will be parsed by Tcl and not by Maxima.

@item
@dfn{x} should be followed by two numbers, which will set up the minimum
and maximum values shown on the horizontal axis. If the variable on the
horizontal axis is not @var{x}, then this option should have the name of
the variable on the horizontal axis.
The default horizontal range is from -10 to 10.

@item
@dfn{y} should be followed by two numbers, which will set up the minimum
and maximum values shown on the vertical axis. If the variable on the
vertical axis is not @var{y}, then this option should have the name of
the variable on the vertical axis.
The default vertical range is from -10 to 10.
@end itemize

@b{Examples:}

@itemize @bullet
@item
To show the direction field of the differential equation @math{y' = exp(-x) + y} and the solution that goes through @math{(2, -0.1)}:
@example
(%i1) load("plotdf")$

(%i2) plotdf(exp(-x)+y,[trajectory_at,2,-0.1])$
@end example

@ifnotinfo
@image{figures/plotdf1,8cm}
@end ifnotinfo

@item
To obtain the direction field for the equation @math{diff(y,x) = x - y^2} and the solution with initial condition @math{y(-1) = 3}, we can use the command:
@example
(%i3) plotdf(x-y^2,[xfun,"sqrt(x);-sqrt(x)"],
          [trajectory_at,-1,3], [direction,forward],
          [y,-5,5], [x,-4,16])$
@end example
The graph also shows the function @math{y = sqrt(x)}. 

@ifnotinfo
@image{figures/plotdf2,8cm}
@end ifnotinfo

@item
The following example shows the direction field of a harmonic oscillator,
defined by the two equations @math{dz/dt = v} and @math{dv/dt = -k*z/m},
and the integral curve through @math{(z,v) = (6,0)}, with a slider that
will allow you to change the value of @math{m} interactively (@math{k} is
fixed at 2):
@example
(%i4) plotdf([v,-k*z/m], [z,v], [parameters,"m=2,k=2"],
            [sliders,"m=1:5"], [trajectory_at,6,0])$
@end example

@ifnotinfo
@image{figures/plotdf3,8cm}
@end ifnotinfo

@item
To plot the direction field of the Duffing equation, @math{m*x''+c*x'+k*x+b*x^3 = 0}, we introduce the variable @math{y=x'} and use:
@example
(%i5) plotdf([y,-(k*x + c*y + b*x^3)/m],
              [parameters,"k=-1,m=1.0,c=0,b=1"],
              [sliders,"k=-2:2,m=-1:1"],[tstep,0.1])$
@end example

@ifnotinfo
@image{figures/plotdf4,8cm}
@end ifnotinfo

@item
The direction field for a damped pendulum, including the
solution for the given initial conditions, with a slider that
can be used to change the value of the mass @math{m}, and with a plot of
the two state variables as a function of time:

@example
(%i6) plotdf([w,-g*sin(a)/l - b*w/m/l], [a,w],
         [parameters,"g=9.8,l=0.5,m=0.3,b=0.05"],
         [trajectory_at,1.05,-9],[tstep,0.01],
         [a,-10,2], [w,-14,14], [direction,forward],
         [nsteps,300], [sliders,"m=0.1:1"], [versus_t,1])$
@end example

@ifnotinfo
@image{figures/plotdf5,8cm}@image{figures/plotdf6,8cm}
@end ifnotinfo

@end itemize

@opencatbox
@category{Package plotdf} @category{Plotting} @category{Numerical methods}
@closecatbox

@end deffn