@menu
* Introduction to plotdf::
* Definitions for plotdf::
@end menu

@node Introduction to plotdf, Definitions 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.

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}. The independent variable is always identified as @var{x},
and the dependent variable as @var{y}. Those two variables should not
have any values assigned to them.

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{F} and @var{G}, in any order.

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.

@node Definitions for plotdf,  , Introduction to plotdf, plotdf
@section Definitions for plotdf

@deffn {Function} plotdf (@var{dydx},...options...)
@deffnx {Function} plotdf (@code{[}@var{dxdt},@var{dydt}@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}. 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 an range of allowed values specified by a
@var{sliders} option.

Several other options can be given within the command, or entered into
the menu that will appear when the upper-left corner of the plot window
is clicked. 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 "forward", "backward" or "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: "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 SHIFT key while clicking, zooms out to the
previous magnification. To resume computing trajectories when you
click on a point, select "Integrate" from the menu.

The option "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 "Replot" should be selected, to activate the new settings.
If a pair of coordinates are entered in the field "Trajectory at" in the
"Config" dialog menu, and the "enter" key is pressed, a new integral
curve will be shown, in addition to the ones already shown. When
"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 printed to a Postscript printer, or saved as a
postscript file, using the menu option "Save". To switch between
printing and saving to a Postscript file, "Print Options" should be
selected in the dialog window of "Config". After the settings in the
"Save" dialog window are entered, "Save'' must be selected in the first
menu, to create the file or print the plot.

@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
Option: @code{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}: @code{x - xinitial =
t - tinitial}.
@example
[tstep,0.01]
@end example
The default value is 0.1.

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

@item
Option: @code{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}.
@example
[direction,forward]
@end example
The defaul value is @code{both}.

@item
Option: @code{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}. 
@example
[tinitial,6.7]
@end example
The default value is 0.

@item
Option: @code{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.
@example
[versus_t,1]
@end example
The default value is 0.

@item
Option: @code{trajectory_at} defines the coordinates @var{xinitial} and
@var{yinitial} for the starting point of an integral curve.
@example
[trajectory_at,0.1,3.2]
@end example
The option is empty by default.

@item
Option @code{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}.
@example
[parameters,"k=1.1,m=2.5"]
@end example

@item
Option: @code{sliders} defines a list o 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}
@example
[sliders,"k=0:4,m=1:3"]
@end example

@item
Option: @code{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.
@example 
[xfun,"x^2;sin(x);exp(x)"]
@end example

@item
Option: @code{xradius} is half of the length of the range of values that
will be shown in the x direction.
@example
[xradius,12.5]
@end example
the default value is 10.

@item
Option: @code{yradius} is half of the length of the range of values that
will be shown in the y direction.
@example
[yradius,15]
@end example
the default value is 10.

@item
Option: @code{xcenter} is the x coordinate of the point at the center of
the plot.
@example
[xcenter,3.45]
@end example
The default value is 0.

@item
Option: @code{ycenter} is the y coordinate of the point at the center of
the plot.
@example
[ycenter,4.5]
@end example
The default value is 0.

@item
Option: @code{width} defines the width of the plot window, in pixels.
@example
[width,800]
@end example
The default value is 500.

@item
Option: @code{height} defines the height of the plot window, in pixels.
@example
[width,600]
@end example
The default value is 500.
@end itemize

@b{Examples:}

NOTE: Due to a bug in @code{openmath}, all commands that use it, in particular
@code{plotdf}, must end with a semicolon and not with a dollar sign. The
dollar sign might work in some of the graphical interfaces to Maxima, but
to avoid problems we will use a semicolon in all the examples below.
  
@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],
          [yradius,5],[xcenter,6]);
@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{dx/dt = y} and @math{dy/dt = -k*x/m},
and the integral curve through @math{(x,y) = (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([y,-k*x/m],[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([y,-g*sin(x)/l - b*y/m/l],
         [parameters,"g=9.8,l=0.5,m=0.3,b=0.05"],
         [trajectory_at,1.05,-9],[tstep,0.01],
         [xradius,6],[yradius,14],
         [xcenter,-4],[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

To use this function write first @code{load("plotdf")}.
@end deffn