solve: do not call MEVAL.

[maxima.git] / doc / info / de / drawdf.de.texi

@c -----------------------------------------------------------------------------
@c File     : drawdf.de.texi
@c License  : GNU General Public License (GPL)
@c Language : German
@c Original : drawdf.texi revision 1.2
@c Date     : 28.11.2010
@c 
@c This file is part of Maxima -- GPL CAS based on DOE-MACSYMA
@c -----------------------------------------------------------------------------

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

@c -----------------------------------------------------------------------------
@node Introduction to drawdf, Functions and Variables for drawdf, drawdf, drawdf
@section Introduction to drawdf

The function @code{drawdf} draws 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("drawdf")}.  Drawdf is built upon the @code{draw}
package, which requires Gnuplot 4.2.

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{drawdf}. 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 drawdf 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{drawdf} 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 drawdf 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{drawdf} will implicitly admit
@code{x=t}, and @code{G(x,y)=1}, transforming the non-autonomous
equation into a system of two autonomous equations.

@c @opencatbox
@c @category{Differential equations} @category{Plotting}
@c @category{Share packages} @category{Package drawdf}
@c @category{Package draw}
@c @closecatbox

@c -----------------------------------------------------------------------------
@node Functions and Variables for drawdf,  , Introduction to drawdf, drawdf
@section Functions and Variables for drawdf

@c -----------------------------------------------------------------------------
@subsection Functions

@c -----------------------------------------------------------------------------
@anchor{function_drawdf}
@deffn  {Function} drawdf (@var{dydx}, ...options and objects...)
@deffnx {Function} drawdf (@var{dvdu}, @code{[}@var{u},@var{v}@code{]}, ...options and objects...)
@deffnx {Function} drawdf (@var{dvdu}, @code{[}@var{u},@var{umin},@var{umax}@code{]}, @code{[}@var{v},@var{vmin},@var{vmax}@code{]}, ...options and objects...)
@deffnx {Function} drawdf (@code{[}@var{dxdt},@var{dydt}@code{]}, ...options and objects...)
@deffnx {Function} drawdf (@code{[}@var{dudt},@var{dvdt}@code{]}, @code{[}@var{u},@var{v}@code{]}, ...options and objects...)
@deffnx {Function} drawdf (@code{[}@var{dudt},@var{dvdt}@code{]}, @code{[}@var{u},@var{umin},@var{umax}@code{]}, @code{[}@var{v},@var{vmin},@var{vmax}@code{]}, ...options and objects...)

Function @code{drawdf} draws a 2D direction field with optional
solution curves and other graphics using the @code{draw} package.

The first argument specifies the derivative(s), and must be either an
expression or a list of two expressions.  @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}.

If the independent and dependent variables are not @var{x} and
@var{y}, then their names must be specified immediately following the
derivative(s), either as a list of two names
@code{[}@var{u},@var{v}@code{]}, or as two lists of the form
@code{[}@var{u},@var{umin},@var{umax}@code{]} and
@code{[}@var{v},@var{vmin},@var{vmax}@code{]}.

The remaining arguments are @i{graphic options}, @i{graphic objects},
or lists containing graphic options and objects, nested to arbitrary
depth.  The set of graphic options and objects supported by
@code{drawdf} is a superset of those supported by @code{draw2d} and
@code{gr2d} from the @code{draw} package.

The arguments are interpreted sequentially: @i{graphic options} affect
all following @i{graphic objects}.  Furthermore, @i{graphic objects}
are drawn on the canvas in order specified, and may obscure graphics
drawn earlier.  Some @i{graphic options} affect the global appearence
of the scene.

The additional @i{graphic objects} supported by @code{drawdf} include:
@code{solns_at}, @code{points_at}, @code{saddles_at}, @code{soln_at},
@code{point_at}, and @code{saddle_at}.

The additional @i{graphic options} supported by @code{drawdf} include:
@code{field_degree}, @code{soln_arrows}, @code{field_arrows},
@code{field_grid}, @code{field_color}, @code{show_field},
@code{tstep}, @code{nsteps}, @code{duration}, @code{direction},
@code{field_tstep}, @code{field_nsteps}, and @code{field_duration}.

Commonly used @i{graphic objects} inherited from the @code{draw}
package include: @code{explicit}, @code{implicit}, @code{parametric},
@code{polygon}, @code{points}, @code{vector}, @code{label}, and all
others supported by @code{draw2d} and @code{gr2d}.

Commonly used @i{graphic options} inherited from the @code{draw}
package include: 
@flushleft
@code{points_joined}, @code{color},
@code{point_type}, @code{point_size}, @code{line_width},
@code{line_type}, @code{key}, @code{title}, @code{xlabel},
@code{ylabel}, @code{user_preamble}, @code{terminal},
@code{dimensions}, @code{file_name}, and all
others supported by @code{draw2d} and @code{gr2d}.
@end flushleft

See also @code{draw2d}. 

Users of wxMaxima or Imaxima may optionally use @code{wxdrawdf}, which
is identical to @code{drawdf} except that the graphics are drawn
within the notebook using @code{wxdraw}.

To make use of this function, write first @code{load("drawdf")}.

Examples:

@example
(%i1) load("drawdf")$
(%i2) drawdf(exp(-x)+y)$        /* default vars: x,y */
(%i3) drawdf(exp(-t)+y, [t,y])$ /* default range: [-10,10] */
(%i4) drawdf([y,-9*sin(x)-y/5], [x,1,5], [y,-2,2])$
@end example

For backward compatibility, @code{drawdf} accepts
most of the parameters supported by plotdf.

@example
(%i5) drawdf(2*cos(t)-1+y, [t,y], [t,-5,10], [y,-4,9],
             [trajectory_at,0,0])$
@end example

@code{soln_at} and @code{solns_at} draw solution curves
passing through the specified points, using a slightly
enhanced 4th-order Runge Kutta numerical integrator.

@example
(%i6) drawdf(2*cos(t)-1+y, [t,-5,10], [y,-4,9],
             solns_at([0,0.1],[0,-0.1]),
             color=blue, soln_at(0,0))$
@end example

@code{field_degree=2} causes the field to be composed of quadratic
splines, based on the first and second derivatives at each grid point.
@code{field_grid=[}@var{COLS},@var{ROWS}@code{]} specifies the number
of columns and rows in the grid.

@example
(%i7) drawdf(2*cos(t)-1+y, [t,-5,10], [y,-4,9],
             field_degree=2, field_grid=[20,15],
             solns_at([0,0.1],[0,-0.1]),
             color=blue, soln_at(0,0))$
@end example

@code{soln_arrows=true} adds arrows to the solution curves, and (by
default) removes them from the direction field.  It also changes the
default colors to emphasize the solution curves.

@example
(%i8) drawdf(2*cos(t)-1+y, [t,-5,10], [y,-4,9],
             soln_arrows=true,
             solns_at([0,0.1],[0,-0.1],[0,0]))$
@end example

@code{duration=40} specifies the time duration of numerical
integration (default 10).  Integration will also stop automatically if
the solution moves too far away from the plotted region, or if the
derivative becomes complex or infinite.  Here we also specify
@code{field_degree=2} to plot quadratic splines.  The equations below
model a predator-prey system.

@example
(%i9) drawdf([x*(1-x-y), y*(3/4-y-x/2)], [x,0,1.1], [y,0,1],
             field_degree=2, duration=40,
             soln_arrows=true, point_at(1/2,1/2),
             solns_at([0.1,0.2], [0.2,0.1], [1,0.8], [0.8,1],
                      [0.1,0.1], [0.6,0.05], [0.05,0.4],
                      [1,0.01], [0.01,0.75]))$
@end example

@code{field_degree='solns} causes the field to be composed
of many small solution curves computed by 4th-order
Runge Kutta, with better results in this case.

@example
(%i10) drawdf([x*(1-x-y), y*(3/4-y-x/2)], [x,0,1.1], [y,0,1],
              field_degree='solns, duration=40,
              soln_arrows=true, point_at(1/2,1/2),
              solns_at([0.1,0.2], [0.2,0.1], [1,0.8],
                       [0.8,1], [0.1,0.1], [0.6,0.05],
                       [0.05,0.4], [1,0.01], [0.01,0.75]))$
@end example

@code{saddles_at} attempts to automatically linearize the equation at
each saddle, and to plot a numerical solution corresponding to each
eigenvector, including the separatrices.  @code{tstep=0.05} specifies
the maximum time step for the numerical integrator (the default is
0.1).  Note that smaller time steps will sometimes be used in order to
keep the x and y steps small.  The equations below model a damped
pendulum.

@example
(%i11) drawdf([y,-9*sin(x)-y/5], tstep=0.05,
              soln_arrows=true, point_size=0.5,
              points_at([0,0], [2*%pi,0], [-2*%pi,0]),
              field_degree='solns,
              saddles_at([%pi,0], [-%pi,0]))$
@end example

@code{show_field=false} suppresses the field entirely.

@example
(%i12) drawdf([y,-9*sin(x)-y/5], tstep=0.05,
              show_field=false, soln_arrows=true,
              point_size=0.5,
              points_at([0,0], [2*%pi,0], [-2*%pi,0]),
              saddles_at([3*%pi,0], [-3*%pi,0],
                         [%pi,0], [-%pi,0]))$
@end example

@code{drawdf} passes all unrecognized parameters to @code{draw2d} or
@code{gr2d}, allowing you to combine the full power of the @code{draw}
package with @code{drawdf}.

@example
(%i13) drawdf(x^2+y^2, [x,-2,2], [y,-2,2], field_color=gray,
              key="soln 1", color=black, soln_at(0,0),
              key="soln 2", color=red, soln_at(0,1),
              key="isocline", color=green, line_width=2,
              nticks=100, parametric(cos(t),sin(t),t,0,2*%pi))$
@end example

@code{drawdf} accepts nested lists of graphic options and objects,
allowing convenient use of makelist and other function calls to
generate graphics.

@example
(%i14) colors : ['red,'blue,'purple,'orange,'green]$
(%i15) drawdf([x-x*y/2, (x*y - 3*y)/4],
              [x,2.5,3.5], [y,1.5,2.5],
              field_color = gray,
              makelist([ key   = concat("soln",k),
                         color = colors[k],
                         soln_at(3, 2 + k/20) ],
                       k,1,5))$
@end example

@c @opencatbox
@c @category{Package drawdf}
@c @closecatbox
@end deffn

@c --- End of file draw.de.texi ------------------------------------------------