doc/info/drawdf.texi

   1 @menu
   2 * Introduction to drawdf::
   3 * Functions and Variables for drawdf::
   4 @end menu
   5
   6 @node Introduction to drawdf, Functions and Variables for drawdf, Package drawdf, Package drawdf
   7 @section Introduction to drawdf
   8
   9 The function @code{drawdf} draws the direction field of a first-order
  10 Ordinary Differential Equation (ODE) or a system of two autonomous
  11 first-order ODE's.
  12
  13 Since this is an additional package, in order to use it you must first
  14 load it with @code{load("drawdf")}.  Drawdf is built upon the @code{draw}
  15 package, which requires Gnuplot 4.2.
  16
  17 To plot the direction field of a single ODE, the ODE must be written in
  18 the form:
  19 @ifnottex
  20 @example
  21        dy
  22        -- = F(x,y)
  23        dx
  24 @end example
  25 @end ifnottex
  26 @tex
  27 $${{dy}\over{dx}} = F(x,y)$$
  28 @end tex
  29
  30 and the function @var{F} should be given as the argument for
  31 @code{drawdf}. If the independent and dependent variables are not @var{x},
  32 and @var{y}, as in the equation above, then those two variables should
  33 be named explicitly in a list given as an argument to the drawdf command
  34 (see the examples).
  35
  36 To plot the direction field of a set of two autonomous ODE's, they must
  37 be written in the form
  38 @ifnottex
  39 @example
  40        dx             dy
  41        -- = G(x,y)    -- = F(x,y)
  42        dt             dt
  43 @end example
  44 @end ifnottex
  45 @tex
  46 $${{dx}\over{dt}} = G(x,y) \qquad {{dy}\over{dt}} = F(x,y)$$
  47 @end tex
  48
  49 and the argument for @code{drawdf} should be a list with the two
  50 functions @var{G} and @var{F}, in that order; namely, the first
  51 expression in the list will be taken to be the time derivative of the
  52 variable represented on the horizontal axis, and the second expression
  53 will be the time derivative of the variable represented on the vertical
  54 axis. Those two variables do not have to be @var{x} and @var{y}, but if
  55 they are not, then the second argument given to drawdf must be another
  56 list naming the two variables, first the one on the horizontal axis and
  57 then the one on the vertical axis.
  58
  59 If only one ODE is given, @code{drawdf} will implicitly admit
  60 @code{x=t}, and @code{G(x,y)=1}, transforming the non-autonomous
  61 equation into a system of two autonomous equations.
  62
  63 @opencatbox{Categories:}
  64 @category{Differential equations}
  65 @category{Plotting}
  66 @category{Share packages}
  67 @category{Package drawdf}
  68 @category{Package draw}
  69 @closecatbox
  70
  71
  72 @node Functions and Variables for drawdf,  , Introduction to drawdf, Package drawdf
  73 @section Functions and Variables for drawdf
  74
  75 @subsection Functions
  76
  77 @anchor{drawdf}
  78 @deffn {Function} drawdf @
  79 @fname{drawdf} (@var{dydx}, ...options and objects...) @
  80 @fname{drawdf} (@var{dvdu}, [@var{u},@var{v}], ...options and objects...) @
  81 @fname{drawdf} (@var{dvdu}, [@var{u},@var{umin},@var{umax}], [@var{v},@var{vmin},@var{vmax}], ...options and objects...) @
  82 @fname{drawdf} ([@var{dxdt},@var{dydt}], ...options and objects...) @
  83 @fname{drawdf} ([@var{dudt},@var{dvdt}], [@var{u},@var{v}], ...options and objects...) @
  84 @fname{drawdf} ([@var{dudt},@var{dvdt}], [@var{u},@var{umin},@var{umax}], [@var{v},@var{vmin},@var{vmax}], ...options and objects...)
  85
  86 Function @code{drawdf} draws a 2D direction field with optional
  87 solution curves and other graphics using the @code{draw} package.
  88
  89 The first argument specifies the derivative(s), and must be either an
  90 expression or a list of two expressions.  @var{dydx}, @var{dxdt} and
  91 @var{dydt} are expressions that depend on @var{x} and @var{y}.
  92 @var{dvdu}, @var{dudt} and @var{dvdt} are expressions that depend on
  93 @var{u} and @var{v}.
  94
  95 If the independent and dependent variables are not @var{x} and
  96 @var{y}, then their names must be specified immediately following the
  97 derivative(s), either as a list of two names
  98 @code{[}@var{u},@var{v}@code{]}, or as two lists of the form
  99 @code{[}@var{u},@var{umin},@var{umax}@code{]} and
 100 @code{[}@var{v},@var{vmin},@var{vmax}@code{]}.
 101
 102 The remaining arguments are @i{graphic options}, @i{graphic objects},
 103 or lists containing graphic options and objects, nested to arbitrary
 104 depth.  The set of graphic options and objects supported by
 105 @code{drawdf} is a superset of those supported by @code{draw2d} and
 106 @code{gr2d} from the @code{draw} package.
 107
 108 The arguments are interpreted sequentially: @i{graphic options} affect
 109 all following @i{graphic objects}.  Furthermore, @i{graphic objects}
 110 are drawn on the canvas in order specified, and may obscure graphics
 111 drawn earlier.  Some @i{graphic options} affect the global appearance
 112 of the scene.
 113
 114 The additional @i{graphic objects} supported by @code{drawdf} include:
 115 @code{solns_at}, @code{points_at}, @code{saddles_at}, @code{soln_at},
 116 @code{point_at}, and @code{saddle_at}.
 117
 118 The additional @i{graphic options} supported by @code{drawdf} include:
 119 @code{field_degree}, @code{soln_arrows}, @code{field_arrows},
 120 @code{field_grid}, @code{field_color}, @code{show_field},
 121 @code{tstep}, @code{nsteps}, @code{duration}, @code{direction},
 122 @code{field_tstep}, @code{field_nsteps}, and @code{field_duration}.
 123
 124 Commonly used @i{graphic objects} inherited from the @code{draw}
 125 package include: @code{explicit}, @code{implicit}, @code{parametric},
 126 @code{polygon}, @code{points}, @code{vector}, @code{label}, and all
 127 others supported by @code{draw2d} and @code{gr2d}.
 128
 129 Commonly used @i{graphic options} inherited from the @code{draw}
 130 package include:@*
 131 @code{points_joined}, @code{color},
 132 @code{point_type}, @code{point_size}, @code{line_width},
 133 @code{line_type}, @code{key}, @code{title}, @code{xlabel},
 134 @code{ylabel}, @code{user_preamble}, @code{terminal},
 135 @code{dimensions}, @code{file_name}, and all
 136 others supported by @code{draw2d} and @code{gr2d}.
 137
 138 See also @mrefcomma{draw2d} @mrefcomma{rk} @mref{desolve} and
 139 @mrefdot{ode2}
 140
 141 Users of wxMaxima or Imaxima may optionally use @code{wxdrawdf}, which
 142 is identical to @code{drawdf} except that the graphics are drawn
 143 within the notebook using @code{wxdraw}.
 144
 145 To make use of this function, write first @code{load("drawdf")}.
 146
 147 Examples:
 148
 149 @example
 150 (%i1) load("drawdf")$
 151 (%i2) drawdf(exp(-x)+y)$        /* default vars: x,y */
 152 (%i3) drawdf(exp(-t)+y, [t,y])$ /* default range: [-10,10] */
 153 (%i4) drawdf([y,-9*sin(x)-y/5], [x,1,5], [y,-2,2])$
 154 @end example
 155
 156 For backward compatibility, @code{drawdf} accepts
 157 most of the parameters supported by plotdf.
 158
 159 @example
 160 (%i5) drawdf(2*cos(t)-1+y, [t,y], [t,-5,10], [y,-4,9],
 161              [trajectory_at,0,0])$
 162 @end example
 163
 164 @code{soln_at} and @code{solns_at} draw solution curves
 165 passing through the specified points, using a slightly
 166 enhanced 4th-order Runge Kutta numerical integrator.
 167
 168 @example
 169 (%i6) drawdf(2*cos(t)-1+y, [t,-5,10], [y,-4,9],
 170              solns_at([0,0.1],[0,-0.1]),
 171              color=blue, soln_at(0,0))$
 172 @end example
 173
 174 @code{field_degree=2} causes the field to be composed of quadratic
 175 splines, based on the first and second derivatives at each grid point.
 176 @code{field_grid=[}@var{COLS},@var{ROWS}@code{]} specifies the number
 177 of columns and rows in the grid.
 178
 179 @example
 180 (%i7) drawdf(2*cos(t)-1+y, [t,-5,10], [y,-4,9],
 181              field_degree=2, field_grid=[20,15],
 182              solns_at([0,0.1],[0,-0.1]),
 183              color=blue, soln_at(0,0))$
 184 @end example
 185
 186 @code{soln_arrows=true} adds arrows to the solution curves, and (by
 187 default) removes them from the direction field.  It also changes the
 188 default colors to emphasize the solution curves.
 189
 190 @example
 191 (%i8) drawdf(2*cos(t)-1+y, [t,-5,10], [y,-4,9],
 192              soln_arrows=true,
 193              solns_at([0,0.1],[0,-0.1],[0,0]))$
 194 @end example
 195
 196 @code{duration=40} specifies the time duration of numerical
 197 integration (default 10).  Integration will also stop automatically if
 198 the solution moves too far away from the plotted region, or if the
 199 derivative becomes complex or infinite.  Here we also specify
 200 @code{field_degree=2} to plot quadratic splines.  The equations below
 201 model a predator-prey system.
 202
 203 @example
 204 (%i9) drawdf([x*(1-x-y), y*(3/4-y-x/2)], [x,0,1.1], [y,0,1],
 205              field_degree=2, duration=40,
 206              soln_arrows=true, point_at(1/2,1/2),
 207              solns_at([0.1,0.2], [0.2,0.1], [1,0.8], [0.8,1],
 208                       [0.1,0.1], [0.6,0.05], [0.05,0.4],
 209                       [1,0.01], [0.01,0.75]))$
 210 @end example
 211
 212 @code{field_degree='solns} causes the field to be composed
 213 of many small solution curves computed by 4th-order
 214 Runge Kutta, with better results in this case.
 215
 216 @example
 217 (%i10) drawdf([x*(1-x-y), y*(3/4-y-x/2)], [x,0,1.1], [y,0,1],
 218               field_degree='solns, duration=40,
 219               soln_arrows=true, point_at(1/2,1/2),
 220               solns_at([0.1,0.2], [0.2,0.1], [1,0.8],
 221                        [0.8,1], [0.1,0.1], [0.6,0.05],
 222                        [0.05,0.4], [1,0.01], [0.01,0.75]))$
 223 @end example
 224
 225 @code{saddles_at} attempts to automatically linearize the equation at
 226 each saddle, and to plot a numerical solution corresponding to each
 227 eigenvector, including the separatrices.  @code{tstep=0.05} specifies
 228 the maximum time step for the numerical integrator (the default is
 229 0.1).  Note that smaller time steps will sometimes be used in order to
 230 keep the x and y steps small.  The equations below model a damped
 231 pendulum.
 232
 233 @example
 234 (%i11) drawdf([y,-9*sin(x)-y/5], tstep=0.05,
 235               soln_arrows=true, point_size=0.5,
 236               points_at([0,0], [2*%pi,0], [-2*%pi,0]),
 237               field_degree='solns,
 238               saddles_at([%pi,0], [-%pi,0]))$
 239 @end example
 240
 241 @code{show_field=false} suppresses the field entirely.
 242
 243 @example
 244 (%i12) drawdf([y,-9*sin(x)-y/5], tstep=0.05,
 245               show_field=false, soln_arrows=true,
 246               point_size=0.5,
 247               points_at([0,0], [2*%pi,0], [-2*%pi,0]),
 248               saddles_at([3*%pi,0], [-3*%pi,0],
 249                          [%pi,0], [-%pi,0]))$
 250 @end example
 251
 252 @code{drawdf} passes all unrecognized parameters to @code{draw2d} or
 253 @code{gr2d}, allowing you to combine the full power of the @code{draw}
 254 package with @code{drawdf}.
 255
 256 @example
 257 (%i13) drawdf(x^2+y^2, [x,-2,2], [y,-2,2], field_color=gray,
 258               key="soln 1", color=black, soln_at(0,0),
 259               key="soln 2", color=red, soln_at(0,1),
 260               key="isocline", color=green, line_width=2,
 261               nticks=100, parametric(cos(t),sin(t),t,0,2*%pi))$
 262 @end example
 263
 264 @code{drawdf} accepts nested lists of graphic options and objects,
 265 allowing convenient use of makelist and other function calls to
 266 generate graphics.
 267
 268 @example
 269 (%i14) colors : ['red,'blue,'purple,'orange,'green]$
 270 (%i15) drawdf([x-x*y/2, (x*y - 3*y)/4],
 271               [x,2.5,3.5], [y,1.5,2.5],
 272               field_color = gray,
 273               makelist([ key   = concat("soln",k),
 274                          color = colors[k],
 275                          soln_at(3, 2 + k/20) ],
 276                        k,1,5))$
 277 @end example
 278
 279 @opencatbox{Categories:}
 280 @category{Package drawdf}
 281 @closecatbox
 282
 283 @end deffn
 284