doc/info/dynamics.texi

   1 @menu
   2 * The dynamics package::
   3 * Graphical analysis of discrete dynamical systems::
   4 * Visualization with VTK::
   5 @end menu
   6
   7 @node The dynamics package, Graphical analysis of discrete dynamical systems, Package dynamics, Package dynamics
   8 @section The dynamics package
   9
  10 Package @code{dynamics} includes functions for 3D visualization,
  11 animations, graphical analysis of differential and difference equations
  12 and numerical solution of differential equations. The functions for
  13 differential equations are described in the section on @mxref{Numerical,
  14 Numerical Methods} and the functions to plot the Mandelbrot and Julia
  15 sets are described in the section on @mrefdot{Plotting}
  16
  17 All the functions in this package will be loaded automatically the first
  18 time they are used.
  19
  20 @opencatbox{Categories:}
  21 @category{Dynamical systems}
  22 @category{Share packages}
  23 @category{Package dynamics}
  24 @closecatbox
  25
  26 @node Graphical analysis of discrete dynamical systems,  Visualization with VTK, The dynamics package, Package dynamics
  27 @section Graphical analysis of discrete dynamical systems
  28
  29 @anchor{chaosgame}
  30 @deffn {Function} chaosgame ([[@var{x1}, @var{y1}]@dots{}[@var{xm}, @var{ym}]], [@var{x0}, @var{y0}], @var{b}, @var{n}, @var{options}, @dots{});
  31
  32 Implements the so-called chaos game: the initial point (@var{x0},
  33 @var{y0}) is plotted and then one of the @var{m} points
  34 [@var{x1}, @var{y1}]@dots{}@var{xm}, @var{ym}]
  35 will be selected at random. The next point plotted will be on the
  36 segment from the previous point plotted to the point chosen randomly, at a
  37 distance from the random point which will be @var{b} times that segment's
  38 length. The procedure is repeated @var{n} times. The options are the
  39 same as for @mrefdot{plot2d}
  40
  41 @strong{Example}. A plot of Sierpinsky's triangle:
  42
  43 @example
  44 (%i1) chaosgame([[0, 0], [1, 0], [0.5, sqrt(3)/2]], [0.1, 0.1], 1/2,
  45                  30000, [style, dots]);
  46 @end example
  47
  48 @ifnotinfo
  49 @figure{dynamics7}
  50 @end ifnotinfo
  51
  52 @opencatbox{Categories:}
  53 @category{Package dynamics}
  54 @category{Plotting}
  55 @closecatbox
  56
  57 @end deffn
  58
  59 @anchor{evolution}
  60 @deffn {Function} evolution (@var{F}, @var{y0}, @var{n},  @dots{}, @var{options}, @dots{});
  61
  62 Draws @var{n+1} points in a two-dimensional graph, where the horizontal
  63 coordinates of the points are the integers 0, 1, 2, ..., @var{n}, and
  64 the vertical coordinates are the corresponding values @var{y(n)} of the
  65 sequence defined by the recurrence relation
  66 @ifnottex
  67 @example
  68         y(n+1) = F(y(n))
  69 @end example
  70 @end ifnottex
  71 @tex
  72 $$y_{n+1} = F(y_n)$$
  73 @end tex
  74
  75 With initial value @var{y(0)} equal to @var{y0}. @var{F} must be an
  76 expression that depends only on one variable (in the example, it
  77 depend on @var{y}, but any other variable can be used),
  78 @var{y0} must be a real number and @var{n} must be a positive integer.
  79  This function accepts the same options as @mrefdot{plot2d}
  80
  81 @strong{Example}.
  82
  83 @example
  84 (%i1) evolution(cos(y), 2, 11);
  85 @end example
  86 @ifnotinfo
  87 @figure{dynamics1}
  88 @end ifnotinfo
  89
  90
  91 @opencatbox{Categories:}
  92 @category{Package dynamics}
  93 @category{Plotting}
  94 @closecatbox
  95
  96 @end deffn
  97
  98 @anchor{evolution2d}
  99 @deffn {Function} evolution2d ([@var{F}, @var{G}], [@var{u}, @var{v}], [@var{u0}, @var{y0}], @var{n}, @var{options}, @dots{});
 100
 101 Shows, in a two-dimensional plot, the first @var{n+1} points in the
 102 sequence of points defined by the two-dimensional discrete dynamical
 103 system with recurrence relations
 104 @ifnottex
 105 @example
 106         u(n+1) = F(u(n), v(n))    v(n+1) = G(u(n), v(n))
 107 @end example
 108 @end ifnottex
 109 @tex
 110 $$\cases{u_{n+1} = F(u_n, v_n) &\cr v_{n+1} = G(u_n, v_n)}$$
 111 @end tex
 112
 113 With initial values @var{u0} and @var{v0}. @var{F} and @var{G} must be
 114 two expressions that depend only on two variables, @var{u} and
 115 @var{v}, which must be named explicitly in a list. The options are the
 116 same as for @mrefdot{plot2d}
 117
 118 @strong{Example}. Evolution of a two-dimensional discrete dynamical system:
 119
 120 @example
 121 (%i1) f: 0.6*x*(1+2*x)+0.8*y*(x-1)-y^2-0.9$
 122 (%i2) g: 0.1*x*(1-6*x+4*y)+0.1*y*(1+9*y)-0.4$
 123 (%i3) evolution2d([f,g], [x,y], [-0.5,0], 50000, [style,dots]);
 124 @end example
 125
 126 @ifnotinfo
 127 @figure{dynamics5}
 128 @end ifnotinfo
 129
 130 And an enlargement of a small region in that fractal:
 131
 132 @example
 133 (%i9) evolution2d([f,g], [x,y], [-0.5,0], 300000, [x,-0.8,-0.6],
 134                   [y,-0.4,-0.2], [style, dots]);
 135 @end example
 136
 137 @ifnotinfo
 138 @figure{dynamics6}
 139 @end ifnotinfo
 140
 141 @opencatbox{Categories:}
 142 @category{Package dynamics}
 143 @category{Plotting}
 144 @closecatbox
 145
 146 @end deffn
 147
 148 @anchor{ifs}
 149 @deffn {Function} ifs ([@var{r1}, @dots{}, @var{rm}], [@var{A1},@dots{}, @var{Am}], [[@var{x1}, @var{y1}], @dots{}, [@var{xm}, @var{ym}]], [@var{x0}, @var{y0}], @var{n}, @var{options}, @dots{});
 150
 151 Implements the Iterated Function System method. This method is similar
 152 to the method described in the function @mrefdot{chaosgame} but instead of
 153 shrinking the segment from the current point to the randomly chosen
 154 point, the 2 components of that segment will be multiplied by the 2 by 2
 155 matrix @var{Ai} that corresponds to the point chosen randomly.
 156
 157 The random choice of one of the @var{m} attractive points can be made
 158 with a non-uniform probability distribution defined by the weights
 159 @var{r1},...,@var{rm}. Those weights are given in cumulative form; for
 160 instance if there are 3 points with probabilities 0.2, 0.5 and 0.3, the
 161 weights @var{r1}, @var{r2} and @var{r3} could be 2, 7 and 10. The
 162 options are the same as for @mrefdot{plot2d}
 163
 164 @strong{Example}. Barnsley's fern, obtained with 4 matrices and 4 points:
 165
 166 @example
 167 (%i1) a1: matrix([0.85,0.04],[-0.04,0.85])$
 168 (%i2) a2: matrix([0.2,-0.26],[0.23,0.22])$
 169 (%i3) a3: matrix([-0.15,0.28],[0.26,0.24])$
 170 (%i4) a4: matrix([0,0],[0,0.16])$
 171 (%i5) p1: [0,1.6]$
 172 (%i6) p2: [0,1.6]$
 173 (%i7) p3: [0,0.44]$
 174 (%i8) p4: [0,0]$
 175 (%i9) w: [85,92,99,100]$
 176 (%i10) ifs(w, [a1,a2,a3,a4], [p1,p2,p3,p4], [5,0], 50000, [style,dots]);
 177 @end example
 178
 179 @ifnotinfo
 180 @figure{dynamics8}
 181 @end ifnotinfo
 182
 183 @opencatbox{Categories:}
 184 @category{Package dynamics}
 185 @category{Plotting}
 186 @closecatbox
 187
 188 @end deffn
 189
 190 @anchor{orbits}
 191 @deffn {Function} orbits (@var{F}, @var{y0}, @var{n1}, @var{n2}, [@var{x}, @var{x0}, @var{xf}, @var{xstep}], @var{options}, @dots{});
 192
 193 Draws the orbits diagram for a family of one-dimensional
 194 discrete dynamical systems, with one parameter @var{x}; that kind of
 195 diagram is used to study the bifurcations of an one-dimensional discrete
 196 system.
 197
 198 The function @var{F(y)} defines a sequence with a starting value of
 199 @var{y0}, as in the case of the function @code{evolution}, but in this
 200 case that function will also depend on a parameter @var{x} that will
 201 take values in the interval from @var{x0} to @var{xf} with increments of
 202 @var{xstep}. Each value used for the parameter @var{x} is shown on the
 203 horizontal axis. The vertical axis will show the @var{n2} values
 204 of the sequence @var{y(n1+1)},..., @var{y(n1+n2+1)} obtained after letting
 205 the sequence evolve @var{n1} iterations.  In addition to the options
 206 accepted by @mrefcomma{plot2d} it accepts an option @var{pixels} that
 207 sets up the maximum number of different points that will be represented
 208 in the vertical direction.
 209
 210 @strong{Example}. Orbits diagram of the quadratic map, with a parameter
 211 @var{a}:
 212
 213 @example
 214 (%i1) orbits(x^2+a, 0, 50, 200, [a, -2, 0.25], [style, dots]);
 215 @end example
 216
 217 @ifnotinfo
 218 @figure{dynamics3}
 219 @end ifnotinfo
 220
 221 To enlarge the region around the lower bifurcation near x @code{=} -1.25 use:
 222 @example
 223 (%i2) orbits(x^2+a, 0, 100, 400, [a,-1,-1.53], [x,-1.6,-0.8],
 224              [nticks, 400], [style,dots]);
 225 @end example
 226
 227 @ifnotinfo
 228 @figure{dynamics4}
 229 @end ifnotinfo
 230
 231 @opencatbox{Categories:}
 232 @category{Package dynamics}
 233 @category{Plotting}
 234 @closecatbox
 235
 236 @end deffn
 237
 238 @anchor{staircase}
 239 @deffn {Function} staircase (@var{F}, @var{y0}, @var{n},@var{options},@dots{});
 240
 241 Draws a staircase diagram for the sequence defined by the recurrence
 242 relation
 243 @ifnottex
 244 @example
 245         y(n+1) = F(y(n))
 246 @end example
 247 @end ifnottex
 248 @tex
 249 $$y_{n+1} = F(y_n)$$
 250 @end tex
 251
 252 The interpretation and allowed values of the input parameters is the
 253 same as for the function @mrefdot{evolution} A staircase diagram consists
 254 of a plot of the function @var{F(y)}, together with the line @var{G(y)}
 255 @code{=} @var{y}. A vertical segment is drawn from the point (@var{y0},
 256 @var{y0}) on that line until the point where it intersects the function
 257 @var{F}. From that point a horizontal segment is drawn until it reaches
 258 the point (@var{y1}, @var{y1}) on the line, and the procedure is
 259 repeated @var{n} times until the point (@var{yn}, @var{yn}) is
 260 reached. The options are the same as for @mrefdot{plot2d}
 261
 262 @strong{Example}.
 263
 264 @example
 265 (%i1) staircase(cos(y), 1, 11, [y, 0, 1.2]);
 266 @end example
 267 @ifnotinfo
 268 @figure{dynamics2}
 269 @end ifnotinfo
 270
 271 @opencatbox{Categories:}
 272 @category{Package dynamics}
 273 @category{Plotting}
 274 @closecatbox
 275
 276 @end deffn
 277
 278 @node Visualization with VTK, , Graphical analysis of discrete dynamical systems, Package dynamics
 279 @section Visualization with VTK
 280
 281 Function scene creates 3D images and animations using the @emph{Visualization
 282 ToolKit} (VTK) software. In order to use that function, Xmaxima and VTK should be
 283 installed in your system (including the TCL bindings of VTK, which in
 284 some system might come in a separate package).
 285
 286 @anchor{scene}
 287 @deffn {Function} scene (@var{objects}, @dots{}, @var{options}, @dots{});
 288
 289 Accepts an empty list or a list of several @mxref{scene_objects,objects}
 290 and @mxrefdot{scene_options,options} The program launches Xmaxima, which
 291 opens an external window representing the given objects in a
 292 3-dimensional space and applying the options given. Each object must
 293 belong to one of the following 4 classes: sphere, cube, cylinder or cone
 294 (see @mxref{scene_objects,Scene objects}). Objects are identified by
 295 giving their name or by a list in which the first element is the class
 296 name and the following elements are options for that object.
 297
 298 @strong{Example}. A hexagonal pyramid with a blue background:
 299 @c ===beg===
 300 @c scene(cone, [background,"#9980e5"])$
 301 @c ===end===
 302 @example
 303 (%i1) scene(cone, [background,"#9980e5"])$
 304 @end example
 305 @ifnotinfo
 306 @figure{scene1}
 307 @end ifnotinfo
 308
 309 By holding down the left button of the mouse while it is moved on the
 310 graphics window, the camera can be rotated showing different views of
 311 the pyramid. The two plot options @mxref{scene_elevation,elevation} and
 312 @mxref{scene_azimuth,azimuth} can also be used to change the initial
 313 orientation of the viewing camera. The camera can be moved by holding
 314 the middle mouse button while moving it and holding the right-side mouse
 315 button while moving it up or down will zoom in or out.
 316
 317 Each object option should be a list starting with the option name,
 318 followed by its value. The list of allowed options can be found in the
 319 @mxref{object_options,Scene object's options} section.
 320
 321 @strong{Example}. This will show a sphere falling to the ground and
 322 bouncing off without losing any energy. To start or pause the
 323 animation, press the play/pause button.
 324 @c ===beg===
 325 @c p: makelist ([0,0,2.1- 9.8*t^2/2], t, 0, 0.64, 0.01)$
 326 @c p: append (p, reverse(p))$
 327 @c ball: [sphere, [radius,0.1], [thetaresolution,20],
 328 @c   [phiresolution,20],[position,0,0,2.1], [color,red],
 329 @c   [animate,position,p]]$
 330 @c ground: [cube, [xlength,2], [ylength,2], [zlength,0.2],
 331 @c   [position,0,0,-0.1],[color,violet]]$
 332 @c scene (ball, ground, restart);
 333 @c ===end===
 334
 335 @example
 336 (%i1) p: makelist ([0,0,2.1- 9.8*t^2/2], t, 0, 0.64, 0.01)$
 337
 338 (%i2) p: append (p, reverse(p))$
 339
 340 (%i3) ball: [sphere, [radius,0.1], [thetaresolution,20],
 341   [phiresolution,20], [position,0,0,2.1], [color,red],
 342   [animate,position,p]]$
 343
 344 (%i4) ground: [cube, [xlength,2], [ylength,2], [zlength,0.2],
 345   [position,0,0,-0.1],[color,violet]]$
 346
 347 (%i5) scene (ball, ground, restart)$
 348 @end example
 349 @ifnotinfo
 350 @figure{scene2}
 351 @end ifnotinfo
 352
 353 The @var{restart} option was used to make the animation restart
 354 automatically every time the last point in the position list is reached.
 355 The accepted values for the colors are the same as for the @mref{color}
 356 option of plot2d.
 357
 358 @opencatbox{Categories:}
 359 @category{Package dynamics}
 360 @category{Plotting}
 361 @closecatbox
 362
 363 @end deffn
 364
 365 @anchor{scene_options}
 366 @subsection Scene options
 367
 368 @anchor{scene_azimuth}
 369 @defvr {Scene option} azimuth [azimuth, @var{angle}]
 370 Default value: @code{135}
 371
 372 The rotation of the camera on the horizontal (x, y) plane. @var{angle}
 373 must be a real number; an angle of 0 means that the camera points in the
 374 direction of the y axis and the x axis will appear on the right.
 375
 376 @opencatbox{Categories:}
 377 @category{Package dynamics}
 378 @category{Plotting}
 379 @closecatbox
 380 @end defvr
 381
 382 @anchor{scene_background}
 383 @defvr {Scene option} background [background, @var{color}]
 384 Default value: @code{black}
 385
 386 The color of the graphics window's background. It accepts color names or
 387 hexadecimal red-green-blue strings (see the @mref{color} option of plot2d).
 388
 389 @opencatbox{Categories:}
 390 @category{Package dynamics}
 391 @category{Plotting}
 392 @closecatbox
 393 @end defvr
 394
 395 @anchor{scene_elevation}
 396 @defvr {Scene option} elevation [elevation, @var{angle}]
 397 Default value: @code{30}
 398
 399 The vertical rotation of the camera. The @var{angle} must be a real
 400 number; an angle of 0 means that the camera points on the horizontal,
 401 and the default angle of 30 means that the camera is pointing 30 degrees
 402 down from the horizontal.
 403
 404 @opencatbox{Categories:}
 405 @category{Package dynamics}
 406 @category{Plotting}
 407 @closecatbox
 408 @end defvr
 409
 410 @anchor{scene_height}
 411 @defvr {Scene option} height [height, @var{pixels}]
 412 Default value: @code{500}
 413
 414 The height, in pixels, of the graphics window. @var{pixels} must be a
 415 positive integer number.
 416
 417 @opencatbox{Categories:}
 418 @category{Package dynamics}
 419 @category{Plotting}
 420 @closecatbox
 421 @end defvr
 422
 423 @anchor{scene_restart}
 424 @defvr {Scene option} restart [restart, @var{value}]
 425 Default value: @code{false}
 426
 427 A true value means that animations will restart automatically when the
 428 end of the list is reached. Writing just ``restart'' is equivalent to
 429 [restart, @var{true}].
 430
 431 @opencatbox{Categories:}
 432 @category{Package dynamics}
 433 @category{Plotting}
 434 @closecatbox
 435 @end defvr
 436
 437 @anchor{scene_tstep}
 438 @defvr {Scene option} tstep [tstep, @var{time}]
 439 Default value: @code{10}
 440
 441 The amount of time, in mili-seconds, between iterations among
 442 consecutive animation frames. @var{time} must be a real number.
 443
 444 @opencatbox{Categories:}
 445 @category{Package dynamics}
 446 @category{Plotting}
 447 @closecatbox
 448 @end defvr
 449
 450 @anchor{scene_width}
 451 @defvr {Scene option} width [width, @var{pixels}]
 452 Default value: @code{500}
 453
 454 The width, in pixels, of the graphics window. @var{pixels} must be a
 455 positive integer number.
 456
 457 @opencatbox{Categories:}
 458 @category{Package dynamics}
 459 @category{Plotting}
 460 @closecatbox
 461 @end defvr
 462
 463 @anchor{scene_windowname}
 464 @defvr {Scene option} windowname [windowtitle, @var{name}]
 465 Default value: @code{.scene}
 466
 467 @var{name} must be a string that can be used as the name of the Tk
 468 window created by Xmaxima for the @code{scene} graphics. The default
 469 value @code{.scene} implies that a new top level window will be created.
 470
 471 @opencatbox{Categories:}
 472 @category{Package dynamics}
 473 @category{Plotting}
 474 @closecatbox
 475 @end defvr
 476
 477 @anchor{scene_windowtitle}
 478 @defvr {Scene option} windowtitle [windowtitle, @var{name}]
 479 Default value: @code{Xmaxima: scene}
 480
 481 @var{name} must be a string that will be written in the title of the
 482 window created by @code{scene}.
 483
 484 @opencatbox{Categories:}
 485 @category{Package dynamics}
 486 @category{Plotting}
 487 @closecatbox
 488 @end defvr
 489
 490 @anchor{scene_objects}
 491 @subsection Scene objects
 492
 493 @anchor{cone}
 494 @defvr {Scene object} cone [cone, @var{options}]
 495
 496 Creates a regular pyramid with height equal to 1 and a hexagonal base
 497 with vertices 0.5 units away from the axis. Options
 498 @mxref{object_height,height} and @mxref{object_radius,radius} can be used
 499 to change those defaults and option @mxref{object_resolution, resolution}
 500 can be used to change the number of edges of the base; higher values
 501 will make it look like a cone. By default, the axis will be along the x
 502 axis, the middle point of the axis will be at the origin and the vertex
 503 on the positive side of the x axis; use options
 504 @mxref{object_orientation,orientation} and @mxref{object_center,center} to
 505 change those defaults.
 506
 507 @strong{Example}. This shows a pyramid that starts rotating around the z
 508 axis when the play button is pressed.
 509
 510 @example
 511 (%i1) scene([cone, [orientation,0,30,0], [tstep,100],
 512    [animate,orientation,makelist([0,30,i],i,5,360,5)]], restart)$
 513 @end example
 514
 515 @opencatbox{Categories:}
 516 @category{Package dynamics}
 517 @category{Plotting}
 518 @closecatbox
 519 @end defvr
 520
 521 @anchor{cube}
 522 @defvr {Scene object} cube [cube, @var{options}]
 523
 524 A cube with edges of 1 unit and faces parallel to the xy, xz and yz
 525 planes. The lengths of the three edges can be changed with options
 526 @mxref{object_xlength,xlength}, @mxref{object_ylength,ylength} and
 527 @mxref{object_zlength,zlength}, turning it into a rectangular box and
 528 the faces can be rotated with option @mxrefdot{object_orientation,orientation}
 529
 530 @opencatbox{Categories:}
 531 @category{Package dynamics}
 532 @category{Plotting}
 533 @closecatbox
 534 @end defvr
 535
 536 @anchor{cylinder}
 537 @defvr {Scene object} cylinder [cylinder, @var{options}]
 538
 539 Creates a regular prism with height equal to 1 and a hexagonal base with
 540 vertices 0.5 units away from the axis. Options
 541 @mxref{object_height,height} and @mxref{object_radius,radius} can be
 542 used to change those defaults and option @mxref{object_resolution,
 543 resolution} can be used to change the number of edges of the base;
 544 higher values will make it look like a cylinder. The default height can
 545 be changed with the option @mxrefdot{object_height,height} By default,
 546 the axis will be along the x axis and the middle point of the axis will
 547 be at the origin; use options @mxref{object_orientation,orientation} and
 548 @mxref{object_center,center} to change those defaults.
 549
 550 @opencatbox{Categories:}
 551 @category{Package dynamics}
 552 @category{Plotting}
 553 @closecatbox
 554 @end defvr
 555
 556 @anchor{sphere}
 557 @defvr {Scene object} sphere [sphere, @var{options}]
 558
 559 A sphere with default radius of 0.5 units and center at the origin.
 560
 561 @opencatbox{Categories:}
 562 @category{Package dynamics}
 563 @category{Plotting}
 564 @closecatbox
 565 @end defvr
 566
 567 @anchor{object_options}
 568 @subsection Scene object's options
 569
 570 @anchor{object_animation}
 571 @defvr {Object option} animation [animation, @var{property}, @var{positions}]
 572
 573 @var{property} should be one of the following 4 object's properties:
 574 @mxrefcomma{object_origin,origin} @mxrefcomma{object_scale,scale}
 575 @mxref{object_position,position} or
 576 @mxref{object_orientation,orientation} and @var{positions} should be a
 577 list of points. When the play button is pressed, the object property
 578 will be changed sequentially through all the values in the list, at
 579 intervals of time given by the option @mxrefdot{scene_tstep,tstep} The
 580 rewind button can be used to point at the start of the sequence making
 581 the animation restart after the play button is pressed again.
 582
 583 See also @mxrefdot{object_track,track}
 584
 585 @opencatbox{Categories:}
 586 @category{Package dynamics}
 587 @category{Plotting}
 588 @closecatbox
 589 @end defvr
 590
 591 @anchor{object_capping}
 592 @defvr {Object option} capping [capping, @var{number}]
 593 Default value: @code{1}
 594
 595 In a cone or a cylinder, it defines whether the base (or bases) will be
 596 shown. A value of 1 for @var{number} makes the base visible and a value
 597 of 0 makes it invisible.
 598
 599 @opencatbox{Categories:}
 600 @category{Package dynamics}
 601 @category{Plotting}
 602 @closecatbox
 603 @end defvr
 604
 605 @anchor{object_center}
 606 @defvr {Object option} center [center, @var{point}]
 607 Default value: @code{[0, 0, 0]}
 608
 609 The coordinates of the object's geometric center, with respect to its
 610 @mxrefdot{object_position, position} @var{point} can be a list with 3
 611 real numbers, or 3 real numbers separated by commas. In a cylinder, cone
 612 or cube it will be at half its height and in a sphere at its center.
 613
 614 @opencatbox{Categories:}
 615 @category{Package dynamics}
 616 @category{Plotting}
 617 @closecatbox
 618 @end defvr
 619
 620 @anchor{object_color}
 621 @defvr {Object option} color [color, @var{colorname}]
 622 Default value: @code{white}
 623
 624 The color of the object. It accepts color names or hexadecimal
 625 red-green-blue strings (see the @mref{color} option of plot2d).
 626
 627 @opencatbox{Categories:}
 628 @category{Package dynamics}
 629 @category{Plotting}
 630 @closecatbox
 631 @end defvr
 632
 633 @anchor{object_endphi}
 634 @defvr {Object option} endphi [endphi, @var{angle}]
 635 Default value: @code{180}
 636
 637 In a sphere phi is the angle on the vertical plane that passes through
 638 the z axis, measured from the positive part of the z axis. @var{angle}
 639 must be a number between 0 and 180 that sets the final value of phi at
 640 which the surface will end. A value smaller than 180 will eliminate a
 641 part of the sphere's surface.
 642
 643 See also @mxref{object_startphi,startphi} and
 644 @mxrefdot{object_phiresolution,phiresolution}
 645
 646 @opencatbox{Categories:}
 647 @category{Package dynamics}
 648 @category{Plotting}
 649 @closecatbox
 650 @end defvr
 651
 652 @anchor{object_endtheta}
 653 @defvr {Object option} endtheta [endtheta, @var{angle}]
 654 Default value: @code{360}
 655
 656 In a sphere theta is the angle on the horizontal plane (longitude),
 657 measured from the positive part of the x axis. @var{angle} must be a
 658 number between 0 and 360 that sets the final value of theta at which the
 659 surface will end. A value smaller than 360 will eliminate a part of
 660 the sphere's surface.
 661
 662 See also @mxref{object_starttheta,starttheta} and
 663 @mxrefdot{object_thetaresolution,thetaresolution}
 664
 665 @opencatbox{Categories:}
 666 @category{Package dynamics}
 667 @category{Plotting}
 668 @closecatbox
 669 @end defvr
 670
 671 @anchor{object_height}
 672 @defvr {Object option} height [height, @var{value}]
 673 Default value: @code{1}
 674
 675 @var{value} must be a positive number which sets the height of a cone
 676 or a cylinder.
 677
 678 @opencatbox{Categories:}
 679 @category{Package dynamics}
 680 @category{Plotting}
 681 @closecatbox
 682 @end defvr
 683
 684 @anchor{object_linewidth}
 685 @defvr {Object option} linewidth [linewidth, @var{value}]
 686 Default value: @code{1}
 687
 688 The width of the lines, when option @mxref{object_wireframe,wireframe} is
 689 used. @var{value} must be a positive number.
 690
 691 @opencatbox{Categories:}
 692 @category{Package dynamics}
 693 @category{Plotting}
 694 @closecatbox
 695 @end defvr
 696
 697 @anchor{object_opacity}
 698 @defvr {Object option} opacity [opacity, @var{value}]
 699 Default value: @code{1}
 700
 701 @var{value} must be a number between 0 and 1. The lower the number, the
 702 more transparent the object will become. The default value of 1 means a
 703 completely opaque object.
 704
 705 @opencatbox{Categories:}
 706 @category{Package dynamics}
 707 @category{Plotting}
 708 @closecatbox
 709 @end defvr
 710
 711 @anchor{object_orientation}
 712 @defvr {Object option} orientation [orientation, @var{angles}]
 713 Default value: @code{[0, 0, 0]}
 714
 715 Three angles by which the object will be rotated with respect to the
 716 three axis. @var{angles} can be a list with 3 real numbers, or 3 real
 717 numbers separated by commas. @strong{Example}: @code{[0, 0, 90]} rotates
 718 the x axis of the object to the y axis of the reference frame.
 719
 720 @opencatbox{Categories:}
 721 @category{Package dynamics}
 722 @category{Plotting}
 723 @closecatbox
 724 @end defvr
 725
 726 @anchor{object_origin}
 727 @defvr {Object option} origin [origin, @var{point}]
 728 Default value: @code{[0, 0, 0]}
 729
 730 The coordinates of the object's origin, with respect to which its
 731 other dimensions are defined. @var{point} can be a list with 3
 732 real numbers, or 3 real numbers separated by commas.
 733
 734 @opencatbox{Categories:}
 735 @category{Package dynamics}
 736 @category{Plotting}
 737 @closecatbox
 738 @end defvr
 739
 740 @anchor{object_phiresolution}
 741 @defvr {Object option} phiresolution [phiresolution, @var{num}]
 742 Default value: @code{}
 743
 744 The number of sub-intervals into which the phi angle interval from
 745 @mxref{object_startphi,startphi} to @mxref{object_endphi,endphi}
 746 will be divided. @var{num} must be a positive integer.
 747
 748 See also @mxref{object_startphi,startphi} and
 749 @mxrefdot{object_endphi,endphi}
 750
 751 @opencatbox{Categories:}
 752 @category{Package dynamics}
 753 @category{Plotting}
 754 @closecatbox
 755 @end defvr
 756
 757 @anchor{object_points}
 758 @defvr {Object option} points  [points]
 759
 760 Only the vertices of the triangulation used to render the surface will
 761 be shown. @strong{Example}: @code{[sphere, [points]]}
 762
 763 See also @mxref{object_surface,surface} and
 764 @mxrefdot{object_wireframe,wireframe}
 765
 766 @opencatbox{Categories:}
 767 @category{Package dynamics}
 768 @category{Plotting}
 769 @closecatbox
 770 @end defvr
 771
 772 @anchor{object_pointsize}
 773 @defvr {Object option} pointsize [pointsize, @var{value}]
 774 Default value: @code{1}
 775
 776 The size of the points, when option @mxref{object_points,points} is
 777 used. @var{value} must be a positive number.
 778
 779 @opencatbox{Categories:}
 780 @category{Package dynamics}
 781 @category{Plotting}
 782 @closecatbox
 783 @end defvr
 784
 785 @anchor{object_position}
 786 @defvr {Object option} position [position, @var{point}]
 787 Default value: @code{[0, 0, 0]}
 788
 789 The coordinates of the object's position. @var{point} can be a list with 3
 790 real numbers, or 3 real numbers separated by commas.
 791
 792 @opencatbox{Categories:}
 793 @category{Package dynamics}
 794 @category{Plotting}
 795 @closecatbox
 796 @end defvr
 797
 798 @anchor{object_radius}
 799 @defvr {Object option} radius [radius, @var{value}]
 800 Default value: @code{0.5}
 801
 802 The radius or a sphere or the distance from the axis to the base's
 803 vertices in a cylinder or a cone. @var{value} must be a positive number.
 804
 805 @opencatbox{Categories:}
 806 @category{Package dynamics}
 807 @category{Plotting}
 808 @closecatbox
 809 @end defvr
 810
 811 @anchor{object_resolution}
 812 @defvr {Object option} resolution [resolution, @var{number}]
 813 Default value: @code{6}
 814
 815 @var{number} must be an integer greater than 2 that sets the number of
 816 edges in the base of a cone or a cylinder.
 817
 818 @opencatbox{Categories:}
 819 @category{Package dynamics}
 820 @category{Plotting}
 821 @closecatbox
 822 @end defvr
 823
 824 @anchor{object_scale}
 825 @defvr {Object option} scale [scale, @var{factors}]
 826 Default value: @code{[1, 1, 1]}
 827
 828 Three numbers by which the object will be scaled with respect to the
 829 three axis. @var{factors} can be a list with 3 real numbers, or 3 real
 830 numbers separated by commas. @strong{Example}: @code{[2, 0.5, 1]}
 831 enlarges the object to twice its size in the x direction, reduces the
 832 dimensions in the y direction to half and leaves the z dimensions
 833 unchanged.
 834
 835 @opencatbox{Categories:}
 836 @category{Package dynamics}
 837 @category{Plotting}
 838 @closecatbox
 839 @end defvr
 840
 841 @anchor{object_startphi}
 842 @defvr {Object option} startphi [startphi, @var{angle}]
 843 Default value: @code{0}
 844
 845 In a sphere phi is the angle on the vertical plane that passes through
 846 the z axis, measured from the positive part of the z axis. @var{angle}
 847 must be a number between 0 and 180 that sets the initial value of phi at
 848 which the surface will start. A value bigger than 0 will eliminate a
 849 part of the sphere's surface.
 850
 851 See also @mxref{object_endphi,endphi} and
 852 @mxrefdot{object_phiresolution,phiresolution}
 853
 854 @opencatbox{Categories:}
 855 @category{Package dynamics}
 856 @category{Plotting}
 857 @closecatbox
 858 @end defvr
 859
 860 @anchor{object_starttheta}
 861 @defvr {Object option} starttheta [starttheta, @var{angle}]
 862 Default value: @code{0}
 863
 864 In a sphere theta is the angle on the horizontal plane (longitude),
 865 measured from the positive part of the x axis. @var{angle} must be a
 866 number between 0 and 360 that sets the initial value of theta at which
 867 the surface will start. A value bigger than 0 will eliminate a part of
 868 the sphere's surface.
 869
 870 See also @mxref{object_endtheta,endtheta} and
 871 @mxrefdot{object_thetaresolution,thetaresolution}
 872
 873 @opencatbox{Categories:}
 874 @category{Package dynamics}
 875 @category{Plotting}
 876 @closecatbox
 877 @end defvr
 878
 879 @anchor{object_surface}
 880 @defvr {Object option} surface [surface]
 881
 882 The surfaces of the object will be rendered and the lines and points of
 883 the triangulation used to build the surface will not be shown. This is
 884 the default behavior, which can be changed using either the option
 885 @mxref{object_points,points} or @mxrefdot{object_wireframe,wireframe}
 886
 887 @opencatbox{Categories:}
 888 @category{Package dynamics}
 889 @category{Plotting}
 890 @closecatbox
 891 @end defvr
 892
 893 @anchor{object_thetaresolution}
 894 @defvr {Object option} thetaresolution [thetaresolution, @var{num}]
 895 Default value: @code{}
 896
 897 The number of sub-intervals into which the theta angle interval from
 898 @mxref{object_starttheta,starttheta} to @mxref{object_endtheta,endtheta}
 899 will be divided. @var{num} must be a positive integer.
 900
 901 See also @mxref{object_starttheta,starttheta} and
 902 @mxrefdot{object_endtheta,endtheta}
 903
 904 @opencatbox{Categories:}
 905 @category{Package dynamics}
 906 @category{Plotting}
 907 @closecatbox
 908 @end defvr
 909
 910 @anchor{object_track}
 911 @defvr {Object option} track [track, @var{positions}]
 912
 913 @var{positions} should be a list of points. When the play button is
 914 pressed, the object position will be changed sequentially through all
 915 the points in the list, at intervals of time given by the option
 916 @mxrefcomma{scene_tstep,tstep} leaving behind a track of the object's
 917 trajectory. The rewind button can be used to point at the start of the
 918 sequence making the animation restart after the play button is pressed
 919 again.
 920
 921 @strong{Example}. This will show the trajectory of a ball thrown with
 922 speed of 5 m/s, at an angle of 45 degrees, when the air resistance can
 923 be neglected:
 924
 925 @example
 926 (%i1) p: makelist ([0,4*t,4*t- 9.8*t^2/2], t, 0, 0.82, 0.01)$
 927
 928 (%i2) ball: [sphere, [radius,0.1], [color,red], [track,p]]$
 929
 930 (%i3) ground: [cube, [xlength,2], [ylength,4], [zlength,0.2],
 931       [position,0,1.5,-0.2],[color,green]]$
 932
 933 (%i4) scene (ball, ground)$
 934 @end example
 935
 936 See also @mxrefdot{object_animation,animation}
 937
 938
 939 @opencatbox{Categories:}
 940 @category{Package dynamics}
 941 @category{Plotting}
 942 @closecatbox
 943 @end defvr
 944
 945 @anchor{object_xlength}
 946 @defvr {Object option} xlength [xlength, @var{length}]
 947 Default value: @code{1}
 948
 949 The height of a cube in the x direction. @var{length} must be a positive
 950 number. See also @mxref{object_ylength,ylength} and
 951 @mxrefdot{object_zlength,zlength}
 952
 953 @opencatbox{Categories:}
 954 @category{Package dynamics}
 955 @category{Plotting}
 956 @closecatbox
 957 @end defvr
 958
 959 @anchor{object_ylength}
 960 @defvr {Object option} ylength [ylength, @var{length}]
 961 Default value: @code{1}
 962
 963 The height of a cube in the y direction. @var{length} must be a positive
 964 number. See also @mxref{object_xlength,xlength} and
 965 @mxrefdot{object_zlength,zlength}
 966
 967 @opencatbox{Categories:}
 968 @category{Package dynamics}
 969 @category{Plotting}
 970 @closecatbox
 971 @end defvr
 972
 973 @anchor{object_zlength}
 974 @defvr {Object option} zlength [zlength, @var{length}]
 975 Default value: @code{1}
 976
 977 The height of a cube in z the direction. @var{length} must be a positive
 978  number.  See also @mxref{object_xlength,xlength} and
 979  @mxrefdot{object_ylength,ylength}
 980
 981 @opencatbox{Categories:}
 982 @category{Package dynamics}
 983 @category{Plotting}
 984 @closecatbox
 985 @end defvr
 986
 987 @anchor{object_wireframe}
 988 @defvr {Object option} wireframe  [wireframe]
 989
 990 Only the edges of the triangulation used to render the surface will be
 991 shown. @strong{Example}: @code{[cube, [wireframe]]}
 992
 993 See also @mxref{object_surface,surface} and
 994 @mxrefdot{object_points,points}
 995
 996 @opencatbox{Categories:}
 997 @category{Package dynamics}
 998 @category{Plotting}
 999 @closecatbox
1000 @end defvr