This is maxima.info, produced by makeinfo version 4.7 from maxima.texi.

   This is a Texinfo Maxima Manual

   Copyright 1994,2001 William F. Schelter

START-INFO-DIR-ENTRY
* Maxima: (maxima).     A computer algebra system.
END-INFO-DIR-ENTRY


File: maxima.info,  Node: Functions and Variables for draw,  Next: Functions and Variables for pictures,  Prev: Introduction to draw,  Up: draw

48.2 Functions and Variables for draw
=====================================

 -- Graphic option: xrange
     Default value: `auto'

     If `xrange' is `auto', the range for the <x> coordinate is
     computed automatically.

     If the user wants a specific interval for <x>, it must be given as
     a Maxima list, as in `xrange=[-2, 3]'.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange = [-3,5],
                       explicit(x^2,x,-1,1))$

     See also `yrange' and `zrange'.


 -- Graphic option: yrange
     Default value: `auto'

     If `yrange' is `auto', the range for the <y> coordinate is
     computed automatically.

     If the user wants a specific interval for <y>, it must be given as
     a Maxima list, as in `yrange=[-2, 3]'.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(yrange = [-2,3],
                       explicit(x^2,x,-1,1),
                       xrange = [-3,3])$

     See also `xrange' and `zrange'.


 -- Graphic option: zrange
     Default value: `auto'

     If `zrange' is `auto', the range for the <z> coordinate is
     computed automatically.

     If the user wants a specific interval for <z>, it must be given as
     a Maxima list, as in `zrange=[-2, 3]'.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(yrange = [-3,3],
                       zrange = [-2,5],
                       explicit(x^2+y^2,x,-1,1,y,-1,1),
                       xrange = [-3,3])$

     See also `xrange' and `yrange'.


 -- Graphic option: logx
     Default value: `false'

     If `logx' is `true', the <x> axis will be drawn in the logarithmic
     scale.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(log(x),x,0.01,5),
                       logx = true)$

     See also `logy' and `logz'.


 -- Graphic option: logy
     Default value: `false'

     If `logy' is `true', the <y> axis will be drawn in the logarithmic
     scale.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(logy = true,
                       explicit(exp(x),x,0,5))$

     See also `logx' and `logz'.


 -- Graphic option: logz
     Default value: `false'

     If `logz' is `true', the <z> axis will be drawn in the logarithmic
     scale.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(logz = true,
                       explicit(exp(u^2+v^2),u,-2,2,v,-2,2))$

     See also `logx' and `logy'.


 -- Graphic option: terminal
     Default value: `screen'

     Selects the terminal to be used by Gnuplot; possible values are:
     `screen' (default), `png', `jpg', `eps', `eps_color', `gif',
     `animated_gif', `wxt' and `aquaterm'.

     Since this is a global graphics option, its position in the scene
     description does not matter. It can be also used as an argument of
     function `draw'.

     Examples:

          (%i1) load(draw)$
          (%i2) /* screen terminal (default) */
                draw2d(explicit(x^2,x,-1,1))$
          (%i3) /* png file */
                draw2d(terminal  = 'png,
                       pic_width = 300,
                       explicit(x^2,x,-1,1))$
          (%i4) /* jpg file */
                draw2d(terminal   = 'jpg,
                       pic_width  = 300,
                       pic_height = 300,
                       explicit(x^2,x,-1,1))$
          (%i5) /* eps file */
                draw2d(file_name = "myfile",
                       explicit(x^2,x,-1,1),
                       terminal  = 'eps)$
          (%i6) /* wxwidgets window */
                draw2d(explicit(x^2,x,-1,1),
                       terminal  = 'wxt)$

     An animated gif file,
          (%i1) load(draw)$
          (%i2) draw(
                  delay     = 100,
                  file_name = "zzz",
                  terminal  = 'animated_gif,
                  gr2d(explicit(x^2,x,-1,1)),
                  gr2d(explicit(x^3,x,-1,1)),
                  gr2d(explicit(x^4,x,-1,1)));
          End of animation sequence
          (%o2)          [gr2d(explicit), gr2d(explicit), gr2d(explicit)]

     Option `delay' is only active in animated gif's; it is ignored in
     any other case.

     See also `file_name', `pic_width', `pic_height' and `delay'.


 -- Graphic option: font
     Default value: `""' (empty string)

     This option can be used to set the font face to be used by the
     terminal.  Only one font face and size can be used throughout the
     plot.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     See also `font_size'.

     Gnuplot doesn't handle fonts by itself, it leaves this task to the
     support libraries of the different terminals, each one with its own
     philosophy about it. A brief summary follows:

        * x11: Uses the normal x11 font server mechanism.

          Example:
               (%i1) load(draw)$
               (%i2) draw2d(font      = "Arial",
                            font_size = 20,
                            label(["Arial font, size 20",1,1]))$

        * windows: The windows terminal doesn't support changing of
          fonts from inside the plot.  Once the plot has been
          generated, the font can be changed right-clicking on the menu
          of the graph window.

        * png, jpeg, gif: The libgd library uses the font path stored
          in the environment variable `GDFONTPATH'; in this case, it is
          only necessary to set option `font' to the font's name. It is
          also possible to give the complete path to the font file.

          Examples:

          Option `font' can be given the complete path to the font file:
               (%i1) load(draw)$
               (%i2) path: "/usr/share/fonts/truetype/freefont/" $
               (%i3) file: "FreeSerifBoldItalic.ttf" $
               (%i4) draw2d(
                       font      = concat(path, file),
                       font_size = 20,
                       color     = red,
                       label(["FreeSerifBoldItalic font, size 20",1,1]),
                       terminal  = png)$

          If environment variable `GDFONTPATH' is set to the path where
          font files are allocated, it is possible to set graphic
          option `font' to the name of the font.
               (%i1) load(draw)$
               (%i2) draw2d(
                       font      = "FreeSerifBoldItalic",
                       font_size = 20,
                       color     = red,
                       label(["FreeSerifBoldItalic font, size 20",1,1]),
                       terminal  = png)$

        * Postscript: Standard Postscript fonts are: `"Times-Roman"',
          `"Times-Italic"', `"Times-Bold"', `"Times-BoldItalic"',
          `"Helvetica"', `"Helvetica-Oblique"', `"Helvetica-Bold"',
          `"Helvetic-BoldOblique"', `"Courier"', `"Courier-Oblique"',
          `"Courier-Bold"', and `"Courier-BoldOblique"'.

          Example:
               (%i1) load(draw)$
               (%i2) draw2d(
                       font      = "Courier-Oblique",
                       font_size = 15,
                       label(["Courier-Oblique font, size 15",1,1]),
                       terminal = eps)$

        * wxt: The pango library finds fonts via the `fontconfig'
          utility.

        * aqua: Default is `"Times-Roman"'.

     The gnuplot documentation is an important source of information
     about terminals and fonts.


 -- Graphic option: font_size
     Default value: 12

     This option can be used to set the font size to be used by the
     terminal.  Only one font face and size can be used throughout the
     plot. `font_size' is active only when option `font' is not equal
     to the empty string.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     See also `font'.


 -- Graphic option: grid
     Default value: `false'

     If `grid' is `true', a grid will be drawn on the <xy> plane.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(grid = true,
                       explicit(exp(u),u,-2,2))$


 -- Graphic option: title
     Default value: `""' (empty string)

     Option `title', a string, is the main title for the scene.  By
     default, no title is written.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(exp(u),u,-2,2),
                       title = "Exponential function")$


 -- Graphic option: xlabel
     Default value: `""' (empty string)

     Option `xlabel', a string, is the label for the <x> axis.  By
     default, no label is written.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xlabel = "Time",
                       explicit(exp(u),u,-2,2),
                       ylabel = "Population")$

     See also `ylabel', and `zlabel'.


 -- Graphic option: ylabel
     Default value: `""' (empty string)

     Option `ylabel', a string, is the label for the <y> axis.  By
     default, no label is written.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xlabel = "Time",
                       ylabel = "Population",
                       explicit(exp(u),u,-2,2) )$

     See also `xlabel', and `zlabel'.


 -- Graphic option: zlabel
     Default value: `""' (empty string)

     Option `zlabel', a string, is the label for the <z> axis.  By
     default, no label is written.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(zlabel = "Z variable",
                       ylabel = "Y variable",
                       explicit(sin(x^2+y^2),x,-2,2,y,-2,2),
                       xlabel = "X variable" )$

     See also `xlabel', and `ylabel'.


 -- Graphic option: xtics
     Default value: `auto'

     This graphic option controls the way tic marks are drawn on the
     <x> axis.

        * When option `xtics' is bounded to symbol <auto>, tic marks are
          drawn automatically.

        * When option `xtics' is bounded to symbol <none>, tic marks are
          not drawn.

        * When option `xtics' is bounded to a positive number, this is
          the distance between two consecutive tic marks.

        * When option `xtics' is bounded to a list of length three of
          the form `[start,incr,end]', tic marks are plotted from
          `start' to `end' at intervals of length `incr'.

        * When option `xtics' is bounded to a set of numbers of the
          form `{n1, n2, ...}', tic marks are plotted at values `n1',
          `n2', ...

        * When option `xtics' is bounded to a set of pairs of the form
          `{["label1", n1], ["label2", n2], ...}', tic marks
          corresponding to values `n1', `n2', ... are labeled with
          `"label1"', `"label2"', ..., respectively.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Examples:

     Disable tics.
          (%i1) load(draw)$
          (%i2) draw2d(xtics = 'none,
                       explicit(x^3,x,-1,1)  )$

     Tics every 1/4 units.
          (%i1) load(draw)$
          (%i2) draw2d(xtics = 1/4,
                       explicit(x^3,x,-1,1)  )$

     Tics from -3/4 to 3/4 in steps of 1/8.
          (%i1) load(draw)$
          (%i2) draw2d(xtics = [-3/4,1/8,3/4],
                       explicit(x^3,x,-1,1)  )$

     Tics at points -1/2, -1/4 and 3/4.
          (%i1) load(draw)$
          (%i2) draw2d(xtics = {-1/2,-1/4,3/4},
                       explicit(x^3,x,-1,1)  )$

     Labeled tics.
          (%i1) load(draw)$
          (%i2) draw2d(xtics = {["High",0.75],["Medium",0],["Low",-0.75]},
                       explicit(x^3,x,-1,1)  )$

     See also `ytics', and `ztics'.


 -- Graphic option: ytics
     Default value: `auto'

     This graphic option controls the way tic marks are drawn on the
     <y> axis.

     See `xtics' for a complete description.


 -- Graphic option: ztics
     Default value: `auto'

     This graphic option controls the way tic marks are drawn on the
     <z> axis.

     See `xtics' for a complete description.


 -- Graphic option: xtics_rotate
     Default value: `false'

     If `xtics_rotate' is `true', tic marks on the <x> axis are rotated
     90 degrees.

     Since this is a global graphics option, its position in the scene
     description does not matter.


 -- Graphic option: ytics_rotate
     Default value: `false'

     If `ytics_rotate' is `true', tic marks on the <y> axis are rotated
     90 degrees.

     Since this is a global graphics option, its position in the scene
     description does not matter.


 -- Graphic option: ztics_rotate
     Default value: `false'

     If `ztics_rotate' is `true', tic marks on the <z> axis are rotated
     90 degrees.

     Since this is a global graphics option, its position in the scene
     description does not matter.


 -- Graphic option: xtics_axis
     Default value: `false'

     If `xtics_axis' is `true', tic marks and their labels are plotted
     just along the <x> axis, if it is `false' tics are plotted on the
     border.

     Since this is a global graphics option, its position in the scene
     description does not matter.


 -- Graphic option: ytics_axis
     Default value: `false'

     If `ytics_axis' is `true', tic marks and their labels are plotted
     just along the <y> axis, if it is `false' tics are plotted on the
     border.

     Since this is a global graphics option, its position in the scene
     description does not matter.


 -- Graphic option: ztics_axis
     Default value: `false'

     If `ztics_axis' is `true', tic marks and their labels are plotted
     just along the <z> axis, if it is `false' tics are plotted on the
     border.

     Since this is a global graphics option, its position in the scene
     description does not matter.


 -- Graphic option: xaxis
     Default value: `false'

     If `xaxis' is `true', the <x> axis is drawn.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^3,x,-1,1),
                       xaxis       = true,
                       xaxis_color = blue)$

     See also `xaxis_width', `xaxis_type' and `xaxis_color'.


 -- Graphic option: xaxis_width
     Default value: 1

     `xaxis_width' is the width of the <x> axis.  Its value must be a
     positive number.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^3,x,-1,1),
                       xaxis       = true,
                       xaxis_width = 3)$

     See also `xaxis', `xaxis_type' and `xaxis_color'.


 -- Graphic option: xaxis_type
     Default value: `dots'

     `xaxis_type' indicates how the <x> axis is displayed; possible
     values are `solid' and `dots'.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^3,x,-1,1),
                       xaxis       = true,
                       xaxis_type  = solid)$

     See also `xaxis', `xaxis_width' and `xaxis_color'.


 -- Graphic option: xaxis_color
     Default value: `"black"'

     `xaxis_color' specifies the color for the <x> axis. See `color' to
     know how colors are defined.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^3,x,-1,1),
                       xaxis       = true,
                       xaxis_color = red)$

     See also `xaxis', `xaxis_width' and `xaxis_type'.


 -- Graphic option: yaxis
     Default value: `false'

     If `yaxis' is `true', the <y> axis is drawn.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^3,x,-1,1),
                       yaxis       = true,
                       yaxis_color = blue)$

     See also `yaxis_width', `yaxis_type' and `yaxis_color'.


 -- Graphic option: yaxis_width
     Default value: 1

     `yaxis_width' is the width of the <y> axis.  Its value must be a
     positive number.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^3,x,-1,1),
                       yaxis       = true,
                       yaxis_width = 3)$

     See also `yaxis', `yaxis_type' and `yaxis_color'.


 -- Graphic option: yaxis_type
     Default value: `dots'

     `yaxis_type' indicates how the <y> axis is displayed; possible
     values are `solid' and `dots'.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^3,x,-1,1),
                       yaxis       = true,
                       yaxis_type  = solid)$

     See also `yaxis', `yaxis_width' and `yaxis_color'.


 -- Graphic option: yaxis_color
     Default value: `"black"'

     `yaxis_color' specifies the color for the <y> axis. See `color' to
     know how colors are defined.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^3,x,-1,1),
                       yaxis       = true,
                       yaxis_color = red)$

     See also `yaxis', `yaxis_width' and `yaxis_type'.


 -- Graphic option: zaxis
     Default value: `false'

     If `zaxis' is `true', the <z> axis is drawn in 3D plots.  This
     option has no effect in 2D scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(explicit(x^2+y^2,x,-1,1,y,-1,1),
                       zaxis       = true,
                       zaxis_type  = solid,
                       zaxis_color = blue)$

     See also `zaxis_width', `zaxis_type' and `zaxis_color'.


 -- Graphic option: zaxis_width
     Default value: 1

     `zaxis_width' is the width of the <z> axis.  Its value must be a
     positive number. This option has no effect in 2D scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(explicit(x^2+y^2,x,-1,1,y,-1,1),
                       zaxis       = true,
                       zaxis_type  = solid,
                       zaxis_width = 3)$

     See also `zaxis', `zaxis_type' and `zaxis_color'.


 -- Graphic option: zaxis_type
     Default value: `dots'

     `zaxis_type' indicates how the <z> axis is displayed; possible
     values are `solid' and `dots'.  This option has no effect in 2D
     scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(explicit(x^2+y^2,x,-1,1,y,-1,1),
                       zaxis       = true,
                       zaxis_type  = solid)$

     See also `zaxis', `zaxis_width' and `zaxis_color'.


 -- Graphic option: zaxis_color
     Default value: `"black"'

     `zaxis_color' specifies the color for the <z> axis. See `color' to
     know how colors are defined.  This option has no effect in 2D
     scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(explicit(x^2+y^2,x,-1,1,y,-1,1),
                       zaxis       = true,
                       zaxis_type  = solid,
                       zaxis_color = red)$

     See also `zaxis', `zaxis_width' and `zaxis_type'.


 -- Graphic option: xyplane
     Default value: `false'

     Allocates the xy-plane in 3D scenes. When `xyplane' is `false',
     the xy-plane is placed automatically; when it is a real number,
     the xy-plane intersects the z-axis at this level.  This option has
     no effect in 2D scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(xyplane = %e-2,
                       explicit(x^2+y^2,x,-1,1,y,-1,1))$


 -- Graphic option: rot_vertical
     Default value: 60

     `rot_vertical' is the angle (in degrees) of vertical rotation
     (around the <x> axis) to set the view point in 3d scenes.

     The angle is bounded to the [0, 180] interval.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(rot_vertical = 170,
                       explicit(sin(x^2+y^2),x,-2,2,y,-2,2) )$

     See also `rot_horizontal'.


 -- Graphic option: rot_horizontal
     Default value: 30

     `rot_horizontal' is the angle (in degrees) of horizontal rotation
     (around the <z> axis) to set the view point in 3d scenes.

     The angle is bounded to the [0, 360] interval.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(rot_vertical = 170,
                       rot_horizontal = 360,
                       explicit(sin(x^2+y^2),x,-2,2,y,-2,2) )$

     See also `rot_vertical'.


 -- Graphic option: xy_file
     Default value: `""' (empty string)

     `xy_file' is the name of the file where the coordinates will be
     saved after clicking with the mouse button and hitting the 'x'
     key. By default, no coordinates are saved.

     Since this is a global graphics option, its position in the scene
     description does not matter.


 -- Graphic option: user_preamble
     Default value: `""' (empty string)

     Expert Gnuplot users can make use of this option to fine tune
     Gnuplot's behaviour by writing settings to be sent before the
     `plot' or `splot' command.

     The value of this option must be a string or a list of strings
     (one per line).

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

     The dumb terminal is not supported by package `draw', but it is
     possible to set it by making use of option `user_preamble',
          (%i1) load(draw)$
          (%i2) draw2d(explicit(exp(x)-1,x,-1,1),
                       parametric(cos(u),sin(u),u,0,2*%pi),
                       user_preamble="set terminal dumb")$


 -- Graphic option: file_name
     Default value: `"maxima_out"'

     This is the name of the file where terminals `png', `jpg', `eps'
     and `eps_color' will save the graphic.

     Since this is a global graphics option, its position in the scene
     description does not matter. It can be also used as an argument of
     function `draw'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(file_name = "myfile",
                       explicit(x^2,x,-1,1),
                       terminal  = 'png)$

     See also `terminal', `pic_width', and `pic_height'.


 -- Graphic option: delay
     Default value: 5

     This is the delay in 1/100 seconds of frames in animated gif files.

     Since this is a global graphics option, its position in the scene
     description does not matter. It can be also used as an argument of
     function `draw'.

     Example:

          (%i1) load(draw)$
          (%i2) draw(
                  delay     = 100,
                  file_name = "zzz",
                  terminal  = 'animated_gif,
                  gr2d(explicit(x^2,x,-1,1)),
                  gr2d(explicit(x^3,x,-1,1)),
                  gr2d(explicit(x^4,x,-1,1)));
          End of animation sequence
          (%o2)          [gr2d(explicit), gr2d(explicit), gr2d(explicit)]

     Option `delay' is only active in animated gif's; it is ignored in
     any other case.

     See also `terminal', `pic_width', and `pic_height'.


 -- Graphic option: pic_width
     Default value: 640

     This is the width of the bitmap file generated by terminals `png'
     and `jpg'.

     Since this is a global graphics option, its position in the scene
     description does not matter. It can be also used as an argument of
     function `draw'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(terminal   = 'png,
                       pic_width  = 300,
                       pic_height = 300,
                       explicit(x^2,x,-1,1))$

     See also `terminal', `file_name', and `pic_height'.


 -- Graphic option: pic_height
     Default value: 640

     This is the height of the bitmap file generated by terminals `png'
     and `jpg'.

     Since this is a global graphics option, its position in the scene
     description does not matter. It can be also used as an argument of
     function `draw'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(terminal   = 'png,
                       pic_width  = 300,
                       pic_height = 300,
                       explicit(x^2,x,-1,1))$

     See also `terminal', `file_name', and `pic_width'.


 -- Graphic option: eps_width
     Default value: 12

     This is the width (measured in cm) of the Postscipt file generated
     by terminals `eps' and `eps_color'.

     Since this is a global graphics option, its position in the scene
     description does not matter. It can be also used as an argument of
     function `draw'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(terminal   = 'eps,
                       eps_width  = 3,
                       eps_height = 3,
                       explicit(x^2,x,-1,1))$

     See also `terminal', `file_name', and `eps_height'.


 -- Graphic option: eps_height
     Default value: 8

     This is the height (measured in cm) of the Postscipt file
     generated by terminals `eps' and `eps_color'.

     Since this is a global graphics option, its position in the scene
     description does not matter. It can be also used as an argument of
     function `draw'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(terminal   = 'eps,
                       eps_width  = 3,
                       eps_height = 3,
                       explicit(x^2,x,-1,1))$

     See also `terminal', `file_name', and `eps_width'.


 -- Graphic option: axis_bottom
     Default value: `true'

     If `axis_bottom' is `true', the bottom axis is shown in 2d scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(axis_bottom = false,
                       explicit(x^3,x,-1,1))$

     See also `axis_left',  `axis_top', `axis_right', and `axis_3d'.


 -- Graphic option: axis_left
     Default value: `true'

     If `axis_left' is `true', the left axis is shown in 2d scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(axis_left = false,
                       explicit(x^3,x,-1,1))$

     See also `axis_bottom',  `axis_top', `axis_right', and `axis_3d'.


 -- Graphic option: axis_top
     Default value: `true'

     If `axis_top' is `true', the top axis is shown in 2d scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(axis_top = false,
                       explicit(x^3,x,-1,1))$

     See also `axis_bottom',  `axis_left', `axis_right', and `axis_3d'.


 -- Graphic option: axis_right
     Default value: `true'

     If `axis_right' is `true', the right axis is shown in 2d scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(axis_right = false,
                       explicit(x^3,x,-1,1))$

     See also `axis_bottom',  `axis_left', `axis_top', and `axis_3d'.


 -- Graphic option: axis_3d
     Default value: `true'

     If `axis_3d' is `true', the <x>, <y> and <z> axis are shown in 3d
     scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(axis_3d = false,
                       explicit(sin(x^2+y^2),x,-2,2,y,-2,2) )$

     See also `axis_bottom',  `axis_left', `axis_top', and `axis_right'
     for axis in 2d.


 -- Graphic option: palette
     Default value: `color'

     `palette' indicates how to map the real values of a matrix passed
     to object `image' onto color components.

     `palette' is a vector of length three with components ranging from
     -36 to +36; each value is an index for a formula mapping the levels
     onto red, green and blue colors, respectively:
           0: 0               1: 0.5           2: 1
           3: x               4: x^2           5: x^3
           6: x^4             7: sqrt(x)       8: sqrt(sqrt(x))
           9: sin(90x)       10: cos(90x)     11: |x-0.5|
          12: (2x-1)^2       13: sin(180x)    14: |cos(180x)|
          15: sin(360x)      16: cos(360x)    17: |sin(360x)|
          18: |cos(360x)|    19: |sin(720x)|  20: |cos(720x)|
          21: 3x             22: 3x-1         23: 3x-2
          24: |3x-1|         25: |3x-2|       26: (3x-1)/2
          27: (3x-2)/2       28: |(3x-1)/2|   29: |(3x-2)/2|
          30: x/0.32-0.78125 31: 2*x-0.84     32: 4x;1;-2x+1.84;x/0.08-11.5
          33: |2*x - 0.5|    34: 2*x          35: 2*x - 0.5
          36: 2*x - 1
     negative numbers mean negative colour component.

     `palette = gray' and `palette = color' are short cuts for `palette
     = [3,3,3]' and `palette = [7,5,15]', respectively.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Examples:

          (%i1) load(draw)$
          (%i2) im: apply(
                     'matrix,
                      makelist(makelist(random(200),i,1,30),i,1,30))$
          (%i3) /* palette = color, default */
                draw2d(image(im,0,0,30,30))$
          (%i4) draw2d(palette = gray, image(im,0,0,30,30))$
          (%i5) draw2d(palette = [15,20,-4],
                       colorbox=false,
                       image(im,0,0,30,30))$

     See also `colorbox'.


 -- Graphic option: colorbox
     Default value: `true'

     If `colorbox' is `true', a color scale is drawn together with
     `image' objects.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) im: apply('matrix,
                           makelist(makelist(random(200),i,1,30),i,1,30))$
          (%i3) draw2d(image(im,0,0,30,30))$
          (%i4) draw2d(colorbox=false, image(im,0,0,30,30))$

     See also `palette'.


 -- Graphic option: enhanced3d
     Default value: `false'

     If `enhanced3d' is `false', surfaces are not colored in 3d plots.
     If `enhanced3d' is `true', surfaces are colored setting Gnuplot's
     pm3d mode. If an expression is given to `enhanced3d', it will be
     used to assign colors according to the `palette'; variables in
     this expression must be the same used in the surface description.

     See option `palette' to learn how palettes are specified.

     Examples:

          (%i1) load(draw)$
          (%i2) draw3d(
                   surface_hide = true,
                   enhanced3d   = true,
                   palette      = gray,
                   explicit(20*exp(-x^2-y^2)-10,x,-3,3,y,-3,3))$
          (%i3) draw3d(
                   surface_hide = true,
                   /* same variables x and y as */
                   /* in explicit below:        */
                   enhanced3d   = sin(x*y),
                   explicit(20*exp(-x^2-y^2)-10,x,-3,3,y,-3,3))$


 -- Graphic option: point_size
     Default value: 1

     `point_size' sets the size for plotted points. It must be a non
     negative number.

     This option has no effect when graphic option `point_type' is set
     to `dot'.

     This option affects the following graphic objects:
        * `gr2d': `points'.

        * `gr3d': `points'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(points(makelist([random(20),random(50)],k,1,10)),
                  point_size = 5,
                  points(makelist(k,k,1,20),makelist(random(30),k,1,20)))$


 -- Graphic option: point_type
     Default value: 1

     `point_type' indicates how isolated points are displayed; the
     value of this option can be any integer index greater or equal
     than -1, or the name of a point style: `$none' (-1), `dot' (0),
     `plus' (1), `multiply' (2), `asterisk' (3), `square' (4),
     `filled_square' (5), `circle' (6), `filled_circle' (7),
     `up_triangle' (8), `filled_up_triangle' (9), `down_triangle' (10),
     `filled_down_triangle' (11), `diamant' (12) and `filled_diamant'
     (13).

     This option affects the following graphic objects:
        * `gr2d': `points'.

        * `gr3d': `points'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange = [0,10],
                       yrange = [0,10],
                       point_size = 3,
                       point_type = diamant,
                       points([[1,1],[5,1],[9,1]]),
                       point_type = filled_down_triangle,
                       points([[1,2],[5,2],[9,2]]),
                       point_type = asterisk,
                       points([[1,3],[5,3],[9,3]]),
                       point_type = filled_diamant,
                       points([[1,4],[5,4],[9,4]]),
                       point_type = 5,
                       points([[1,5],[5,5],[9,5]]),
                       point_type = 6,
                       points([[1,6],[5,6],[9,6]]),
                       point_type = filled_circle,
                       points([[1,7],[5,7],[9,7]]),
                       point_type = 8,
                       points([[1,8],[5,8],[9,8]]),
                       point_type = filled_diamant,
                       points([[1,9],[5,9],[9,9]]) )$


 -- Graphic option: points_joined
     Default value: `false'

     When `points_joined' is `true', points are joined by lines; when
     `false', isolated points are drawn. A third possible value for
     this graphic option is `impulses'; in such case, vertical segments
     are drawn from points to the x-axis (2D) or to the xy-plane (3D).

     This option affects the following graphic objects:
        * `gr2d': `points'.

        * `gr3d': `points'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange        = [0,10],
                       yrange        = [0,4],
                       point_size    = 3,
                       point_type    = up_triangle,
                       color         = blue,
                       points([[1,1],[5,1],[9,1]]),
                       points_joined = true,
                       point_type    = square,
                       line_type     = dots,
                       points([[1,2],[5,2],[9,2]]),
                       point_type    = circle,
                       color         = red,
                       line_width    = 7,
                       points([[1,3],[5,3],[9,3]]) )$


 -- Graphic option: filled_func
     Default value: `false'

     Option `filled_func' controls how regions limited by functions
     should be filled. When `filled_func' is `true', the region bounded
     by the function defined with object `explicit' and the bottom of
     the graphic window is filled with `fill_color'. When `filled_func'
     contains a function expression, then the region bounded by this
     function and the function defined with object `explicit' will be
     filled. By default, explicit functions are not filled.

     This option affects only the 2d graphic object `explicit'.

     Example:

     Region bounded by an `explicit' object and the bottom of the
     graphic window.
          (%i1) load(draw)$
          (%i2) draw2d(fill_color  = red,
                       filled_func = true,
                       explicit(sin(x),x,0,10) )$

     Region bounded by an `explicit' object and the function defined by
     option `filled_func'. Note that the variable in `filled_func' must
     be the same as that used in `explicit'.
          (%i1) load(draw)$
          (%i2) draw2d(fill_color  = grey,
                       filled_func = sin(x),
                       explicit(-sin(x),x,0,%pi));

     See also `fill_color' and `explicit'.


 -- Graphic option: transparent
     Default value: `false'

     If `transparent' is `true', interior regions of polygons are
     filled according to `fill_color'.

     This option affects the following graphic objects:
        * `gr2d': `polygon', `rectangle', and `ellipse'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(polygon([[3,2],[7,2],[5,5]]),
                       transparent = true,
                       color       = blue,
                       polygon([[5,2],[9,2],[7,5]]) )$


 -- Graphic option: border
     Default value: `true'

     If `border' is `true', borders of polygons are painted according
     to `line_type' and `line_width'.

     This option affects the following graphic objects:
        * `gr2d': `polygon', `rectangle', and `ellipse'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(color       = brown,
                       line_width  = 8,
                       polygon([[3,2],[7,2],[5,5]]),
                       border      = false,
                       fill_color  = blue,
                       polygon([[5,2],[9,2],[7,5]]) )$


 -- Graphic option: head_both
     Default value: `false'

     If `head_both' is `true', vectors are plotted with two arrow heads.
     If `false', only one arrow is plotted.

     This option is relevant only for `vector' objects.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange      = [0,8],
                       yrange      = [0,8],
                       head_length = 0.7,
                       vector([1,1],[6,0]),
                       head_both   = true,
                       vector([1,7],[6,0]) )$

     See also `head_length', `head_angle', and `head_type'.


 -- Graphic option: head_length
     Default value: 2

     `head_length' indicates, in <x>-axis units, the length of arrow
     heads.

     This option is relevant only for `vector' objects.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange      = [0,12],
                       yrange      = [0,8],
                       vector([0,1],[5,5]),
                       head_length = 1,
                       vector([2,1],[5,5]),
                       head_length = 0.5,
                       vector([4,1],[5,5]),
                       head_length = 0.25,
                       vector([6,1],[5,5]))$

     See also `head_both', `head_angle', and `head_type'.


 -- Graphic option: head_angle
     Default value: 45

     `head_angle' indicates the angle, in degrees, between the arrow
     heads and the segment.

     This option is relevant only for `vector' objects.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange      = [0,10],
                       yrange      = [0,9],
                       head_length = 0.7,
                       head_angle  = 10,
                       vector([1,1],[0,6]),
                       head_angle  = 20,
                       vector([2,1],[0,6]),
                       head_angle  = 30,
                       vector([3,1],[0,6]),
                       head_angle  = 40,
                       vector([4,1],[0,6]),
                       head_angle  = 60,
                       vector([5,1],[0,6]),
                       head_angle  = 90,
                       vector([6,1],[0,6]),
                       head_angle  = 120,
                       vector([7,1],[0,6]),
                       head_angle  = 160,
                       vector([8,1],[0,6]),
                       head_angle  = 180,
                       vector([9,1],[0,6]) )$

     See also `head_both', `head_length', and `head_type'.


 -- Graphic option: head_type
     Default value: `filled'

     `head_type' is used to specify how arrow heads are plotted.
     Possible values are: `filled' (closed and filled arrow heads),
     `empty' (closed but not filled arrow heads), and `nofilled' (open
     arrow heads).

     This option is relevant only for `vector' objects.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange      = [0,12],
                       yrange      = [0,10],
                       head_length = 1,
                       vector([0,1],[5,5]), /* default type */
                       head_type = 'empty,
                       vector([3,1],[5,5]),
                       head_type = 'nofilled,
                       vector([6,1],[5,5]))$

     See also `head_both', `head_angle', and `head_length'.


 -- Graphic option: unit_vectors
     Default value: `false'

     If `unit_vectors' is `true', vectors are plotted with module 1.
     This is useful for plotting vector fields. If `unit_vectors' is
     `false', vectors are plotted with its original length.

     This option is relevant only for `vector' objects.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange      = [-1,6],
                       yrange      = [-1,6],
                       head_length = 0.1,
                       vector([0,0],[5,2]),
                       unit_vectors = true,
                       color        = red,
                       vector([0,3],[5,2]))$


 -- Graphic option: label_alignment
     Default value: `center'

     `label_alignment' is used to specify where to write labels with
     respect to the given coordinates. Possible values are: `center',
     `left', and `right'.

     This option is relevant only for `label' objects.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange          = [0,10],
                       yrange          = [0,10],
                       points_joined   = true,
                       points([[5,0],[5,10]]),
                       color           = blue,
                       label(["Centered alignment (default)",5,2]),
                       label_alignment = 'left,
                       label(["Left alignment",5,5]),
                       label_alignment = 'right,
                       label(["Right alignment",5,8]))$

     See also `label_orientation', and `color'.


 -- Graphic option: label_orientation
     Default value: `horizontal'

     `label_orientation' is used to specify orientation of labels.
     Possible values are: `horizontal', and `vertical'.

     This option is relevant only for `label' objects.

     Example:

     In this example, a dummy point is added to get an image.  Package
     `draw' needs always data to draw an scene.
          (%i1) load(draw)$
          (%i2) draw2d(xrange     = [0,10],
                       yrange     = [0,10],
                       point_size = 0,
                       points([[5,5]]),
                       color      = navy,
                       label(["Horizontal orientation (default)",5,2]),
                       label_orientation = 'vertical,
                       color             = "#654321",
                       label(["Vertical orientation",1,5]))$

     See also `label_alignment' and `color'.


 -- Graphic option: color
     Default value: `"black"'

     `color' specifies the color for plotting lines, points, borders of
     polygons and labels.

     Colors can be given as names or in hexadecimal rgb code.

     Available color names are: `"white"', `"black"', `"gray0"',
     `"grey0"', `"gray10"', `"grey10"', `"gray20"', `"grey20"',
     `"gray30"', `"grey30"', `"gray40"', `"grey40"', `"gray50"',
     `"grey50"', `"gray60"', `"grey60"', `"gray70"', `"grey70"',
     `"gray80"', `"grey80"', `"gray90"', `"grey90"', `"gray100"',
     `"grey100"', `"gray"', `"grey"', `"light-gray"', `"light-grey"',
     `"dark-gray"', `"dark-grey"', `"red"', `"light-red"',
     `"dark-red"', `"yellow"', `"light-yellow"', `"dark-yellow"',
     `"green"', `"light-green"', `"dark-green"', `"spring-green"',
     `"forest-green"', `"sea-green"', `"blue"', `"light-blue"',
     `"dark-blue"', `"midnight-blue"', `"navy"', `"medium-blue"',
     `"royalblue"', `"skyblue"', `"cyan"', `"light-cyan"',
     `"dark-cyan"', `"magenta"', `"light-magenta"', `"dark-magenta"',
     `"turquoise"', `"light-turquoise"', `"dark-turquoise"', `"pink"',
     `"light-pink"', `"dark-pink"', `"coral"', `"light-coral"',
     `"orange-red"', `"salmon"', `"light-salmon"', `"dark-salmon"',
     `"aquamarine"', `"khaki"', `"dark-khaki"', `"goldenrod"',
     `"light-goldenrod"', `"dark-goldenrod"', `"gold"', `"beige"',
     `"brown"', `"orange"', `"dark-orange"', `"violet"',
     `"dark-violet"', `"plum"' and `"purple"'.

     Cromatic componentes in hexadecimal code are introduced in the
     form `"#rrggbb"'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^2,x,-1,1), /* default is black */
                       color = "red",
                       explicit(0.5 + x^2,x,-1,1),
                       color = blue,
                       explicit(1 + x^2,x,-1,1),
                       color = "light-blue", /* double quotes if - is used */
                       explicit(1.5 + x^2,x,-1,1),
                       color = "#23ab0f",
                       label(["This is a label",0,1.2])  )$

     See also `fill_color'.


 -- Graphic option: fill_color
     Default value: `"red"'

     `fill_color' specifies the color for filling polygons and 2d
     `explicit' functions.

     See `color' to learn how colors are specified.


 -- Graphic option: fill_density
     Default value: 0

     `fill_density' is a number between 0 and 1 that specifies the
     intensity of the `fill_color' in `bars' objects.

     See `bars' for examples.

 -- Graphic option: line_width
     Default value: 1

     `line_width' is the width of plotted lines.  Its value must be a
     positive number.

     This option affects the following graphic objects:
        * `gr2d': `points', `polygon', `rectangle', `ellipse',
          `vector', `explicit', `implicit', `parametric' and `polar'.

        * `gr3d': `points' and `parametric'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^2,x,-1,1), /* default width */
                       line_width = 5.5,
                       explicit(1 + x^2,x,-1,1),
                       line_width = 10,
                       explicit(2 + x^2,x,-1,1))$

     See also `line_type'.


 -- Graphic option: line_type
     Default value: `solid'

     `line_type' indicates how lines are displayed; possible values are
     `solid' and `dots'.

     This option affects the following graphic objects:
        * `gr2d': `points', `polygon', `rectangle', `ellipse',
          `vector', `explicit', `implicit', `parametric' and `polar'.

        * `gr3d': `points', `explicit', `parametric' and
          `parametric_surface'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(line_type = dots,
                       explicit(1 + x^2,x,-1,1),
                       line_type = solid, /* default */
                       explicit(2 + x^2,x,-1,1))$

     See also `line_width'.


 -- Graphic option: nticks
     Default value: 30

     In 2d, `nticks' gives the initial number of points used by the
     adaptive plotting routine for explicit objects. It is also the
     number of points that will be shown in parametric and polar curves.

     This option affects the following graphic objects:
        * `gr2d': `ellipse', `explicit', `parametric' and `polar'.

        * `gr3d': `parametric'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(transparent = true,
                       ellipse(0,0,4,2,0,180),
                       nticks = 5,
                       ellipse(0,0,4,2,180,180) )$


 -- Graphic option: adapt_depth
     Default value: 10

     `adapt_depth' is the maximum number of splittings used by the
     adaptive plotting routine.

     This option is relevant only for 2d `explicit' functions.


 -- Graphic option: key
     Default value: `""' (empty string)

     `key' is the name of a function in the legend. If `key' is an
     empty string, no key is assigned to the function.

     This option affects the following graphic objects:
        * `gr2d': `points', `polygon', `rectangle', `ellipse',
          `vector', `explicit', `implicit', `parametric', and `polar'.

        * `gr3d': `points', `explicit', `parametric', and
          `parametric_surface'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(key   = "Sinus",
                       explicit(sin(x),x,0,10),
                       key   = "Cosinus",
                       color = red,
                       explicit(cos(x),x,0,10) )$


 -- Graphic option: xu_grid
     Default value: 30

     `xu_grid' is the number of coordinates of the first variable (`x'
     in explicit and `u' in parametric 3d surfaces) to build the grid
     of sample points.

     This option affects the following graphic objects:
        * `gr3d': `explicit' and `parametric_surface'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(xu_grid = 10,
                       yv_grid = 50,
                       explicit(x^2+y^2,x,-3,3,y,-3,3) )$

     See also `yv_grid'.


 -- Graphic option: yv_grid
     Default value: 30

     `yv_grid' is the number of coordinates of the second variable (`y'
     in explicit and `v' in parametric 3d surfaces) to build the grid
     of sample points.

     This option affects the following graphic objects:
        * `gr3d': `explicit' and `parametric_surface'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(xu_grid = 10,
                       yv_grid = 50,
                       explicit(x^2+y^2,x,-3,3,y,-3,3) )$

     See also `xu_grid'.


 -- Graphic option: surface_hide
     Default value: `false'

     If `surface_hide' is `true', hidden parts are not plotted in 3d
     surfaces.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw(columns=2,
                     gr3d(explicit(exp(sin(x)+cos(x^2)),x,-3,3,y,-3,3)),
                     gr3d(surface_hide = true,
                          explicit(exp(sin(x)+cos(x^2)),x,-3,3,y,-3,3)) )$


 -- Graphic option: contour
     Default value: `none'

     Option `contour' enables the user to select where to plot contour
     lines.  Possible values are:

        * `none': no contour lines are plotted.

        * `base': contour lines are projected on the xy plane.

        * `surface': contour lines are plotted on the surface.

        * `both': two contour lines are plotted: on the xy plane and on
          the surface.

        * `map': contour lines are projected on the xy plane, and the
          view point is set just in the vertical.


     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(explicit(20*exp(-x^2-y^2)-10,x,0,2,y,-3,3),
                       contour_levels = 15,
                       contour        = both,
                       surface_hide   = true) $


 -- Graphic option: contour_levels
     Default value: 5

     This graphic option controls the way contours are drawn.
     `contour_levels' can be set to a positive integer number, a list
     of three numbers or an arbitrary set of numbers:

        * When option `contour_levels' is bounded to positive integer
          <n>, <n> contour lines will be drawn at equal intervals. By
          default, five equally spaced contours are plotted.

        * When option `contour_levels' is bounded to a list of length
          three of the form `[lowest,s,highest]', contour lines are
          plotted from `lowest' to `highest' in steps of `s'.

        * When option `contour_levels' is bounded to a set of numbers
          of the form `{n1, n2, ...}', contour lines are plotted at
          values `n1', `n2', ...

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Examples:

     Ten equally spaced contour lines. The actual number of levels can
     be adjusted to give simple labels.
          (%i1) load(draw)$
          (%i2) draw3d(color = green,
                       explicit(20*exp(-x^2-y^2)-10,x,0,2,y,-3,3),
                       contour_levels = 10,
                       contour        = both,
                       surface_hide   = true) $

     From -8 to 8 in steps of 4.
          (%i1) load(draw)$
          (%i2) draw3d(color = green,
                       explicit(20*exp(-x^2-y^2)-10,x,0,2,y,-3,3),
                       contour_levels = [-8,4,8],
                       contour        = both,
                       surface_hide   = true) $

     Isolines at levels -7, -6, 0.8 and 5.
          (%i1) load(draw)$
          (%i2) draw3d(color = green,
                       explicit(20*exp(-x^2-y^2)-10,x,0,2,y,-3,3),
                       contour_levels = {-7, -6, 0.8, 5},
                       contour        = both,
                       surface_hide   = true) $

     See also `contour'.


 -- Graphic option: columns
     Default value: 1

     `columns' is the number of columns in multiple plots.

     Since this is a global graphics option, its position in the scene
     description does not matter. It can be also used as an argument of
     function `draw'.

     Example:

          (%i1) load(draw)$
          (%i2) scene1: gr2d(title="Ellipse",
                             nticks=30,
                             parametric(2*cos(t),5*sin(t),t,0,2*%pi))$
          (%i3) scene2: gr2d(title="Triangle",
                             polygon([4,5,7],[6,4,2]))$
          (%i4) draw(scene1, scene2, columns = 2)$


 -- Graphic option: ip_grid
     Default value: `[50, 50]'

     `ip_grid' sets the grid for the first sampling in implicit plots.

     This option is relevant only for `implicit' objects.


 -- Graphic option: ip_grid_in
     Default value: `[5, 5]'

     `ip_grid_in' sets the grid for the second sampling in implicit
     plots.

     This option is relevant only for `implicit' objects.


 -- Graphic option: x_voxel
     Default value: 10

     `x_voxel' is the number of voxels in the x direction to be used by
     the marching cubes algorithm implemented by the 3d `implicit'
     object.


 -- Graphic option: y_voxel
     Default value: 10

     `y_voxel' is the number of voxels in the y direction to be used by
     the marching cubes algorithm implemented by the 3d `implicit'
     object.


 -- Graphic option: z_voxel
     Default value: 10

     `z_voxel' is the number of voxels in the z direction to be used by
     the marching cubes algorithm implemented by the 3d `implicit'
     object.


 -- Scene constructor: gr2d (<graphic option>, ..., <graphic object>,
          ...)
     Function `gr2d' builds an object describing a 2D scene. Arguments
     are graphic options and graphic objects. This scene is interpreted
     sequentially: graphic options affect those graphic objects placed
     on its right. Some graphic options affect the global appearence of
     the scene.

     This is the list of graphic objects available for scenes in two
     dimensions: `points', `polygon', `rectangle', `bars', `ellipse',
     `label', `vector', `explicit', `implicit', `polar', `parametric',
     `image' and `geomap'.

     See also the following global graphic options: `xrange', `yrange',
     `logx', `logy', `terminal', `grid', `title', `xlabel', `ylabel',
     `xtics', `ytics', `xtics_rotate', `ytics_rotate', `xtics_axis',
     `ytics_axis', `xaxis', `yaxis', `xaxis_width', `yaxis_width',
     `xaxis_type', `yaxis_type', `xaxis_color', `yaxis_color',
     `xy_file', `file_name', `pic_width', `pic_height', `eps_width',
     `eps_height', `user_preamble', `axis_bottom', `axis_left',
     `axis_top' and `axis_right'.

     To make use of this function, write first `load(draw)'.


 -- Scene constructor: gr3d (<graphic option>, ..., <graphic object>,
          ...)
     Function `gr3d' builds an object describing a 3d scene. Arguments
     are graphic options and graphic objects. This scene is interpreted
     sequentially: graphic options affect those graphic objects placed
     on its right. Some graphic options affect the global appearence of
     the scene.

     This is the list of graphic objects available for scenes in three
     dimensions: `points', `label', `vector', `explicit', `implicit',
     `parametric', `parametric_surface' and `geomap'.

     See also the following global graphic options: `xrange', `yrange',
     `zrange', `logx', `logy', `logz', `terminal', `grid', `title',
     `xlabel', `ylabel', `zlabel', `xtics', `ytics', `ztics',
     `xtics_rotate', `ytics_rotate', `ztics_rotate', `xtics_axis',
     `ytics_axis', `ztics_axis', `xaxis', `yaxis', `zaxis',
     `xaxis_width', `yaxis_width', `zaxis_width', `xaxis_type',
     `yaxis_type', `zaxis_type', `xaxis_color', `yaxis_color',
     `zaxis_color', `xy_file', `user_preamble', `axis_bottom',
     `axis_left', `axis_top', `file_name', `pic_width', `pic_height',
     `eps_width', `eps_height', `axis_right', `rot_vertical',
     `rot_horizontal', `axis_3d', `xu_grid', `yv_grid', `surface_hide',
     `contour', `contour_levels', `palette', `colorbox' and
     `enhanced3d'.

     To make use of this function, write first `load(draw)'.


 -- Graphic object: points ([[<x1>,<y1>], [<x2>,<y2>],...])
 -- Graphic object: points ([<x1>,<x2>,...], [<y1>,<y2>,...])
 -- Graphic object: points ([<y1>,<y2>,...])
 -- Graphic object: points ([[<x1>,<y1>,<z1>], [<x2>,<y2>,<z2>],...])
 -- Graphic object: points ([<x1>,<x2>,...], [<y1>,<y2>,...],
          [<z1>,<z2>,...])
 -- Graphic object: points (<matrix>)
     Draws points in 2D and 3D.

     This object is affected by the following graphic options:
     `point_size', `point_type', `points_joined', `line_width', `key',
     `line_type' and `color'.

     2D

     `points ([[<x1>,<y1>], [<x2>,<y2>],...])' or `points
     ([<x1>,<x2>,...], [<y1>,<y2>,...])' plots points `[x1,y1]',
     `[x2,y2]', etc. If abscissas are not given, they are set to
     consecutive positive integers, so that `points ([<y1>,<y2>,...])'
     draws points `[1,<y1>]', `[2,<y2>]', etc.  If <matrix> is a
     two-column or two-row matrix, `points (<matrix>)' draws the
     associated points. If <matrix> is a one-column or one-row matrix,
     abscissas are assigned automatically.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(
                  key = "Small points",
                  points(makelist([random(20),random(50)],k,1,10)),
                  point_type    = circle,
                  point_size    = 3,
                  points_joined = true,
                  key           = "Great points",
                  points(makelist(k,k,1,20),makelist(random(30),k,1,20)),
                  point_type    = filled_down_triangle,
                  key           = "Automatic abscissas",
                  color         = red,
                  points([2,12,8]))$

          (%i1) load(draw)$
          (%i2) draw2d(
                  points_joined = impulses,
                  line_width    = 2,
                  color         = red,
                  points(makelist([random(20),random(50)],k,1,10)))$

     3D

     `points ([[<x1>,<y1>,<z1>], [<x2>,<y2>,<z2>],...])' or `points
     ([<x1>,<x2>,...], [<y1>,<y2>,...], [<z1>,<z2>,...])' plots points
     `[<x1>,<y1>,<z1>]', `[<x2>,<y2>,<z2>]', etc.  If <matrix> is a
     three-column or three-row matrix, `points (<matrix>)' draws the
     associated points.

     Examples:

     One tridimensional sample,
          (%i1) load(draw)$
          (%i2) load (numericalio)$
          (%i3) s2 : read_matrix (file_search ("wind.data"))$
          (%i4) draw3d(title = "Daily average wind speeds",
                       point_size = 2,
                       points(args(submatrix (s2, 4, 5))) )$

     Two tridimensional samples,
          (%i1) load(draw)$
          (%i2) load (numericalio)$
          (%i3) s2 : read_matrix (file_search ("wind.data"))$
          (%i4) draw3d(
                   title = "Daily average wind speeds. Two data sets",
                   point_size = 2,
                   key        = "Sample from stations 1, 2 and 3",
                   points(args(submatrix (s2, 4, 5))),
                   point_type = 4,
                   key        = "Sample from stations 1, 4 and 5",
                   points(args(submatrix (s2, 2, 3))) )$


 -- Graphic object: polygon ([[<x1>,<y1>], [<x2>,<y2>],...])
 -- Graphic object: polygon ([<x1>,<x2>,...], [<y1>,<y2>,...])
     Draws polygons in 2D.

     2D

     `polygon ([[<x1>,<y1>], [<x2>,<y2>],...])' or `polygon
     ([<x1>,<x2>,...], [<y1>,<y2>,...])': plots on the plane a polygon
     with vertices `[<x1>,<y1>]', `[<x2>,<y2>]', etc..

     This object is affected by the following graphic options:
     `transparent', `fill_color', `border', `line_width', `key',
     `line_type' and `color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(color      = "#e245f0",
                       line_width = 8,
                       polygon([[3,2],[7,2],[5,5]]),
                       border      = false,
                       fill_color  = yellow,
                       polygon([[5,2],[9,2],[7,5]]) )$


 -- Graphic object: rectangle ([<x1>,<y1>], [<x2>,<y2>])
     Draws rectangles in 2D.

     2D

     `rectangle ([<x1>,<y1>], [<x2>,<y2>])' draws a rectangle with
     opposite vertices `[<x1>,<y1>]' and `[<x2>,<y2>]'.

     This object is affected by the following graphic options:
     `transparent', `fill_color', `border', `line_width', `key',
     `line_type' and `color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(fill_color  = red,
                       line_width  = 6,
                       line_type   = dots,
                       transparent = false,
                       fill_color  = blue,
                       rectangle([-2,-2],[8,-1]), /* opposite vertices */
                       transparent = true,
                       line_type   = solid,
                       line_width  = 1,
                       rectangle([9,4],[2,-1.5]),
                       xrange      = [-3,10],
                       yrange      = [-3,4.5] )$


 -- Graphic object: bars ([<x1>,<h1>,<w1>], [<x2>,<h2>,<w2>, ...])
     Draws vertical bars in 2D.

     2D

     `bars ([<x1>,<h1>,<w1>], [<x2>,<h2>,<w2>, ...])' draws bars
     centered at values <x1>, <x2>, ... with heights <h1>, <h2>, ...
     and widths <w1>, <w2>, ...

     This object is affected by the following graphic options: `key',
     `fill_color', `fill_density' and `line_width'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(
                 key          = "Group A",
                 fill_color   = blue,
                 fill_density = 0.2,
                 bars([0.8,5,0.4],[1.8,7,0.4],[2.8,-4,0.4]),
                 key          = "Group B",
                 fill_color   = red,
                 fill_density = 0.6,
                 line_width   = 4,
                 bars([1.2,4,0.4],[2.2,-2,0.4],[3.2,5,0.4]),
                 xaxis = true);

 -- Graphic object: ellipse (<xc>, <yc>, <a>, <b>, <ang1>, <ang2>)
     Draws ellipses and circles in 2D.

     2D

     `ellipse (<xc>, <yc>, <a>, <b>, <ang1>, <ang2>)' plots an ellipse
     centered at `[<xc>, <yc>]' with horizontal and vertical semi axis
     <a> and <b>, respectively, starting at angle <ang1> with an
     amplitude equal to angle <ang2>.

     This object is affected by the following graphic options: `nticks',
     `transparent', `fill_color', `border', `line_width', `line_type',
     `key' and `color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(transparent = false,
                       fill_color  = red,
                       color       = gray30,
                       transparent = false,
                       line_width  = 5,
                       ellipse(0,6,3,2,270,-270),
                       /* center (x,y), a, b, start & end in degrees */
                       transparent = true,
                       color       = blue,
                       line_width  = 3,
                       ellipse(2.5,6,2,3,30,-90),
                       xrange      = [-3,6],
                       yrange      = [2,9] )$


 -- Graphic object: label ([<string>,<x>,<y>],...)
 -- Graphic object: label ([<string>,<x>,<y>,<z>],...)
     Writes labels in 2D and 3D.

     This object is affected by the following graphic options:
     `label_alignment', `label_orientation' and `color'.

     2D

     `label([<string>,<x>,<y>])' writes the <string> at point
     `[<x>,<y>]'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(yrange = [0.1,1.4],
                       color = "red",
                       label(["Label in red",0,0.3]),
                       color = "#0000ff",
                       label(["Label in blue",0,0.6]),
                       color = "light-blue",
                       label(["Label in light-blue",0,0.9],
                             ["Another light-blue",0,1.2])  )$

     3D

     `label([<string>,<x>,<y>,<z>])' writes the <string> at point
     `[<x>,<y>,<z>]'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(explicit(exp(sin(x)+cos(x^2)),x,-3,3,y,-3,3),
                       color = red,
                       label(["UP 1",-2,0,3], ["UP 2",1.5,0,4]),
                       color = blue,
                       label(["DOWN 1",2,0,-3]) )$


 -- Graphic object: vector ([<x>,<y>], [<dx>,<dy>])
 -- Graphic object: vector ([<x>,<y>,<z>], [<dx>,<dy>,<dz>])
     Draws vectors in 2D and 3D.

     This object is affected by the following graphic options:
     `head_both', `head_length', `head_angle', `head_type',
     `line_width', `line_type', `key' and `color'.

     2D

     `vector([<x>,<y>], [<dx>,<dy>])' plots vector `[<dx>,<dy>]' with
     origin in `[<x>,<y>]'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange      = [0,12],
                       yrange      = [0,10],
                       head_length = 1,
                       vector([0,1],[5,5]), /* default type */
                       head_type = 'empty,
                       vector([3,1],[5,5]),
                       head_both = true,
                       head_type = 'nofilled,
                       line_type = dots,
                       vector([6,1],[5,5]))$

     3D

     `vector([<x>,<y>,<z>], [<dx>,<dy>,<dz>])' plots vector
     `[<dx>,<dy>,<dz>]' with origin in `[<x>,<y>,<z>]'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(color = cyan,
                       vector([0,0,0],[1,1,1]/sqrt(3)),
                       vector([0,0,0],[1,-1,0]/sqrt(2)),
                       vector([0,0,0],[1,1,-2]/sqrt(6)) )$


 -- Graphic object: explicit (<fcn>,<var>,<minval>,<maxval>)
 -- Graphic object: explicit
          (<fcn>,<var1>,<minval1>,<maxval1>,<var2>,<minval2>,<maxval2>)
     Draws explicit functions in 2D and 3D.

     2D

     `explicit(<fcn>,<var>,<minval>,<maxval>)' plots explicit function
     <fcn>, with variable <var> taking values from <minval> to <maxval>.

     This object is affected by the following graphic options: `nticks',
     `adapt_depth', `line_width', `line_type', `key', `filled_func',
     `fill_color' and `color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(line_width = 3,
                       color      = blue,
                       explicit(x^2,x,-3,3) )$
          (%i3) draw2d(fill_color  = brown,
                       filled_func = true,
                       explicit(x^2,x,-3,3) )$

     3D

     `explicit(<fcn>,<var1>,<minval1>,<maxval1>,<var2>,<minval2>,<maxval2>)'
     plots explicit function <fcn>, with variable <var1> taking values
     from <minval1> to <maxval1> and variable <var2> taking values from
     <minval2> to <maxval2>.

     This object is affected by the following graphic options:
     `xu_grid', `yv_grid', `line_type', `key' and `color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(key   = "Gauss",
                       color = "#a02c00",
                       explicit(20*exp(-x^2-y^2)-10,x,-3,3,y,-3,3),
                       yv_grid     = 10,
                       color = blue,
                       key   = "Plane",
                       explicit(x+y,x,-5,5,y,-5,5),
                       surface_hide = true)$

     See also `filled_func' for filled functions.


 -- Graphic object: implicit (<fcn>,<x>,<xmin>,<xmax>,<y>,<ymin>,<ymax>)
 -- Graphic object: implicit
          (<fcn>,<x>,<xmin>,<xmax>,<y>,<ymin>,<ymax>,<z>,<zmin>,<zmax>)
     Draws implicit functions in 2D and 3D.

     2D

     `implicit(<fcn>,<x>,<xmin>,<xmax>,<y>,<ymin>,<ymax>)' plots the
     implicit function defined by <fcn>, with variable <x> taking values
     from <xmin> to <xmax>, and variable <y> taking values from <ymin>
     to <ymax>.

     This object is affected by the following graphic options:
     `ip_grid', `ip_grid_in', `line_width', `line_type', `key' and
     `color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(terminal  = eps,
                       grid      = true,
                       line_type = solid,
                       key       = "y^2=x^3-2*x+1",
                       implicit(y^2=x^3-2*x+1, x, -4,4, y, -4,4),
                       line_type = dots,
                       key       = "x^3+y^3 = 3*x*y^2-x-1",
                       implicit(x^3+y^3 = 3*x*y^2-x-1, x,-4,4, y,-4,4),
                       title     = "Two implicit functions" )$

     3D

     `implicit (<fcn>,<x>,<xmin>,<xmax>, <y>,<ymin>,<ymax>,
     <z>,<zmin>,<zmax>)' plots the implicit surface defined by <fcn>,
     with variable <x> taking values from <xmin> to <xmax>, variable
     <y> taking values from <ymin> to <ymax> and variable <z> taking
     values from <zmin> to <zmax>. This object implements the marching
     cubes algorithm.

     This object is affected by the following graphic options:
     `x_voxel', `y_voxel', `z_voxel', `line_width', `line_type', `key'
     and `color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(
                  color=blue,
                  implicit((x^2+y^2+z^2-1)*(x^2+(y-1.5)^2+z^2-0.5)=0.015,
                           x,-1,1,y,-1.2,2.3,z,-1,1),
                  surface_hide=true);


 -- Graphic object: polar (<radius>,<ang>,<minang>,<maxang>)
     Draws 2D functions defined in polar coordinates.

     2D

     `polar (<radius>,<ang>,<minang>,<maxang>)' plots function
     `<radius>(<ang>)' defined in polar coordinates, with variable
     <ang> taking values from <minang> to <maxang>.

     This object is affected by the following graphic options: `nticks',
     `line_width', `line_type', `key' and `color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(user_preamble = "set grid polar",
                       nticks        = 200,
                       xrange        = [-5,5],
                       yrange        = [-5,5],
                       color         = blue,
                       line_width    = 3,
                       title         = "Hyperbolic Spiral",
                       polar(10/theta,theta,1,10*%pi) )$


 -- Graphic object: spherical
          (<radius>,<azi>,<minazi>,<maxazi>,<zen>,<minzen>,<maxzen>)
     Draws 3D functions defined in spherical coordinates.

     3D

     `spherical
     (<radius>,<azi>,<minazi>,<maxazi>,<zen>,<minzen>,<maxzen>)' plots
     function `<radius>(<azi>,<zen>)' defined in spherical coordinates,
     with azimuth <azi> taking values from <minazi> to <maxazi> and
     zenith <zen> taking values from <minzen> to <maxzen>.

     This object is affected by the following graphic options:
     `xu_grid', `yv_grid', `line_type', `key' and `color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(spherical(1,a,0,2*%pi,z,0,%pi))$


 -- Graphic object: cylindrical
          (<radius>,<z>,<minz>,<maxz>,<azi>,<minazi>,<maxazi>)
     Draws 3D functions defined in cylindrical coordinates.

     3D

     `cylindrical (<radius>,<z>,<minz>,<maxz>,<azi>,<minazi>,<maxazi>)'
     plots function `<radius>(<z>,<azi>)' defined in cylindrical
     coordinates, with variable <z> taking values from <minz> to <maxz>
     and azimuth <azi> taking values from <minazi> to <maxazi>.

     This object is affected by the following graphic options:
     `xu_grid', `yv_grid', `line_type', `key' and `color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(cylindrical(1,z,-2,2,az,0,2*%pi))$


 -- Graphic object: parametric (<xfun>,<yfun>,<par>,<parmin>,<parmax>)
 -- Graphic object: parametric
          (<xfun>,<yfun>,<zfun>,<par>,<parmin>,<parmax>)
     Draws parametric functions in 2D and 3D.

     This object is affected by the following graphic options: `nticks',
     `line_width', `line_type', `key' and `color'.

     2D

     `parametric (<xfun>,<yfun>,<par>,<parmin>,<parmax>)' plots
     parametric function `[<xfun>,<yfun>]', with parameter <par> taking
     values from <parmin> to <parmax>.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(exp(x),x,-1,3),
                       color = red,
                       key   = "This is the parametric one!!",
                       parametric(2*cos(rrr),rrr^2,rrr,0,2*%pi))$

     3D

     `parametric (<xfun>,<yfun>,<zfun>,<par>,<parmin>,<parmax>)' plots
     parametric curve `[<xfun>,<yfun>,<zfun>]', with parameter <par>
     taking values from <parmin> to <parmax>.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(explicit(exp(sin(x)+cos(x^2)),x,-3,3,y,-3,3),
                       color = royalblue,
                       parametric(cos(5*u)^2,sin(7*u),u-2,u,0,2),
                       color      = turquoise,
                       line_width = 2,
                       parametric(t^2,sin(t),2+t,t,0,2),
                       surface_hide = true,
                       title = "Surface & curves" )$


 -- Graphic object: image (<im>,<x0>,<y0>,<width>,<height>)
     Renders images in 2D.

     2D

     `image (<im>,<x0>,<y0>,<width>,<height>)' plots image <im> in the
     rectangular region from vertex `(<x0>,<y0>)' to
     `(x0+<width>,y0+<height>)' on the real plane. Argument <im> must
     be a matrix of real numbers, a matrix of vectors of length three
     or a <picture> object.

     If <im> is a matrix of real numbers or a <levels picture> object,
     pixel values are interpreted according to graphic option `palette',
     which is a vector of length three with components ranging from -36
     to +36; each value is an index for a formula mapping the levels
     onto red, green and blue colors, respectively:
           0: 0               1: 0.5           2: 1
           3: x               4: x^2           5: x^3
           6: x^4             7: sqrt(x)       8: sqrt(sqrt(x))
           9: sin(90x)       10: cos(90x)     11: |x-0.5|
          12: (2x-1)^2       13: sin(180x)    14: |cos(180x)|
          15: sin(360x)      16: cos(360x)    17: |sin(360x)|
          18: |cos(360x)|    19: |sin(720x)|  20: |cos(720x)|
          21: 3x             22: 3x-1         23: 3x-2
          24: |3x-1|         25: |3x-2|       26: (3x-1)/2
          27: (3x-2)/2       28: |(3x-1)/2|   29: |(3x-2)/2|
          30: x/0.32-0.78125                  31: 2*x-0.84
          32: 4x;1;-2x+1.84;x/0.08-11.5
          33: |2*x - 0.5|    34: 2*x          35: 2*x - 0.5
          36: 2*x - 1
     negative numbers mean negative colour component.

     `palette = gray' and `palette = color' are short cuts for `palette
     = [3,3,3]' and `palette = [7,5,15]', respectively.

     If <im> is a matrix of vectors of length three or an <rgb picture>
     object, they are interpreted as red, green and blue color
     components.

     Examples:

     If <im> is a matrix of real numbers, pixel values are interpreted
     according to graphic option `palette'.
          (%i1) load(draw)$
          (%i2) im: apply(
                     'matrix,
                      makelist(makelist(random(200),i,1,30),i,1,30))$
          (%i3) /* palette = color, default */
                draw2d(image(im,0,0,30,30))$
          (%i4) draw2d(palette = gray, image(im,0,0,30,30))$
          (%i5) draw2d(palette = [15,20,-4],
                       colorbox=false,
                       image(im,0,0,30,30))$

     See also `colorbox'.

     If <im> is a matrix of vectors of length three, they are
     interpreted as red, green and blue color components.
          (%i1) load(draw)$
          (%i2) im: apply(
                      'matrix,
                       makelist(
                         makelist([random(300),
                                   random(300),
                                   random(300)],i,1,30),i,1,30))$
          (%i3) draw2d(image(im,0,0,30,30))$

     Package `draw' automatically loads package `picture'. In this
     example, a level picture object is built by hand and then rendered.
          (%i1) load(draw)$
          (%i2) im: make_level_picture([45,87,2,134,204,16],3,2);
          (%o2)       picture(level, 3, 2, {Array:  #(45 87 2 134 204 16)})
          (%i3) /* default color palette */
                draw2d(image(im,0,0,30,30))$
          (%i4) /* gray palette */
                draw2d(palette = gray,
                       image(im,0,0,30,30))$

     An xpm file is read and then rendered.
          (%i1) load(draw)$
          (%i2) im: read_xpm("myfile.xpm")$
          (%i3) draw2d(image(im,0,0,10,7))$

     See also `make_level_picture', `make_rgb_picture' and `read_xpm'.

     URL `http://www.telefonica.net/web2/biomates/maxima/gpdraw/image'
     contains more elaborated examples.


 -- Global variable: boundaries_array
     Default value: `false'

     `boundaries_array' is where the graphic object `geomap' looks for
     boundaries coordinates.

     Each component of `boundaries_array' is an array of floating point
     quantities, the coordinates of a polygonal segment or map boundary.

     See also `geomap'.


 -- Graphic object: geomap (<numlist>)
 -- Graphic object: geomap (<numlist>,<3Dprojection>)
     Draws cartographic maps in 2D and 3D.

     2D

     This function works together with global variable
     `boundaries_array'.

     Argument <numlist> is a list containing numbers or lists of
     numbers.  All these numbers must be integers greater or equal than
     zero, representing the components of global array
     `boundaries_array'.

     Each component of `boundaries_array' is an array of floating point
     quantities, the coordinates of a polygonal segment or map boundary.

     `geomap (<numlist>)' flattens its arguments and draws the
     associated boundaries in `boundaries_array'.

     This object is affected by the following graphic options:
     `line_width', `line_type' and `color'.

     Examples:

     A simple map defined by hand:
          (%i1) load(draw)$
          (%i2) /* Vertices of boundary #0: {(1,1),(2,5),(4,3)} */
             ( bnd0: make_array(flonum,6),
               bnd0[0]:1.0, bnd0[1]:1.0, bnd0[2]:2.0,
               bnd0[3]:5.0, bnd0[4]:4.0, bnd0[5]:3.0 )$
          (%i3) /* Vertices of boundary #1: {(4,3),(5,4),(6,4),(5,1)} */
             ( bnd1: make_array(flonum,8),
               bnd1[0]:4.0, bnd1[1]:3.0, bnd1[2]:5.0, bnd1[3]:4.0,
               bnd1[4]:6.0, bnd1[5]:4.0, bnd1[6]:5.0, bnd1[7]:1.0)$
          (%i4) /* Vertices of boundary #2: {(5,1), (3,0), (1,1)} */
             ( bnd2: make_array(flonum,6),
               bnd2[0]:5.0, bnd2[1]:1.0, bnd2[2]:3.0,
               bnd2[3]:0.0, bnd2[4]:1.0, bnd2[5]:1.0 )$
          (%i5) /* Vertices of boundary #3: {(1,1), (4,3)} */
             ( bnd3: make_array(flonum,4),
               bnd3[0]:1.0, bnd3[1]:1.0, bnd3[2]:4.0, bnd3[3]:3.0)$
          (%i6) /* Vertices of boundary #4: {(4,3), (5,1)} */
             ( bnd4: make_array(flonum,4),
               bnd4[0]:4.0, bnd4[1]:3.0, bnd4[2]:5.0, bnd4[3]:1.0)$
          (%i7) /* Pack all together in boundaries_array */
             ( boundaries_array: make_array(any,5),
               boundaries_array[0]: bnd0, boundaries_array[1]: bnd1,
               boundaries_array[2]: bnd2, boundaries_array[3]: bnd3,
               boundaries_array[4]: bnd4 )$
          (%i8) draw2d(geomap([0,1,2,3,4]))$

     Auxiliary package `worldmap' sets global variable
     `boundaries_array' to real world boundaries in (longitude,
     latitude) coordinates. These data are in the public domain and
     come from `http://www-cger.nies.go.jp/grid-e/gridtxt/grid19.html'.
     Package `worldmap' defines also boundaries for countries,
     continents and coastlines as lists with the necessary components of
     `boundaries_array' (see file `share/draw/worldmap.mac' for more
     information). Package `draw' does not automatically load
     `worldmap'.
          (%i1) load(draw)$
          (%i2) load(worldmap)$
          (%i3) c1: gr2d(geomap(Canada,United_States,
                                Mexico,Cuba))$
          (%i4) c2: gr2d(geomap(Africa))$
          (%i5) c3: gr2d(geomap(Oceania,China,Japan))$
          (%i6) c4: gr2d(geomap(France,Portugal,Spain,
                                Morocco,Western_Sahara))$
          (%i7) draw(columns  = 2,
                     c1,c2,c3,c4)$

     Package `worldmap' is also useful for plotting countries as
     polygons. In this case, graphic object `geomap' is no longer
     necessary and the `polygon' object is used instead. Since lists
     are now used and not arrays, maps rendering will be slower. See
     also `make_poly_country' and `make_poly_continent' to understand
     the following code.
          (%i1) load(draw)$
          (%i2) load(worldmap)$
          (%i3) mymap: append(
             [color      = white],  /* borders are white */
             [fill_color = red],             make_poly_country(Bolivia),
             [fill_color = cyan],            make_poly_country(Paraguay),
             [fill_color = green],           make_poly_country(Colombia),
             [fill_color = blue],            make_poly_country(Chile),
             [fill_color = "#23ab0f"],       make_poly_country(Brazil),
             [fill_color = goldenrod],       make_poly_country(Argentina),
             [fill_color = "midnight-blue"], make_poly_country(Uruguay))$
          (%i4) apply(draw2d, mymap)$

     3D

     `geomap (<numlist>)' projects map boundaries on the sphere of
     radius 1 centered at (0,0,0). It is possible to change the sphere
     or the projection type by using `geomap
     (<numlist>,<3Dprojection>)'.

     Available 3D projections:

        * `[spherical_projection,<x>,<y>,<z>,<r>]': projects map
          boundaries on the sphere of radius <r> centered at
          (<x>,<y>,<z>).
               (%i1) load(draw)$
               (%i2) load(worldmap)$
               (%i3) draw3d(geomap(Australia), /* default projection */
                            geomap(Australia,
                                   [spherical_projection,2,2,2,3]))$

        * `[cylindrical_projection,<x>,<y>,<z>,<r>,<rc>]': re-projects
          spherical map boundaries on the cylinder of radius <rc> and
          axis passing through the poles of the globe of radius <r>
          centered at (<x>,<y>,<z>).
               (%i1) load(draw)$
               (%i2) load(worldmap)$
               (%i3) draw3d(geomap([America_coastlines,Eurasia_coastlines],
                                   [cylindrical_projection,2,2,2,3,4]))$

        * `[conic_projection,<x>,<y>,<z>,<r>,<alpha>]': re-projects
          spherical map boundaries on the cones of angle <alpha>, with
          axis passing through the poles of the globe of radius <r>
          centered at (<x>,<y>,<z>). Both the northern and southern
          cones are tangent to sphere.
               (%i1) load(draw)$
               (%i2) load(worldmap)$
               (%i3) draw3d(geomap(World_coastlines,
                                   [conic_projection,0,0,0,1,90]))$

     See also
     `http://www.telefonica.net/web2/biomates/maxima/gpdraw/geomap' for
     more elaborated examples.


 -- Graphic object: parametric_surface
          (<xfun>,<yfun>,<zfun>,<par1>,<par1min>,<par1max>,<par2>,<par2min>,<par2max>)
     Draws parametric surfaces in 3D.

     3D

     `parametric_surface
     (<xfun>,<yfun>,<zfun>,<par1>,<par1min>,<par1max>,<par2>,<par2min>,<par2max>)'
     plots parametric surface `[<xfun>,<yfun>,<zfun>]', with parameter
     <par1> taking values from <par1min> to <par1max> and parameter
     <par2> taking values from <par2min> to <par2max>.

     This object is affected by the following graphic options:
     `xu_grid', `yv_grid', `line_type', `key' and `color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(title          = "Sea shell",
                       xu_grid        = 100,
                       yv_grid        = 25,
                       rot_vertical   = 100,
                       rot_horizontal = 20,
                       surface_hide   = true,
                       parametric_surface(0.5*u*cos(u)*(cos(v)+1),
                                     0.5*u*sin(u)*(cos(v)+1),
                                     u*sin(v) - ((u+3)/8*%pi)^2 - 20,
                                     u, 0, 13*%pi, v, -%pi, %pi) )$


 -- Function: draw (<gr2d>, ..., <gr3d>, ..., <options>, ...)
     Plots a series of scenes; its arguments are `gr2d' and/or `gr3d'
     objects, together with some options. By default, the scenes are
     put together in one column.

     Function `draw' accepts the following global options: `terminal',
     `columns', `pic_width', `pic_height', `eps_width', `eps_height',
     `file_name' and `delay'.

     Functions `draw2d' and `draw3d' are short cuts to be used when
     only one scene is required, in two or three dimensions,
     respectively.

     To make use of this function, write first `load(draw)'.

     Example:

          (%i1) load(draw)$
          (%i2) scene1: gr2d(title="Ellipse",
                             nticks=30,
                             parametric(2*cos(t),5*sin(t),t,0,2*%pi))$
          (%i3) scene2: gr2d(title="Triangle",
                             polygon([4,5,7],[6,4,2]))$
          (%i4) draw(scene1, scene2, columns = 2)$

     The two draw sentences are equivalent:
          (%i1) load(draw)$
          (%i2) draw(gr3d(explicit(x^2+y^2,x,-1,1,y,-1,1)));
          (%o2)                          [gr3d(explicit)]
          (%i3) draw3d(explicit(x^2+y^2,x,-1,1,y,-1,1));
          (%o3)                          [gr3d(explicit)]

     An animated gif file:
          (%i1) load(draw)$
          (%i2) draw(
                  delay     = 100,
                  file_name = "zzz",
                  terminal  = 'animated_gif,
                  gr2d(explicit(x^2,x,-1,1)),
                  gr2d(explicit(x^3,x,-1,1)),
                  gr2d(explicit(x^4,x,-1,1)));
          End of animation sequence
          (%o2)          [gr2d(explicit), gr2d(explicit), gr2d(explicit)]

     See also `gr2d', `gr3d', `draw2d' and `draw3d'..


 -- Function: draw2d (<option>, <graphic_object>, ...)
     This function is a short cut for `draw(gr2d(<options>, ...,
     <graphic_object>, ...))'.

     It can be used to plot a unique scene in 2d.

     To make use of this function, write first `load(draw)'.

     See also `draw' and `gr2d'.


 -- Function: draw3d (<option>, <graphic_object>, ...)
     This function is a short cut for `draw(gr3d(<options>, ...,
     <graphic_object>, ...))'.

     It can be used to plot a unique scene in 3d.

     To make use of this function, write first `load(draw)'.

     See also `draw' and `gr3d'.



File: maxima.info,  Node: Functions and Variables for pictures,  Next: Functions and Variables for worldmap,  Prev: Functions and Variables for draw,  Up: draw

48.3 Functions and Variables for pictures
=========================================

 -- Function: make_level_picture (<data>)
 -- Function: make_level_picture (<data>,<width>,<height>)
     Returns a levels <picture> object. `make_level_picture (<data>)'
     builds the <picture> object from matrix <data>.
     `make_level_picture (<data>,<width>,<height>)' builds the object
     from a list of numbers; in this case, both the <width> and the
     <height> must be given.

     The returned <picture> object contains the following four parts:

       1. symbol `level'

       2. image width

       3. image height

       4. an integer array with pixel data ranging from 0 to 255.
          Argument <data> must contain only numbers ranged from 0 to
          255; negative numbers are substituted by 0, and those which
          are greater than 255 are set to 255.

     Example:

     Level picture from matrix.
          (%i1) load(draw)$
          (%i2) make_level_picture(matrix([3,2,5],[7,-9,3000]));
          (%o2)         picture(level, 3, 2, {Array:  #(3 2 5 7 0 255)})

     Level picture from numeric list.
          (%i1) load(draw)$
          (%i2) make_level_picture([-2,0,54,%pi],2,2);
          (%o2)            picture(level, 2, 2, {Array:  #(0 0 54 3)})


 -- Function: picturep (<x>)
     Returns `true' if the argument is a well formed image, and `false'
     otherwise.


 -- Function: picture_equalp (<x>,<y>)
     Returns `true' in case of equal pictures, and `false' otherwise.


 -- Function: make_rgb_picture (<redlevel>,<greenlevel>,<bluelevel>)
     Returns an rgb-coloured <picture> object. All three arguments must
     be levels picture; with red, green and blue levels.

     The returned <picture> object contains the following four parts:

       1. symbol `rgb'

       2. image width

       3. image height

       4. an integer array of length <3*width*height> with pixel data
          ranging from 0 to 255. Each pixel is represented by three
          consecutive numbers (red, green, blue).

     Example:

          (%i1) load(draw)$
          (%i2) red: make_level_picture(matrix([3,2],[7,260]));
          (%o2)           picture(level, 2, 2, {Array:  #(3 2 7 255)})
          (%i3) green: make_level_picture(matrix([54,23],[73,-9]));
          (%o3)           picture(level, 2, 2, {Array:  #(54 23 73 0)})
          (%i4) blue: make_level_picture(matrix([123,82],[45,32.5698]));
          (%o4)          picture(level, 2, 2, {Array:  #(123 82 45 33)})
          (%i5) make_rgb_picture(red,green,blue);
          (%o5) picture(rgb, 2, 2,
                        {Array:  #(3 54 123 2 23 82 7 73 45 255 0 33)})


 -- Function: take_channel (<im>,<color>)
     If argument <color> is `red', `green' or `blue', function
     `take_channel' returns the corresponding color channel of picture
     <im>.  Example:

          (%i1) load(draw)$
          (%i2) red: make_level_picture(matrix([3,2],[7,260]));
          (%o2)           picture(level, 2, 2, {Array:  #(3 2 7 255)})
          (%i3) green: make_level_picture(matrix([54,23],[73,-9]));
          (%o3)           picture(level, 2, 2, {Array:  #(54 23 73 0)})
          (%i4) blue: make_level_picture(matrix([123,82],[45,32.5698]));
          (%o4)          picture(level, 2, 2, {Array:  #(123 82 45 33)})
          (%i5) make_rgb_picture(red,green,blue);
          (%o5) picture(rgb, 2, 2,
                        {Array:  #(3 54 123 2 23 82 7 73 45 255 0 33)})
          (%i6) take_channel(%,'green);  /* simple quote!!! */
          (%o6)           picture(level, 2, 2, {Array:  #(54 23 73 0)})


 -- Function: negative_picture (<pic>)
     Returns the negative of a (<level> or <rgb>) picture.


 -- Function: rgb2level (<pic>)
     Transforms an <rgb> picture into a <level> one by averaging the
     red, green and blue channels.


 -- Function: get_pixel (<pic>,<x>,<y>)
     Returns pixel from picture. Coordinates <x> and <y> range from 0 to
     `width-1' and `height-1', respectively.


 -- Function: read_xpm (<xpm_file>)
     Reads a file in xpm and returns a picture object.



File: maxima.info,  Node: Functions and Variables for worldmap,  Prev: Functions and Variables for pictures,  Up: draw

48.4 Functions and Variables for worldmap
=========================================

 -- Function: region_boundaries (<x1>,<y1>,<x2>,<y2>)
     Detects polygonal segments of global variable `boundaries_array'
     contained in the rectangle with vertices (<x1>,<y1>) -upper left-
     and (<x2>,<y2>) -bottom right-.

     Example:

     Returns segment numbers for plotting southern Italy.
          (%i1) load(draw)$
          (%i2) load(worldmap)$
          (%i3) region_boundaries(10.4,41.5,20.7,35.4);
          (%o3)                [1846, 1863, 1864, 1881, 1888, 1894]
          (%i4) draw2d(geomap(%))$


 -- Function: numbered_boundaries (<nlist>)
     Draws a list of polygonal segments (boundaries), labeled by its
     numbers (`boundaries_array' coordinates). This is of great help
     when building new geographical entities.

     Example:

     Map of Europe labeling borders with their component number in
     `boundaries_array'.
          (%i1) load(draw)$
          (%i2) load(worldmap)$
          (%i3) european_borders:
                     region_boundaries(-31.81,74.92,49.84,32.06)$
          (%i4) numbered_boundaries(european_borders)$


 -- Function: make_polygon (<nlist>)
     Returns a `polygon' object from boundary indices. Argument <nlist>
     is a list of components of `boundaries_array'.

     Example:

     Bhutan is defined by boundary numbers 171, 173 and 1143, so that
     `make_polygon([171,173,1143])' appends arrays of coordinates
     `boundaries_array[171]', `boundaries_array[173]' and
     `boundaries_array[1143]' and returns a `polygon' object suited to
     be plotted by `draw'. To avoid an error message, arrays must be
     compatible in the sense that any two consecutive arrays have two
     coordinates in the extremes in common. In this example, the two
     first components of `boundaries_array[171]' are equal to the last
     two coordinates of `boundaries_array[173]', and the two first of
     `boundaries_array[173]' are equal to the two first of
     `boundaries_array[1143]'; in conclussion, boundary numbers 171,
     173 and 1143 (in this order) are compatible and the colored
     polygon can be drawn.
          (%i1) load(draw)$
          (%i2) load(worldmap)$
          (%i3) Bhutan;
          (%o3)                        [[171, 173, 1143]]
          (%i4) boundaries_array[171];
          (%o4) {Array:
                 #(88.750549 27.14727 88.806351 27.25305 88.901367 27.282221
                   88.917877 27.321039)}
          (%i5) boundaries_array[173];
          (%o5) {Array:
                 #(91.659554 27.76511 91.6008 27.66666 91.598022 27.62499
                   91.631348 27.536381 91.765533 27.45694 91.775253 27.4161
                   92.007751 27.471939 92.11441 27.28583 92.015259 27.168051
                   92.015533 27.08083 92.083313 27.02277 92.112183 26.920271
                   92.069977 26.86194 91.997192 26.85194 91.915253 26.893881
                   91.916924 26.85416 91.8358 26.863331 91.712479 26.799999
                   91.542191 26.80444 91.492188 26.87472 91.418854 26.873329
                   91.371353 26.800831 91.307457 26.778049 90.682457 26.77417
                   90.392197 26.903601 90.344131 26.894159 90.143044 26.75333
                   89.98996 26.73583 89.841919 26.70138 89.618301 26.72694
                   89.636093 26.771111 89.360786 26.859989 89.22081 26.81472
                   89.110237 26.829161 88.921631 26.98777 88.873016 26.95499
                   88.867737 27.080549 88.843307 27.108601 88.750549
                   27.14727)}
          (%i6) boundaries_array[1143];
          (%o6) {Array:
                 #(91.659554 27.76511 91.666924 27.88888 91.65831 27.94805
                   91.338028 28.05249 91.314972 28.096661 91.108856 27.971109
                   91.015808 27.97777 90.896927 28.05055 90.382462 28.07972
                   90.396088 28.23555 90.366074 28.257771 89.996353 28.32333
                   89.83165 28.24888 89.58609 28.139999 89.35997 27.87166
                   89.225517 27.795 89.125793 27.56749 88.971077 27.47361
                   88.917877 27.321039)}
          (%i7) Bhutan_polygon: make_polygon([171,173,1143])$
          (%i8) draw2d(Bhutan_polygon)$


 -- Function: make_poly_country (<country_name>)
     Makes the necessary polygons to draw a colored country.  If
     islands exist, one country can be defined with more than just one
     polygon.

     Example:

          (%i1) load(draw)$
          (%i2) load(worldmap)$
          (%i3) make_poly_country(India)$
          (%i4) apply(draw2d, %)$


 -- Function: make_poly_continent (<continent_name>)
 -- Function: make_poly_continent (<country_list>)
     Makes the necessary polygons to draw a colored continent or a list
     of countries.

     Example:

          (%i1) load(draw)$
          (%i2) load(worldmap)$
          (%i3) /* A continent */
                make_poly_continent(Africa)$
          (%i4) apply(draw2d, %)$
          (%i5) /* A list of countries */
                make_poly_continent([Germany,Denmark,Poland])$
          (%i6) apply(draw2d, %)$



File: maxima.info,  Node: dynamics,  Next: ezunits,  Prev: draw,  Up: Top

49 dynamics
***********

* Menu:

* Introduction to dynamics::
* Functions and Variables for dynamics::


File: maxima.info,  Node: Introduction to dynamics,  Next: Functions and Variables for dynamics,  Prev: dynamics,  Up: dynamics

49.1 Introduction to dynamics
=============================

The additional package `dynamics' includes several functions to create
various graphical representations of discrete dynamical systems and
fractals, and an implementation of the Runge-Kutta 4th-order numerical
method for solving systems of differential equations.

   To use the functions in this package you must first load it with
`load("dynamics")'.

   Changes introduced in Maxima 5.12

   Starting with Maxima 5.12, the dynamics package now uses the function
`plot2d' to do the graphs. The commands that produce graphics (with the
exception of `julia' and `mandelbrot') now accept any options of
`plot2d', including the option to change among the various graphical
interfaces, using different plot styles and colors, and representing
one or both axes in a logarithmic scale. The old options <domain>,
<pointsize>, <xcenter>, <xradius>, <ycenter>, <yradius>, <xaxislabel>
and <yaxislabel> are not accepted in this new version.

   All programs will now accept any variables names, and not just <x>
and <y> as in the older versions. Two required parameters have changes
in two of the programs: `evolution2d' now requires a list naming
explicitely the two independent variables, and the horizontal range for
`orbits' no longer requires a step size; the range should only specify
the variable name, and the minimum and maximum values; the number of
steps can now be changed with the option <nticks>.


File: maxima.info,  Node: Functions and Variables for dynamics,  Prev: Introduction to dynamics,  Up: dynamics

49.2 Functions and Variables for dynamics
=========================================

 -- Function: chaosgame (`[['<x1>, <y1>`]'...`['<xm>, <ym>`]]',
          `['<x0>, <y0>`]', <b>, <n>, ..., options, ...);
     Implements the so-called chaos game: the initial point (<x0>,
     <y0>) is plotted and then one of the <m> points `['<x1>,
     <y1>`]'...`['<xm>, <ym>`]' will be selected at random. The next
     point plotted will be on the segment from the previous point
     plotted to the point chosen randomly, at a distance from the
     random point which will be <b> times that segment's length. The
     procedure is repeated <n> times.


 -- Function: evolution (<F>, <y0>, <n>, ..., options, ...);
     Draws <n+1> points in a two-dimensional graph, where the horizontal
     coordinates of the points are the integers 0, 1, 2, ..., <n>, and
     the vertical coordinates are the corresponding values <y(n)> of the
     sequence defined by the recurrence relation
                  y(n+1) = F(y(n))

     With initial value <y(0)> equal to <y0>. <F> must be an expression
     that depends only on one variable (in the example, it depend on
     <y>, but any other variable can be used), <y0> must be a real
     number and <n> must be a positive integer.


 -- Function: evolution2d (`['<F>, <G>`]', `['<u>, <v>`]', `['<u0>,
          <y0>`]', <n>, ..., options, ...);
     Shows, in a two-dimensional plot, the first <n+1> points in the
     sequence of points defined by the two-dimensional discrete
     dynamical system with recurrence relations
                  u(n+1) = F(u(n), v(n))    v(n+1) = G(u(n), v(n))

     With initial values <u0> and <v0>. <F> and <G> must be two
     expressions that depend only on two variables, <u> and <v>, which
     must be named explicitely in a list.


 -- Function: ifs (`['<r1>, ..., <rm>`]', `['<A1>, ..., <Am>`]',
          `[['<x1>, <y1>`]', ..., `['<xm>, <ym>`]]', `['<x0>, <y0>`]',
          <n>, ..., options, ...);
     Implements the Iterated Function System method. This method is
     similar to the method described in the function `chaosgame', but
     instead of shrinking the segment from the current point to the
     randomly chosen point, the 2 components of that segment will be
     multiplied by the 2 by 2 matrix <Ai> that corresponds to the point
     chosen randomly.

     The random choice of one of the <m> attractive points can be made
     with a non-uniform probability distribution defined by the weights
     <r1>,...,<rm>. Those weights are given in cumulative form; for
     instance if there are 3 points with probabilities 0.2, 0.5 and
     0.3, the weights <r1>, <r2> and <r3> could be 2, 7 and 10.


 -- Function: julia (<x>, <y>, ...<options>...)
     Creates a graphics file with the representation of the Julia set
     for the complex number (<x> + i <y>). The parameters <x> and <y>
     must be real. The file is created in the current directory or in
     the user's directory, using the XPM graphics format. The program
     may take several seconds to run and after it is finished, a
     message will be printed with the name of the file created.

     The points which do not belong to the Julia set are assigned
     different colors, according to the number of iterations it takes
     the sequence starting at that point to move out of the convergence
     circle of radius 2. The maximum number of iterations is set with
     the option <levels>; after that number of iterations, if the
     sequence is still inside the convergence circle, the point will be
     painted with the color defined by the option <color>.

     All the colors used for the points that do not belong to the Julia
     set will have the same <saturation> and <value>, but with different
     hue angles distributed uniformly between <hue> and (<hue> +
     <huerange>).

     <options> is an optional sequence of options. The list of accepted
     options is given in a section below.


 -- Function: mandelbrot (<options>)
     Creates a graphics file with the representation of the Mandelbrot
     set. The file is created in the current directory or in the user's
     directory, using the XPM graphics format. The program may take
     several seconds to run and after it is finished, a message will be
     printed with the name of the file created.

     The points which do not belong to the Mandelbrot set are assigned
     different colors, according to the number of iterations it takes
     the sequence generated with that point to move out of the
     convergence circle o radius 2. The maximum number of iterations is
     set with the option <levels>; after that number of iterations, if
     the sequence is still inside the convergence circle, the point
     will be painted with the color defined by the option <color>.

     All the colors used for the points that do not belong to the
     Mandelbrot set will have the same <saturation> and <value>, but
     with different hue angles distributed uniformly between <hue> and
     (<hue> + <huerange>).

     <options> is an optional sequence of options. The list of accepted
     options is given in a section below.


 -- Function: orbits (<F>, <y0>, <n1>, <n2>, [<x>, <x0>, <xf>,
          <xstep>], ...options...);
     Draws the orbits diagram for a family of one-dimensional discrete
     dynamical systems, with one parameter <x>; that kind of diagram is
     used to study the bifurcations of a one-dimensional discrete
     system.

     The function <F(y)> defines a sequence with a starting value of
     <y0>, as in the case of the function `evolution', but in this case
     that function will also depend on a parameter <x> that will take
     values in the interval from <x0> to <xf> with increments of
     <xstep>. Each value used for the parameter <x> is shown on the
     horizontal axis. The vertical axis will show the <n2> values of
     the sequence <y(n1+1)>,..., <y(n1+n2+1)> obtained after letting
     the sequence evolve <n1> iterations.


 -- Function: rk (<ODE>, <var>, <initial>, <domain>)
 -- Function: rk ([<ODE1>,...,<ODEm>], [<v1>,...,<vm>],
          [<init1>,...,<initm>], <domain>)
     The first form solves numerically one first-order ordinary
     differential equation, and the second form solves a system of m of
     those equations, using the 4th order Runge-Kutta method. <var>
     represents the dependent variable. <ODE> must be an expression
     that depends only on the independent and dependent variables and
     defines the derivative of the dependent variable with respect to
     the independent variable.

     The independent variable is specified with `domain', which must be
     a list of four elements as, for instance:
          [t, 0, 10, 0.1]
     the first element of the list identifies the independent variable,
     the second and third elements are the initial and final values for
     that variable, and the last element sets the increments that
     should be used within that interval.

     If <m> equations are going to be solved, there should be <m>
     dependent variables <v1>, <v2>, ..., <vm>. The initial values for
     those variables will be <init1>, <init2>, ..., <initm>.  There
     will still be just one independent variable defined by `domain',
     as in the previous case. <ODE1>, ..., <ODEm> are the expressions
     that define the derivatives of each dependent variable in terms of
     the independent variable. The only variables that may appear in
     those expressions are the independent variable and any of the
     dependent variables. It is important to give the derivatives
     <ODE1>, ..., <ODEm> in the list in exactly the same order used for
     the dependent variables; for instance, the third element in the
     list will be interpreted as the derivative of the third dependent
     variable.

     The program will try to integrate the equations from the initial
     value of the independent variable until its last value, using
     constant increments. If at some step one of the dependent
     variables takes an absolute value too large, the integration will
     be interrupted at that point. The result will be a list with as
     many elements as the number of iterations made. Each element in
     the results list is itself another list with <m>+1 elements: the
     value of the independent variable, followed by the values of the
     dependent variables corresponding to that point.


 -- Function: staircase (<F>, <y0>, <n>, ...options...);
     Draws a staircase diagram for the sequence defined by the
     recurrence relation
                  y(n+1) = F(y(n))

     The interpretation and allowed values of the input parameters is
     the same as for the function `evolution'. A staircase diagram
     consists of a plot of the function <F(y)>, together with the line
     <G(y)> `=' <y>. A vertical segment is drawn from the point (<y0>,
     <y0>) on that line until the point where it intersects the
     function <F>. From that point a horizontal segment is drawn until
     it reaches the point (<y1>, <y1>) on the line, and the procedure
     is repeated <n> times until the point (<yn>, <yn>) is reached.


   Options

   Each option is a list of two or more items. The first item is the
name of the option, and the remainder comprises the arguments for the
option.

   The options accepted by the functions `evolution', `evolution2d',
`staircase', `orbits', `ifs' and `chaosgame' are the same as the
options for `plot2d'. In addition to those options, `orbits' accepts and
extra option <pixels> that sets up the maximum number of different
points that will be represented in the vertical direction.

   The following options are accepted by the functions `julia' and
`mandelbrot':

   * "size" takes either one or two arguments. If only one argument is
     given, the width and height of the graphic file created will be
     equal to that value, in pixels. If two arguments are given, they
     will define the width and height. The default value is 400 pixels
     for both the width and height. If the two values are not equal,
     the set will appear distorted.

   * "levels" defines the maximum number of iterations, which is also
     equal to the number of colors used for points not belonging to the
     set. The default value is 12; larger values mean much longer
     processing times.

   * "huerange" defines the range of hue angles used for the hue of
     points not belonging to the set. The default value is 360, which
     means that the colors will expand all the range of hues. Values
     bigger than 360, will mean repeated ranges of the hue, and negative
     values can be used to make the hue angle decrease as the number of
     iterations increases.

   * "hue" sets the hue, in degrees, of the first color used for the
     points which do not belong to the set. Its default value is 300
     degrees, which corresponds to magenta; the values for other
     standard colors are 0 for red, 45 for orange, 60 for yellow, 120
     for green, 180 for cyan and 240 for blue. See also option
     <huerange>.

   * "saturation" sets the value of the saturation used for points not
     belonging to the set. It must be between 0 and 1. The default is
     0.46.

   * "value" sets the value of the colors used for points not belonging
     to the set. It must be between 0 and 1; the higher the value, the
     brighter the colors. The default is 0.96

   * "color" must be followed by three parameters that define the hue,
     saturation and value, for the color used to represent the points
     of the set. The default value is 0 for the three parameters, which
     corresponds to black. For an explanation of the range of allowed
     values, see options <hue>, <saturation> and <value>.

   * "center" must be followed by two real parameters, which give the
     coordinates, on the complex plane, of the point in the center of
     the region shown. The default value is 0 for both coordinates (the
     origin).

   * "radius" sets the radius of the biggest circle inside the square
     region that will be displayed. The default value is 2.

   * "filename" gives the name of the file where the resulting graph
     will be saved. The extension .xpm will be added to that name. If
     the file already exists, it will be replaced by the file generated
     by the function. The default values are julia for the Julia set,
     and mandelbrot for the Mandelbrot set.


   Examples

   Graphical representation and staircase diagram for the sequence: 2,
cos(2), cos(cos(2)),...

     (%i1) load("dynamics")$

     (%i2) evolution(cos(y), 2, 11);

     (%i3) staircase(cos(y), 1, 11, [y, 0, 1.2]);

   If your system is slow, you'll have to reduce the number of
iterations in the following examples. And if the dots appear too small
in your monitor, you might want to try a different style, such as
`['<style>,`['<points>,0.8`]]'.

   Orbits diagram for the quadratic map, with a parameter <a>.
             x(n+1) = a + x(n)^2

     (%i4) orbits(x^2+a, 0, 50, 200, [a, -2, 0.25], [style, dots]);

   To enlarge the region around the lower bifurcation near x `=' -1.25
use:
     (%i5) orbits(x^2+a, 0, 100, 400, [a,-1,-1.53], [x,-1.6,-0.8],
                  [nticks, 400], [style,dots]);

   Evolution of a two-dimensional system that leads to a fractal:

     (%i6) f: 0.6*x*(1+2*x)+0.8*y*(x-1)-y^2-0.9$

     (%i7) g: 0.1*x*(1-6*x+4*y)+0.1*y*(1+9*y)-0.4$

     (%i8) evolution2d([f,g], [x,y], [-0.5,0], 50000, [style,dots]);

   And an enlargement of a small region in that fractal:

     (%i9) evolution2d([f,g], [x,y], [-0.5,0], 300000, [x,-0.8,-0.6],
                       [y,-0.4,-0.2], [style, dots]);

   A plot of Sierpinsky's triangle, obtained with the chaos game:

     (%i9) chaosgame([[0, 0], [1, 0], [0.5, sqrt(3)/2]], [0.1, 0.1], 1/2,
                      30000, [style, dots]);

   Barnsley's fern, obtained with an Iterated Function System:

     (%i10) a1: matrix([0.85,0.04],[-0.04,0.85])$

     (%i11) a2: matrix([0.2,-0.26],[0.23,0.22])$

     (%i12) a3: matrix([-0.15,0.28],[0.26,0.24])$

     (%i13) a4: matrix([0,0],[0,0.16])$

     (%i14) p1: [0,1.6]$

     (%i15) p2: [0,1.6]$

     (%i16) p3: [0,0.44]$

     (%i17) p4: [0,0]$

     (%i18) w: [85,92,99,100]$

     (%i19) ifs(w, [a1,a2,a3,a4], [p1,p2,p3,p4], [5,0], 50000, [style,dots]);

   To create a file named _dynamics9.xpm_ with a graphical
representation of the Mandelbrot set, with 12 colors, use:

     mandelbrot([filename,"dynamics9"])$

   and the Julia set for the number (-0.55 + i 0.6) can be obtained
with:
     julia(-0.55, 0.6, [levels, 36], [center, 0, 0.6], [radius, 0.3],
           [hue, 240], [huerange, -180], [filename, "dynamics10"])$

   the graph will be saved in the file _dynamics10.xpm_ and will show
the region from -0.3 to 0.3 in the x direction, and from 0.3 to 0.9 in
the y direction. 36 colors will be used, starting with blue and ending
with yellow.

   To solve numerically the differential equation

               dx/dt = t - x^2

   With initial value x(t=0) = 1, in the interval of t from 0 to 8 and
with increments of 0.1 for t, use:

     (%i20) results: rk(t-x^2,x,1,[t,0,8,0.1])$

   the results will be saved in the list `results'.

   To solve numerically the system:

             dx/dt = 4-x^2-4*y^2     dy/dt = y^2-x^2+1

   for t between 0 and 4, and with values of -1.25 and 0.75 for x and y
at t=0:

     (%i21) sol: rk([4-x^2-4*y^2,y^2-x^2+1],[x,y],[-1.25,0.75],[t,0,4,0.02])$


File: maxima.info,  Node: ezunits,  Next: f90,  Prev: dynamics,  Up: Top

50 ezunits
**********

* Menu:

* Introduction to ezunits::
* Introduction to physical_constants::
* Functions and Variables for ezunits::


File: maxima.info,  Node: Introduction to ezunits,  Next: Introduction to physical_constants,  Prev: ezunits,  Up: ezunits

50.1 Introduction to ezunits
============================

`ezunits' is a package for working with dimensional quantities,
including some functions for dimensional analysis.  `ezunits' can carry
out arithmetic operations on dimensional quantities and unit
conversions.  The built-in units include Systeme Internationale (SI)
and US customary units, and other units can be declared.  See also
`physical_constants', a collection of physical constants.
`load(ezunits)' loads this package.  `demo(ezunits)' displays several
examples.

   An expression `a ` b' represents a dimensional quantity, with `a'
indicating a nondimensional quantity and `b' indicating the dimensional
units.  A symbol can be used as a unit without declaring it as such;
unit symbols need not have any special properties.  The quantity and
unit of an expression `a ` b' can be extracted by the `qty' and `units'
functions, respectively.

   A symbol may be declared to be a dimensional quantity, with
specified quantity or specified units or both.

   An expression `a ` b `` c' converts from unit `b' to unit `c'.
`ezunits' has built-in conversions for SI base units, SI derived units,
and some non-SI units.  Unit conversions not already known to `ezunits'
can be declared.  The unit conversions known to `ezunits' are specified
by the global variable `known_unit_conversions', which comprises
built-in and user-defined conversions.  Conversions for products,
quotients, and powers of units are derived from the set of known unit
conversions.

   As Maxima generally prefers exact numbers (integers or rationals) to
inexact (float or bigfloat), so `ezunits' preserves exact numbers when
they appear in dimensional quantities.  All built-in unit conversions
are expressed in terms of exact numbers; inexact numbers in declared
conversions are coerced to exact.

   There is no preferred system for display of units; input units are
not converted to other units unless conversion is explicitly indicated.
`ezunits' does not attempt to simplify units by prefixes (milli-,
centi-, deci-, etc) unless such conversion is explicitly indicated.

   Arithmetic operations on dimensional quantities are carried out by
conventional rules for such operations.

   * `(x ` a) * (y ` b)' is equal to `(x * y) ` (a * b)'.

   * `(x ` a) + (y ` a)' is equal to `(x + y) ` a'.

   * `(x ` a)^y' is equal to `x^y ` a^y' when `y' is nondimensional.

   `ezunits' does not require that units in a sum have the same
dimensions; such terms are not added together, and no error is reported.

   `ezunits' includes functions for elementary dimensional analysis,
namely the fundamental dimensions and fundamental units of a
dimensional quantity, and computation of dimensionless quantities and
natural units.  The functions for dimensional analysis were adapted
from similar functions in another package, written by Barton Willis.

   For the purpose of dimensional analysis, a list of fundamental
dimensions and an associated list of fundamental units are maintained;
by default the fundamental dimensions are length, mass, time, charge,
temperature, and quantity, and the fundamental units are the associated
SI units, but other fundamental dimensions and units can be declared.


File: maxima.info,  Node: Introduction to physical_constants,  Next: Functions and Variables for ezunits,  Prev: Introduction to ezunits,  Up: ezunits

50.2 Introduction to physical_constants
=======================================

`physical_constants' is a collection of physical constants, copied from
CODATA 2006 recommended values. [1] `load(physical_constants)' loads
this package, and loads `ezunits' also, if it is not already loaded.

   A physical constant is represented as a symbol which has a property
which is the constant value.  The constant value is a dimensional
quantity, as represented by `ezunits'.  The function `constvalue'
fetches the constant value; the constant value is not the ordinary
value of the symbol, so the symbols persist in evaluated expressions
until the value is fetched by `constvalue'.

   `physical_constants' includes some auxilliary information such as a
description string for each constant, an estimate of the error of its
numerical value, and a property for TeX display.  To identify physical
constants, each symbol has the `physical_constant' property;
`propvars(physical_constant)' therefore shows the list of all such
symbols.

   `physical_constants' comprises the following constants.

`%c'
     speed of light in vacuum

`%mu_0'
     magnetic constant

`%e_0'
     electric constant

`%Z_0'
     characteristic impedance of vacuum

`%G'
     Newtonian constant of gravitation

`%h'
     Planck constant

`%h_bar'
     Planck constant

`%m_P'
     Planck mass

`%T_P'
     Planck temperature

`%l_P'
     Planck length

`%t_P'
     Planck time

`%%e'
     elementary charge

`%Phi_0'
     magnetic flux quantum

`%G_0'
     conductance quantum

`%K_J'
     Josephson constant

`%R_K'
     von Klitzing constant

`%mu_B'
     Bohr magneton

`%mu_N'
     nuclear magneton

`%alpha'
     fine-structure constant

`%R_inf'
     Rydberg constant

`%a_0'
     Bohr radius

`%E_h'
     Hartree energy

`%ratio_h_me'
     quantum of circulation

`%m_e'
     electron mass

`%N_A'
     Avogadro constant

`%m_u'
     atomic mass constant

`%F'
     Faraday constant

`%R'
     molar gas constant

`%%k'
     Boltzmann constant

`%V_m'
     molar volume of ideal gas

`%n_0'
     Loschmidt constant

`%ratio_S0_R'
     Sackur-Tetrode constant (absolute entropy constant)

`%sigma'
     Stefan-Boltzmann constant

`%c_1'
     first radiation constant

`%c_1L'
     first radiation constant for spectral radiance

`%c_2'
     second radiation constant

`%b'
     Wien displacement law constant

`%b_prime'
     Wien displacement law constant

   References:

   [1] `http://physics.nist.gov/constants'

   Examples:

   The list of all symbols which have the `physical_constant' property.

     (%i1) load (physical_constants);
     (%i2) propvars (physical_constant);
     (%o2) [%c, %mu_0, %e_0, %Z_0, %G, %h, %h_bar, %m_P, %T_P, %l_P,
     %t_P, %%e, %Phi_0, %G_0, %K_J, %R_K, %mu_B, %mu_N, %alpha,
     %R_inf, %a_0, %E_h, %ratio_h_me, %m_e, %N_A, %m_u, %F, %R, %%k,
     %V_m, %n_0, %ratio_S0_R, %sigma, %c_1, %c_1L, %c_2, %b, %b_prime]

   Properties of the physical constant `%c'.

     (%i1) load (physical_constants);
     (%i2) constantp (%c);
     (%o2)                         true
     (%i3) get (%c, description);
     (%o3)               speed of light in vacuum
     (%i4) constvalue (%c);
                                           m
     (%o4)                     299792458 ` -
                                           s
     (%i5) get (%c, RSU);
     (%o5)                           0
     (%i6) tex (%c);
     $$c$$
     (%o6)                         false

   The energy equivalent of 1 pound-mass.  The symbol `%c' persists
until its value is fetched by `constvalue'.  The joules to gigajoules
conversion is not built-in, so it is declared.

     (%i1) load (physical_constants);
     (%i2) m * %c^2;
                                     2
     (%o2)                         %c  m
     (%i3) %, m = 1 ` lbm;
                                   2
     (%o3)                       %c  ` lbm
     (%i4) constvalue (%);
                                                 2
                                            lbm m
     (%o4)              89875517873681764 ` ------
                                               2
                                              s
     (%i5) E : % `` J;
                          366838848464007200
     (%o5)                ------------------ ` J
                                  9
     (%i6) declare_unit_conversion (1 ` GJ = 10^9 ` J);
     (%o6)                         done
     (%i7) E `` GJ;
                           458548560580009
     (%o7)                 --------------- ` GJ
                              11250000
     (%i8) float (%);
     (%o8)              4.0759872051556356e+7 ` GJ


File: maxima.info,  Node: Functions and Variables for ezunits,  Prev: Introduction to physical_constants,  Up: ezunits

50.3 Functions and Variables for ezunits
========================================

 -- Operator: `
     The dimensional quantity operator.  An expression `a ` b'
     represents a dimensional quantity, with `a' indicating a
     nondimensional quantity and `b' indicating the dimensional units.
     A symbol can be used as a unit without declaring it as such; unit
     symbols need not have any special properties.  The quantity and
     unit of an expression `a ` b' can be extracted by the `qty' and
     `units' functions, respectively.

     Arithmetic operations on dimensional quantities are carried out by
     conventional rules for such operations.

        * `(x ` a) * (y ` b)' is equal to `(x * y) ` (a * b)'.

        * `(x ` a) + (y ` a)' is equal to `(x + y) ` a'.

        * `(x ` a)^y' is equal to `x^y ` a^y' when `y' is
          nondimensional.

     `ezunits' does not require that units in a sum have the same
     dimensions; such terms are not added together, and no error is
     reported.

     `load(ezunits)' enables this operator.

     Examples:

     SI (Systeme Internationale) units.

          (%i1) foo : 10 ` m;
          (%o1)                        10 ` m
          (%i2) qty (foo);
          (%o2)                          10
          (%i3) units (foo);
          (%o3)                           m
          (%i4) dimensions (foo);
          (%o4)                        length

     "Customary" units.

          (%i1) bar : x ` acre;
          (%o1)                       x ` acre
          (%i2) dimensions (bar);
                                             2
          (%o2)                        length
          (%i3) fundamental_units (bar);
                                          2
          (%o3)                          m

     Units ad hoc.

          (%i1) load (ezunits);
          (%i2) baz : 3 ` sheep + 8 ` goat + 1 ` horse;
          (%o2)           8 ` goat + 3 ` sheep + 1 ` horse
          (%i3) subst ([sheep = 3*goat, horse = 10*goat], baz);
          (%o3)                       27 ` goat
          (%i4) baz2 : 1000`gallon/fortnight;
                                          gallon
          (%o4)                   1000 ` ---------
                                         fortnight
          (%i5) subst (fortnight = 14*d, baz2);
                                    500   gallon
          (%o5)                     --- ` ------
                                     7      d

     Arithmetic operations on dimensional quantities.

          (%i1) 100 ` kg + 200 ` kg;
          (%o1)                       300 ` kg
          (%i2) 100 ` m^3 - 100 ` m^3;
                                            3
          (%o2)                        0 ` m
          (%i3) (10 ` kg) * (17 ` m/s^2);
                                           kg m
          (%o3)                      170 ` ----
                                             2
                                            s
          (%i4) (x ` m) / (y ` s);
                                        x   m
          (%o4)                         - ` -
                                        y   s
          (%i5) (a ` m)^2;
                                        2    2
          (%o5)                        a  ` m


 -- Operator: "
     The unit conversion operator.  An expression `a ` b `` c' converts
     from unit `b' to unit `c'.  `ezunits' has built-in conversions for
     SI base units, SI derived units, and some non-SI units.  Unit
     conversions not already known to `ezunits' can be declared.  The
     unit conversions known to `ezunits' are specified by the global
     variable `known_unit_conversions', which comprises built-in and
     user-defined conversions.  Conversions for products, quotients,
     and powers of units are derived from the set of known unit
     conversions.

     There is no preferred system for display of units; input units are
     not converted to other units unless conversion is explicitly
     indicated.  `ezunits' does not attempt to simplify units by
     prefixes (milli-, centi-, deci-, etc) unless such conversion is
     explicitly indicated.

     `load(ezunits)' enables this operator.

     Examples:

     The set of known unit conversions.

          (%i1) load (ezunits)$
          (%i2) display2d : false$
          (%i3) known_unit_conversions;
          (%o3) {acre = 4840*yd^2,Btu = 1055*J,cfm = ft^3/min,cm = m/100,
                 d = 24*h,ft = 381*m/1250,g = kg/1000,gallon = 757*l/200,
                 h = 60*min,Hz = 1/s,in = ft/12,km = 1000*m,l = m^3/1000,
                 lbf = 32*ft*lbm/s^2,lbm = 200*kg/441,mi = 5280*ft,
                 micron = m/1000000,min = 60*s,mm = m/1000,oz = lbm/16,
                 Ohm = s*J/C^2,psi = lbf/in^2,Pa = N/m^2,Wb = J/A,
                 yd = 3*ft,C = s*A,F = C^2/J,H = J/A^2,J = m*N,
                 N = kg*m/s^2,R = 5*K/9,S = 1/Ohm,T = J/(m^2*A),V = J/C,
                 W = J/s}

     Elementary unit conversions.

          (%i1) load (ezunits)$
          (%i2) 1 ` ft `` m;
                                      381
          (%o2)                       ---- ` m
                                      1250
          (%i3) %, numer;
          (%o3)                      0.3048 ` m
          (%i4) 1 ` kg `` lbm;
                                      441
          (%o4)                       --- ` lbm
                                      200
          (%i5) %, numer;
          (%o5)                      2.205 ` lbm
          (%i6) 1 ` W `` Btu/h;
                                      720   Btu
          (%o6)                       --- ` ---
                                      211    h
          (%i7) %, numer;
                                                   Btu
          (%o7)                3.412322274881517 ` ---
                                                    h
          (%i8) 100 ` degC `` degF;
          (%o8)                      212 ` degF
          (%i9) -40 ` degF `` degC;
          (%o9)                     (- 40) ` degC
          (%i10) 1 ` acre*ft `` m^3;
                                  60228605349    3
          (%o10)                  ----------- ` m
                                   48828125
          (%i11) %, numer;
                                                    3
          (%o11)                1233.48183754752 ` m

     Coercing quantities in feet and meters to one or the other.

          (%i1) load (ezunits)$
          (%i2) 100 ` m + 100 ` ft;
          (%o2)                  100 ` m + 100 ` ft
          (%i3) (100 ` m + 100 ` ft) `` ft;
                                     163100
          (%o3)                      ------ ` ft
                                      381
          (%i4) %, numer;
          (%o4)                428.0839895013123 ` ft
          (%i5) (100 ` m + 100 ` ft) `` m;
                                      3262
          (%o5)                       ---- ` m
                                       25
          (%i6) %, numer;
          (%o6)                      130.48 ` m

     Dimensional analysis to find fundamental dimensions and
     fundamental units.

          (%i1) load (ezunits)$
          (%i2) foo : 1 ` acre * ft;
          (%o2)                      1 ` acre ft
          (%i3) dimensions (foo);
                                             3
          (%o3)                        length
          (%i4) fundamental_units (foo);
                                          3
          (%o4)                          m
          (%i5) foo `` m^3;
                                  60228605349    3
          (%o5)                   ----------- ` m
                                   48828125
          (%i6) %, numer;
                                                    3
          (%o6)                 1233.48183754752 ` m

     Declared unit conversions.

          (%i1) load (ezunits)$
          (%i2) declare_unit_conversion (MMBtu = 10^6*Btu, kW = 1000*W);
          (%o2)                         done
          (%i3) declare_unit_conversion (kWh = kW*h, MWh = 1000*kWh, bell = 1800*s);
          (%o3)                         done
          (%i4) 1 ` kW*s `` MWh;
                                       1
          (%o4)                     ------- ` MWh
                                    3600000
          (%i5) 1 ` kW/m^2 `` MMBtu/bell/ft^2;
                                 1306449      MMBtu
          (%o5)                 ---------- ` --------
                                8242187500          2
                                             bell ft


 -- Function: constvalue (<x>)
 -- Function: declare_constvalue (<a>, <x>)
     Returns the declared constant value of a symbol, or value of an
     expression with declared constant values substituted for symbols.

     Constant values are declared by `declare_constvalue'.  Note that
     constant values as recognized by `constvalue' are separate from
     values declared by `numerval' and recognized by `constantp'.

     The `physical_units' package declares constant values for a number
     of physical constants.

     `load(ezunits)' loads this function.

     Example:

     Constant value of a physical constant.

          (%i1) load (physical_constants)$
          (%i2) constvalue (%G);
                                               3
                                              m
          (%o2)                    6.67428 ` -----
                                                 2
                                             kg s
          (%i3) get ('%G, 'description);
          (%o3)           Newtonian constant of gravitation

     Declaring a new constant.

          (%i1) load (ezunits)$
          (%i2) declare_constvalue (FOO, 100 ` lbm / acre);
                                           lbm
          (%o2)                      100 ` ----
                                           acre
          (%i3) FOO * (50 ` acre);
          (%o3)                     50 FOO ` acre
          (%i4) constvalue (%);
          (%o4)                      5000 ` lbm


 -- Function: units (<x>)
 -- Function: declare_units (<a>, <u>)
     Returns the units of a dimensional quantity <x>, or returns 1 if
     <x> is nondimensional.

     <x> may be a literal dimensional expression `a ` b', a symbol with
     declared units, or an expression containing either or both of
     those.

     `load(ezunits)' loads these functions.

     `declare_units' declares that `units(<a>)' should return <u>,
     where <u> is an expression.

     Examples:

     `units' applied to literal dimensional expressions.

          (%i1) load (ezunits)$
          (%i2) foo : 100 ` kg;
          (%o2)                              100 ` kg
          (%i3) bar : x ` m/s;
                                                   m
          (%o3)                                x ` -
                                                   s
          (%i4) units (foo);
          (%o4)                                 kg
          (%i5) units (bar);
                                                 m
          (%o5)                                  -
                                                 s
          (%i6) units (foo * bar);
                                               kg m
          (%o6)                                ----
                                                s
          (%i7) units (foo / bar);
                                               kg s
          (%o7)                                ----
                                                m
          (%i8) units (foo^2);
                                                  2
          (%o8)                                 kg

     `units' applied to symbols with declared units.

          (%i1) load (ezunits)$
          (%i2) linenum:0;
          (%o0)                                  0
          (%i1) units (aa);
          (%o1)                                  1
          (%i2) declare_units (aa, J);
          (%o2)                                  J
          (%i3) units (aa);
          (%o3)                                  J
          (%i4) units (aa^2);
                                                 2
          (%o4)                                 J
          (%i5) foo : 100 ` kg;
          (%o5)                              100 ` kg
          (%i6) units (aa * foo);
          (%o6)                                kg J


 -- Function: qty (<x>)
 -- Function: declare_qty (<a>, <x>)
     `qty' returns the nondimensional part of a dimensional quantity
     <x>, or returns <x> if <x> is nondimensional.  <x> may be a
     literal dimensional expression `a ` b', a symbol with declared
     quantity, or an expression containing either or both of those.

     `declare_qty' declares that `qty(<a>)' should return <x>, where
     <x> is a nondimensional quantity.

     `load(ezunits)' loads these functions.

     Examples:

     `qty' applied to literal dimensional expressions.

          (%i1) load (ezunits)$
          (%i2) foo : 100 ` kg;
          (%o2)                       100 ` kg
          (%i3) qty (foo);
          (%o3)                          100
          (%i4) bar : v ` m/s;
                                            m
          (%o4)                         v ` -
                                            s
          (%i5) foo * bar;
                                            kg m
          (%o5)                     100 v ` ----
                                             s
          (%i6) qty (foo * bar);
          (%o6)                         100 v

     `qty' applied to symbols with declared quantity.

          (%i1) load (ezunits)$
          (%i2) declare_qty (aa, xx);
          (%o2)                          xx
          (%i3) qty (aa);
          (%o3)                          xx
          (%i4) qty (aa^2);
                                           2
          (%o4)                          xx
          (%i5) foo : 100 ` kg;
          (%o5)                       100 ` kg
          (%i6) qty (aa * foo);
          (%o6)                        100 xx


 -- Function: unitp (<x>)
     Returns `true' if <x> is a literal dimensional expression, a
     symbol declared dimensional, or an expression in which the main
     operator is declared dimensional.  `unitp' returns `false'
     otherwise.

     `load(ezunits)' loads this function.

     Examples:

     `unitp' applied to a literal dimensional expression.

          (%i1) load (ezunits)$
          (%i2) unitp (100 ` kg);
          (%o2)                         true

     `unitp' applied to a symbol declared dimensional.

          (%i1) load (ezunits)$
          (%i2) unitp (foo);
          (%o2)                         false
          (%i3) declare (foo, dimensional);
          (%o3)                         done
          (%i4) unitp (foo);
          (%o4)                         true

     `unitp' applied to an expression in which the main operator is
     declared dimensional.

          (%i1) load (ezunits)$
          (%i2) unitp (bar (x, y, z));
          (%o2)                         false
          (%i3) declare (bar, dimensional);
          (%o3)                         done
          (%i4) unitp (bar (x, y, z));
          (%o4)                         true


 -- Function: declare_unit_conversion (<u> = <v>, ...)
     Appends equations <u> = <v>, ... to the list of unit conversions
     known to the unit conversion operator ```'.  Each equation is a
     equality of multiplicative terms, in which any variables are units,
     or literal dimensional expressions.

     At present, it is necessary to express conversions such that the
     left-hand side of each equation is a simple unit (not a
     multiplicative expression) or a literal dimensional expression
     with the quantity equal to 1 and the unit being a simple unit.  It
     is foreseen that this limitation will be relaxed in future
     versions.

     `known_unit_conversions' is the list of known unit conversions.

     `load(ezunits)' loads this function.

     Examples:

     Unit conversions expressed by equations of multiplicative terms.

          (%i1) load (ezunits)$
          (%i2) declare_unit_conversion (nautical_mile = 1852 * m, fortnight = 14 * d);
          (%o2)                         done
          (%i3) 100 ` nautical_mile / fortnight `` m/s;
                                      463    m
          (%o3)                       ---- ` -
                                      3024   s

     Unit conversions expressed by equations of literal dimensional
     expressions.



 -- Function: declare_dimensions (<d_1>, <d_2>, <d_3>, ...)
 -- Function: remove_dimensions (<d_1>, <d_2>, <d_3>, ...)

 -- Function: declare_fundamental_dimensions (<d_1>, <d_2>, <d_3>, ...)
 -- Function: remove_fundamental_dimensions (<d_1>, <d_2>, <d_3>, ...)

 -- Function: declare_fundamental_units (<u_1>, <u_2>, <u_3>, ...)
 -- Function: remove_fundamental_units (<u_1>, <u_2>, <u_3>, ...)

 -- Function: dimensions (<x>)
 -- Function: dimensions_as_list (<x>)
     `dimensions' returns the dimensions of the dimensional quantity <x>
     as an expression comprising products and powers of base dimensions.

     `dimensions_as_list' returns the dimensions of the dimensional
     quantity <x> as a list, in which each element is an integer which
     indicates the power of the corresponding base dimension in the
     dimensions of <x>.

     `load(ezunits)' loads these functions.

     Examples:

          (%i1) load (ezunits)$
          (%i2) dimensions (1000 ` kg*m^2/s^3);
                                          2
                                    length  mass
          (%o2)                     ------------
                                           3
                                       time
          (%i3) declare_units (foo, acre*ft/h);
                                       acre ft
          (%o3)                        -------
                                          h
          (%i4) dimensions (foo);
                                             3
                                       length
          (%o4)                        -------
                                        time

          (%i1) load (ezunits)$
          (%i2) fundamental_dimensions;
          (%o2)  [length, mass, time, charge, temperature, quantity]
          (%i3) dimensions_as_list (1000 ` kg*m^2/s^3);
          (%o3)                 [2, 1, - 3, 0, 0, 0]
          (%i4) declare_units (foo, acre*ft/h);
                                       acre ft
          (%o4)                        -------
                                          h
          (%i5) dimensions_as_list (foo);
          (%o5)                 [3, 0, - 1, 0, 0, 0]


 -- Function: fundamental_units (<x>)

 -- Function: dimensionless (<x>)

 -- Function: natural_unit (<x>)


File: maxima.info,  Node: f90,  Next: ggf,  Prev: ezunits,  Up: Top

51 f90
******

* Menu:

* Functions and Variables for f90::


File: maxima.info,  Node: Functions and Variables for f90,  Prev: f90,  Up: f90

51.1 Functions and Variables for f90
====================================

 -- Function: f90 (<expr>)
     The `f90' command is an update to the original maxima `fortran'
     command. The primary difference is the way long lines are broken.

     In the next example, notice how the `fortran' command breaks lines
     within symbols. The `f90' command never breaks within a symbol.


     (%i1) load("f90")$

     (%i2) expr:expand((xxx+yyy+7)^4);
              4            3         3        2    2
     (%o2) yyy  + 4 xxx yyy  + 28 yyy  + 6 xxx  yyy
                  2          2        3             2
      + 84 xxx yyy  + 294 yyy  + 4 xxx  yyy + 84 xxx  yyy
                                    4         3          2
      + 588 xxx yyy + 1372 yyy + xxx  + 28 xxx  + 294 xxx
      + 1372 xxx + 2401
     (%i3) fortran(expr);
           yyy**4+4*xxx*yyy**3+28*yyy**3+6*xxx**2*yyy**2+84*xxx*yyy**2+294*yy
          1   y**2+4*xxx**3*yyy+84*xxx**2*yyy+588*xxx*yyy+1372*yyy+xxx**4+28*
          2   xxx**3+294*xxx**2+1372*xxx+2401
     (%o3)                       done
     (%i4) f90(expr);
     yyy**4+4*xxx*yyy**3+28*yyy**3+6*xxx**2*yyy**2+84*xxx*yyy**2+294* &
          yyy**2+4*xxx**3*yyy+84*xxx**2*yyy+588*xxx*yyy+1372*yyy+xxx** &
          4+28*xxx**3+294*xxx**2+1372*xxx+2401
     (%o4)                       done

     The `f90' implementation was done as a quick hack. It is not a
     necessarily a good example upon which to base other language
     translations.

     To use this function write first `load("f90")'.



File: maxima.info,  Node: ggf,  Next: graphs,  Prev: f90,  Up: Top

52 ggf
******

* Menu:

* Functions and Variables for ggf::


File: maxima.info,  Node: Functions and Variables for ggf,  Prev: ggf,  Up: ggf

52.1 Functions and Variables for ggf
====================================

 -- Option variable: GGFINFINITY
     Default value: 3

     This is an option variable for function `ggf'.

     When computing the continued fraction of the generating function,
     a partial quotient having a degree (strictly) greater than
     <GGFINFINITY> will be discarded and the current convergent will be
     considered as the exact value of the generating function; most
     often the degree of all partial quotients will be 0 or 1; if you
     use a greater value, then you should give enough terms in order to
     make the computation accurate enough.

     See also `ggf'.


 -- Option variable: GGFCFMAX
     Default value: 3

     This is an option variable for function `ggf'.

     When computing the continued fraction of the generating function,
     if no good result has been found (see the <GGFINFINITY> flag)
     after having computed <GGFCFMAX> partial quotients, the generating
     function will be considered as not being a fraction of two
     polynomials and the function will exit. Put freely a greater value
     for more complicated generating functions.

     See also `ggf'.


 -- Function: ggf (<l>)
     Compute the generating function (if it is a fraction of two
     polynomials) of a sequence, its first terms being given. <l> is a
     list of numbers.

     The solution is returned as a fraction of two polynomials.  If no
     solution has been found, it returns with `done'.

     This function is controlled by global variables <GGFINFINITY> and
     <GGFCFMAX>. See also <GGFINFINITY> and <GGFCFMAX>.

     To use this function write first `load("ggf")'.



File: maxima.info,  Node: graphs,  Next: grobner,  Prev: ggf,  Up: Top

53 graphs
*********

* Menu:

* Introduction to graphs::
* Functions and Variables for graphs::


File: maxima.info,  Node: Introduction to graphs,  Next: Functions and Variables for graphs,  Prev: graphs,  Up: graphs

53.1 Introduction to graphs
===========================

The `graphs' package provides graph and digraph data structure for
Maxima. Graphs and digraphs are simple (have no multiple edges nor
loops), although digraphs can have a directed edge from <u> to <v> and
a directed edge from <v> to <u>.

   Internally graphs are represented by adjacency lists and implemented
as a lisp structures. Vertices are identified by their ids (an id is an
integer). Edges/arcs are represented by lists of length 2. Labels can be
assigned to vertices of graphs/digraphs and weights can be assigned to
edges/arcs of graphs/digraphs.

   There is a `draw_graph' function for drawing graphs. Graphs are
drawn using a force based vertex positioning algorithm. `draw_graph'
can also use graphviz programs available from
`http://www.graphviz.org'. `draw_graph' is based on the maxima `draw'
package.

   To use the `graphs' package, first load it with `load(graphs)'.


File: maxima.info,  Node: Functions and Variables for graphs,  Prev: Introduction to graphs,  Up: graphs

53.2 Functions and Variables for graphs
=======================================

53.2.1 Building graphs
----------------------

 -- Function: create_graph (<v_list>, <e_list>)
 -- Function: create_graph (<n>, <e_list>)
 -- Function: create_graph (<v_list>, <e_list>, <directed>)
     Creates a new graph on the set of vertices <v_list> and with edges
     <e_list>.

     <v_list> is a list of vertices (`[v1, v2,..., vn]') or a list of
     vertices together with vertex labels (`[[v1,l1], [v2,l2],...,
     [vn,ln]]').

     <n> is the number of vertices. Vertices will be identified by
     integers from 0 to n-1.

     <e_list> is a list of edges (`[e1, e2,..., em]') or a list of
     edges together with edge-weights (`[[e1, w1], ..., [em, wm]]').

     If <directed> is not `false', a directed graph will be returned.

     Example 1: create a cycle on 3 vertices:
          (%i1) load (graphs)$
          (%i2) g : create_graph([1,2,3], [[1,2], [2,3], [1,3]])$
          (%i3) print_graph(g)$
          Graph on 3 vertices with 3 edges.
          Adjacencies:
            3 :  1  2
            2 :  3  1
            1 :  3  2

     Example 2: create a cycle on 3 vertices with edge weights:
          (%i1) load (graphs)$
          (%i2) g : create_graph([1,2,3], [[[1,2], 1.0], [[2,3], 2.0],
                                    [[1,3], 3.0]])$
          (%i3) print_graph(g)$
          Graph on 3 vertices with 3 edges.
          Adjacencies:
            3 :  1  2
            2 :  3  1
            1 :  3  2

     Example 3: create a directed graph:
          (%i1) load (graphs)$
          (%i2) d : create_graph(
                  [1,2,3,4],
                  [
                   [1,3], [1,4],
                   [2,3], [2,4]
                  ],
                  'directed = true)$
          (%i3) print_graph(d)$
          Digraph on 4 vertices with 4 arcs.
          Adjacencies:
            4 :
            3 :
            2 :  4  3
            1 :  4  3

 -- Function: copy_graph (<g>)
     Returns a copy of the graph <g>.

 -- Function: circulant_graph (<n>, <d>)
     Returns the circulant graph with parameters <n> and <d>.

     Example:
          (%i1) load (graphs)$
          (%i2) g : circulant_graph(10, [1,3])$
          (%i3) print_graph(g)$
          Graph on 10 vertices with 20 edges.
          Adjacencies:
            9 :  2  6  0  8
            8 :  1  5  9  7
            7 :  0  4  8  6
            6 :  9  3  7  5
            5 :  8  2  6  4
            4 :  7  1  5  3
            3 :  6  0  4  2
            2 :  9  5  3  1
            1 :  8  4  2  0
            0 :  7  3  9  1

 -- Function: clebsch_graph ()
     Returns the Clebsch graph.

 -- Function: complement_graph (<g>)
     Returns the complement of the graph <g>.

 -- Function: complete_bipartite_graph (<n>, <m>)
     Returns the complete bipartite graph on <n+m> vertices.

 -- Function: complete_graph (<n>)
     Returns the complete graph on <n> vertices.

 -- Function: cycle_digraph (<n>)
     Returns the directed cycle on <n> vertices.

 -- Function: cycle_graph (<n>)
     Returns the cycle on <n> vertices.

 -- Function: cube_graph (<n>)
     Returns the <n>-dimensional cube.

 -- Function: dodecahedron_graph ()
     Returns the dodecahedron graph.

 -- Function: empty_graph (<n>)
     Returns the empty graph on <n> vertices.

 -- Function: flower_snark (<n>)
     Returns the flower graph on <4n> vertices.

     Example:
          (%i1) load (graphs)$
          (%i2) f5 : flower_snark(5)$
          (%i3) chromatic_index(f5);
          (%o3)                           4

 -- Function: from_adjacency_matrix (<A>)
     Returns the graph represented by its adjacency matrix <A>.

 -- Function: frucht_graph ()
     Returns the Frucht graph.

 -- Function: graph_product (<g1>, <g1>)
     Returns the direct product of graphs <g1> and <g2>.

     Example:
          (%i1) load (graphs)$
          (%i2) grid : graph_product(path_graph(3), path_graph(4))$
          (%i3) draw_graph(grid)$

 -- Function: graph_union (<g1>, <g1>)
     Returns the union (sum) of graphs <g1> and <g2>.

 -- Function: grid_graph (<n>, <m>)
     Returns the <n x m> grid.

 -- Function: grotzch_graph ()
     Returns the Grotzch graph.

 -- Function: heawood_graph ()
     Returns the Heawood graph.

 -- Function: icosahedron_graph ()
     Returns the icosahedron graph.

 -- Function: induced_subgraph (<V>, <g>)
     Returns the graph induced on the subset <V> of vertices of the
     graph <g>.

     Example:
          (%i1) load (graphs)$
          (%i2) p : petersen_graph()$
          (%i3) V : [0,1,2,3,4]$
          (%i4) g : induced_subgraph(V, p)$
          (%i5) print_graph(g)$
          Graph on 5 vertices with 5 edges.
          Adjacencies:
            4 :  3  0
            3 :  2  4
            2 :  1  3
            1 :  0  2
            0 :  1  4

 -- Function: line_graph (<g>)
     Returns the line graph of the graph <g>.

 -- Function: make_graph (<vrt>, <f>)
 -- Function: make_graph (<vrt>, <f>, <oriented>)
     Creates a graph using a predicate function <f>.

     <vrt> is a list/set of vertices or an integer. If <vrt> is an
     integer, then vertices of the graph will be integers from 1 to
     <vrt>.

     <f> is a predicate function. Two vertices <a> and <b> will be
     connected if `f(a,b)=true'.

     If <directed> is not <false>, then the graph will be directed.

     Example 1:
          (%i1) load(graphs)$
          (%i2) g : make_graph(powerset({1,2,3,4,5}, 2), disjointp)$
          (%i3) is_isomorphic(g, petersen_graph());
          (%o3)                         true
          (%i4) get_vertex_label(1, g);
          (%o4)                        {1, 2}

     Example 2:
          (%i1) load(graphs)$
          (%i2) f(i, j) := is (mod(j, i)=0)$
          (%i3) g : make_graph(20, f, directed=true)$
          (%i4) out_neighbors(4, g);
          (%o4)                    [8, 12, 16, 20]
          (%i5) in_neighbors(18, g);
          (%o5)                    [1, 2, 3, 6, 9]

 -- Function: mycielski_graph (<g>)
     Returns the mycielskian graph of the graph <g>.

 -- Function: new_graph ()
     Returns the graph with no vertices and no edges.

 -- Function: path_digraph (<n>)
     Returns the directed path on <n> vertices.

 -- Function: path_graph (<n>)
     Returns the path on <n> vertices.

 -- Function: petersen_graph ()
 -- Function: petersen_graph (<n>, <d>)
     Returns the petersen graph <P_{n,d}>. The default values for <n>
     and <d> are `n=5' and `d=2'.

 -- Function: random_bipartite_graph (<a>, <b>, <p>)
     Returns a random bipartite graph on `a+b' vertices. Each edge is
     present with probability <p>.

 -- Function: random_digraph (<n>, <p>)
     Returns a random directed graph on <n> vertices. Each arc is
     present with probability <p>.

 -- Function: random_regular_graph (<n>)
 -- Function: random_regular_graph (<n>, <d>)
     Returns a random <d>-regular graph on <n> vertices. The default
     value for <d> is `d=3'.

 -- Function: random_graph (<n>, <p>)
     Returns a random graph on <n> vertices. Each edge is present with
     probability <p>.

 -- Function: random_graph1 (<n>, <m>)
     Returns a random graph on <n> vertices and random <m> edges.

 -- Function: random_network (<n>, <p>, <w>)
     Returns a random network on <n> vertices. Each arc is present with
     probability <p> and has a weight in the range `[0,w]'. The
     function returns a list `[network, source, sink]'.

     Example:
          (%i1) load (graphs)$
          (%i2) [net, s, t] : random_network(50, 0.2, 10.0);
          (%o2)                   [DIGRAPH, 50, 51]
          (%i3) max_flow(net, s, t)$
          (%i4) first(%);
          (%o4)                   27.65981397932507

 -- Function: random_tournament (<n>)
     Returns a random tournament on <n> vertices.

 -- Function: random_tree (<n>)
     Returns a random tree on <n> vertices.

 -- Function: tutte_graph ()
     Returns the Tutte graph.

 -- Function: underlying_graph (<g>)
     Returns the underlying graph of the directed graph <g>.

 -- Function: wheel_graph (<n>)
     Returns the wheel graph on <n+1> vertices.

53.2.2 Graph properties
-----------------------

 -- Function: adjacency_matrix (<gr>)
     Returns the adjacency matrix of the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) c5 : cycle_graph(4)$
          (%i3) adjacency_matrix(c5);
                                   [ 0  1  0  1 ]
                                   [            ]
                                   [ 1  0  1  0 ]
          (%o3)                    [            ]
                                   [ 0  1  0  1 ]
                                   [            ]
                                   [ 1  0  1  0 ]

 -- Function: average_degree (<gr>)
     Returns the average degree of vertices in the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) average_degree(grotzch_graph());
                                         40
          (%o2)                          --
                                         11

 -- Function: biconected_components (<gr>)
     Returns the (vertex sets of) 2-connected components of the graph
     <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) g : create_graph(
                      [1,2,3,4,5,6,7],
                      [
                       [1,2],[2,3],[2,4],[3,4],
                       [4,5],[5,6],[4,6],[6,7]
                      ])$
          (%i3) biconnected_components(g);
          (%o3)        [[6, 7], [4, 5, 6], [1, 2], [2, 3, 4]]


 -- Function: bipartition (<gr>)
     Returns a bipartition of the vertices of the graph <gr> or an empty
     list if <gr> is not bipartite.

     Example:

          (%i1) load (graphs)$
          (%i2) h : heawood_graph()$
          (%i3) [A,B]:bipartition(h);
          (%o3)  [[8, 12, 6, 10, 0, 2, 4], [13, 5, 11, 7, 9, 1, 3]]
          (%i4) draw_graph(h, show_vertices=A, program=circular)$

 -- Function: chromatic_index (<gr>)
     Returns the chromatic index of the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) p : petersen_graph()$
          (%i3) chromatic_index(p);
          (%o3)                           4

 -- Function: chromatic_number (<gr>)
     Returns the chromatic number of the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) chromatic_number(cycle_graph(5));
          (%o2)                           3
          (%i3) chromatic_number(cycle_graph(6));
          (%o3)                           2

 -- Function: clear_edge_weight (<e>, <gr>)
     Removes the weight of the edge  <e> in the graph <gr>.

     Example:

          (%i1) load (graphs)$
          (%i2) g : create_graph(3, [[[0,1], 1.5], [[1,2], 1.3]])$
          (%i3) get_edge_weight([0,1], g);
          (%o3)                          1.5
          (%i4) clear_edge_weight([0,1], g)$
          (%i5) get_edge_weight([0,1], g);
          (%o5)                           1

 -- Function: clear_vertex_label (<v>, <gr>)
     Removes the label of the vertex <v> in the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) g : create_graph([[0,"Zero"], [1, "One"]], [[0,1]])$
          (%i3) get_vertex_label(0, g);
          (%o3)                         Zero
          (%i4) clear_vertex_label(0, g);
          (%o4)                         done
          (%i5) get_vertex_label(0, g);
          (%o5)                         false

 -- Function: connected_components (<gr>)
     Returns the (vertex sets of) connected components of the graph
     <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) g: graph_union(cycle_graph(5), path_graph(4))$
          (%i3) connected_components(g);
          (%o3)            [[1, 2, 3, 4, 0], [8, 7, 6, 5]]

 -- Function: diameter (<gr>)
     Returns the diameter of the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) diameter(dodecahedron_graph());
          (%o2)                           5

 -- Function: edge_coloring (<gr>)
     Returns an optimal coloring of the edges of the graph <gr>.

     The function returns the chromatic index and a list representing
     the coloring of the edges of <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) p : petersen_graph()$
          (%i3) [ch_index, col] : edge_coloring(p);
          (%o3) [4, [[[0, 5], 3], [[5, 7], 1], [[0, 1], 1], [[1, 6], 2],
          [[6, 8], 1], [[1, 2], 3], [[2, 7], 4], [[7, 9], 2], [[2, 3], 2],
          [[3, 8], 3], [[5, 8], 2], [[3, 4], 1], [[4, 9], 4], [[6, 9], 3],
          [[0, 4], 2]]]
          (%i4) assoc([0,1], col);
          (%o4)                           1
          (%i5) assoc([0,5], col);
          (%o5)                           3

 -- Function: degree_sequence (<gr>)
     Returns the list of vertex degrees of the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) degree_sequence(random_graph(10, 0.4));
          (%o2)            [2, 2, 2, 2, 2, 2, 3, 3, 3, 3]

 -- Function: edge_connectivity (<gr>)
     Returns the edge-connectivity of a connected graph <gr>.

 -- Function: edges (<gr>)
     Returns the list of edges (arcs) in a (directed) graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) edges(complete_graph(4));
          (%o2)   [[2, 3], [1, 3], [1, 2], [0, 3], [0, 2], [0, 1]]

 -- Function: get_edge_weight (<e>, <gr>)
 -- Function: get_edge_weight (<e>, <gr>, <ifnot>)
     Returns the weight of the edge <e> in the graph <gr>.

     If there is no weight assigned to the edge, the function returns
     1. If the edge is not present in the graph, the function signals
     an error or returns the optional argument <ifnot>.

     Example:
          (%i1) load (graphs)$
          (%i2) c5 : cycle_graph(5)$
          (%i3) get_edge_weight([1,2], c5);
          (%o3)                           1
          (%i4) set_edge_weight([1,2], 2.0, c5);
          (%o4)                         done
          (%i5) get_edge_weight([1,2], c5);
          (%o5)                          2.0

 -- Function: get_vertex_label (<v>, <gr>)
     Returns the label of the vertex <v> in the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) g : create_graph([[0,"Zero"], [1, "One"]], [[0,1]])$
          (%i3) get_vertex_label(0, g);
          (%o3)                         Zero

 -- Function: graph_charpoly (<gr>, <x>)
     Returns the characteristic polynomial (in variable <x>) of the
     graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) p : petersen_graph()$
          (%i3) graph_charpoly(p, x), factor;
                                             5        4
          (%o3)               (x - 3) (x - 1)  (x + 2)

 -- Function: graph_center (<gr>)
     Returns the center of the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) g : grid_graph(5,5)$
          (%i3) graph_center(g);
          (%o3)                         [12]

 -- Function: graph_eigenvalues (<gr>)
     Returns the eigenvalues of the graph <gr>. The function returns
     eigenvalues in the same format as maxima `eigenvalue' function.

     Example:
          (%i1) load (graphs)$
          (%i2) p : petersen_graph()$
          (%i3) graph_eigenvalues(p);
          (%o3)               [[3, - 2, 1], [1, 4, 5]]

 -- Function: graph_periphery (<gr>)
     Returns the periphery of the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) g : grid_graph(5,5)$
          (%i3) graph_periphery(g);
          (%o3)                    [24, 20, 4, 0]

 -- Function: graph_size (<gr>)
     Returns the number of vertices in the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) p : petersen_graph()$
          (%i3) graph_size(p);
          (%o3)                          10

 -- Function: graph_order (<gr>)
     Returns the number of edges in the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) p : petersen_graph()$
          (%i3) graph_order(p);
          (%o3)                          15

 -- Function: girth (<gr>)
     Returns the length of the shortest cycle in <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) g : heawood_graph()$
          (%i3) girth(g);
          (%o3)                           6

 -- Function: hamilton_cycle (<gr>)
     Returns the Hamilton cycle of the graph <gr> or an empty list if
     <gr> is not hamiltonian.

     Example:
          (%i1) load (graphs)$
          (%i2) c : cube_graph(3)$
          (%i3) hc : hamilton_cycle(c);
          (%o3)              [7, 3, 2, 6, 4, 0, 1, 5, 7]
          (%i4) draw_graph(c, show_edges=vertices_to_cycle(hc))$

 -- Function: hamilton_path (<gr>)
     Returns the Hamilton path of the graph <gr> or an empty list if
     <gr> does not have a Hamilton path.

     Example:
          (%i1) load (graphs)$
          (%i2) p : petersen_graph()$
          (%i3) hp : hamilton_path(p);
          (%o3)            [0, 5, 7, 2, 1, 6, 8, 3, 4, 9]
          (%i4) draw_graph(p, show_edges=vertices_to_path(hp))$

 -- Function: isomorphism (<gr1>, <gr2>)
     Returns a an isomorphism between graphs/digraphs <gr1> and <gr2>.
     If <gr1> and <gr2> are not isomorphic, it returns an empty list.

     Example:
          (%i1) load (graphs)$
          (%i2) clk5:complement_graph(line_graph(complete_graph(5)))$
          (%i3) isomorphism(clk5, petersen_graph());
          (%o3) [9 -> 0, 2 -> 1, 6 -> 2, 5 -> 3, 0 -> 4, 1 -> 5, 3 -> 6,
                                                    4 -> 7, 7 -> 8, 8 -> 9]

 -- Function: in_neighbors (<v>, <gr>)
     Returns the list of in-neighbors of the vertex <v> in the directed
     graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) p : path_digraph(3)$
          (%i3) in_neighbors(2, p);
          (%o3)                          [1]
          (%i4) out_neighbors(2, p);
          (%o4)                          []

 -- Function: is_biconnected (<gr>)
     Returns `true' if <gr> is 2-connected and `false' otherwise.

     Example:
          (%i1) load (graphs)$
          (%i2) is_biconnected(cycle_graph(5));
          (%o2)                         true
          (%i3) is_biconnected(path_graph(5));
          (%o3)                         false

 -- Function: is_bipartite (<gr>)
     Returns `true' if <gr> is bipartite (2-colorable) and `false'
     otherwise.

     Example:
          (%i1) load (graphs)$
          (%i2) is_bipartite(petersen_graph());
          (%o2)                         false
          (%i3) is_bipartite(heawood_graph());
          (%o3)                         true

 -- Function: is_connected (<gr>)
     Returns `true' if the graph <gr> is connected and `false'
     otherwise.

     Example:
          (%i1) load (graphs)$
          (%i2) is_connected(graph_union(cycle_graph(4), path_graph(3)));
          (%o2)                         false

 -- Function: is_digraph (<gr>)
     Returns `true' if <gr> is a directed graph and `false' otherwise.

     Example:
          (%i1) load (graphs)$
          (%i2) is_digraph(path_graph(5));
          (%o2)                         false
          (%i3) is_digraph(path_digraph(5));
          (%o3)                         true

 -- Function: is_edge_in_graph (<e>, <gr>)
     Returns `true' if <e> is an edge (arc) in the (directed) graph <g>
     and `false' otherwise.

     Example:
          (%i1) load (graphs)$
          (%i2) c4 : cycle_graph(4)$
          (%i3) is_edge_in_graph([2,3], c4);
          (%o3)                         true
          (%i4) is_edge_in_graph([3,2], c4);
          (%o4)                         true
          (%i5) is_edge_in_graph([2,4], c4);
          (%o5)                         false
          (%i6) is_edge_in_graph([3,2], cycle_digraph(4));
          (%o6)                         false

 -- Function: is_graph (<gr>)
     Returns `true' if <gr> is a graph and `false' otherwise.

     Example:
          (%i1) load (graphs)$
          (%i2) is_graph(path_graph(5));
          (%o2)                         true
          (%i3) is_graph(path_digraph(5));
          (%o3)                         false

 -- Function: is_graph_or_digraph (<gr>)
     Returns `true' if <gr> is a graph or a directed graph and `false'
     otherwise.

     Example:
          (%i1) load (graphs)$
          (%i2) is_graph_or_digraph(path_graph(5));
          (%o2)                         true
          (%i3) is_graph_or_digraph(path_digraph(5));
          (%o3)                         true

 -- Function: is_isomorphic (<gr1>, <gr2>)
     Returns `true' if graphs/digraphs <gr1> and <gr2> are isomorphic
     and `false' otherwise.

     See also `isomorphism'.

     Example:
          (%i1) load (graphs)$
          (%i2) clk5:complement_graph(line_graph(complete_graph(5)))$
          (%i3) is_isomorphic(clk5, petersen_graph());
          (%o3)                         true

 -- Function: is_planar (<gr>)
     Returns `true' if <gr> is a planar graph and `false' otherwise.

     The algorithm used is the Demoucron's algorithm, which is a
     quadratic time algorithm.

     Example:
          (%i1) load (graphs)$
          (%i2) is_planar(dodecahedron_graph());
          (%o2)                         true
          (%i3) is_planar(petersen_graph());
          (%o3)                         false
          (%i4) is_planar(petersen_graph(10,2));
          (%o4)                         true

 -- Function: is_sconnected (<gr>)
     Returns `true' if the directed graph <gr> is strongly connected and
     `false' otherwise.

     Example:
          (%i1) load (graphs)$
          (%i2) is_sconnected(cycle_digraph(5));
          (%o2)                         true
          (%i3) is_sconnected(path_digraph(5));
          (%o3)                         false

 -- Function: is_vertex_in_graph (<v>, <gr>)
     Returns `true' if <v> is a vertex in the graph <g> and `false'
     otherwise.

     Example:
          (%i1) load (graphs)$
          (%i2) c4 : cycle_graph(4)$
          (%i3) is_vertex_in_graph(0, c4);
          (%o3)                         true
          (%i4) is_vertex_in_graph(6, c4);
          (%o4)                         false

 -- Function: is_tree (<gr>)
     Returns `true' if <gr> is a tree and `false'  otherwise.

     Example:
          (%i1) load (graphs)$
          (%i2) is_tree(random_tree(4));
          (%o2)                         true
          (%i3) is_tree(graph_union(random_tree(4), random_tree(5)));
          (%o3)                         false

 -- Function: laplacian_matrix (<gr>)
     Returns the laplacian matrix of the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) laplacian_matrix(cycle_graph(5));
                             [  2   - 1   0    0   - 1 ]
                             [                         ]
                             [ - 1   2   - 1   0    0  ]
                             [                         ]
          (%o2)              [  0   - 1   2   - 1   0  ]
                             [                         ]
                             [  0    0   - 1   2   - 1 ]
                             [                         ]
                             [ - 1   0    0   - 1   2  ]

 -- Function: max_clique (<gr>)
     Returns a maximum clique of the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) g : random_graph(100, 0.5)$
          (%i3) max_clique(g);
          (%o3)          [6, 12, 31, 36, 52, 59, 62, 63, 80]

 -- Function: max_degree (<gr>)
     Returns the maximal degree of vertices of the graph <gr> and a
     vertex of maximal degree.

     Example:
          (%i1) load (graphs)$
          (%i2) g : random_graph(100, 0.02)$
          (%i3) max_degree(g);
          (%o3)                        [6, 79]
          (%i4) vertex_degree(95, g);
          (%o4)                           2

 -- Function: max_flow (<net>, <s>, <t>)
     Returns a maximum flow through the network <net> with the source
     <s> and the sink <t>.

     The function returns the value of the maximal flow and a list
     representing the weights of the arcs in the optimal flow.

     Example:
          (%i1) load (graphs)$
          (%i2) net : create_graph(
            [1,2,3,4,5,6],
            [[[1,2], 1.0],
             [[1,3], 0.3],
             [[2,4], 0.2],
             [[2,5], 0.3],
             [[3,4], 0.1],
             [[3,5], 0.1],
             [[4,6], 1.0],
             [[5,6], 1.0]],
            directed=true)$
          (%i3) [flow_value, flow] : max_flow(net, 1, 6);
          (%o3) [0.7, [[[1, 2], 0.5], [[1, 3], 0.2], [[2, 4], 0.2],
          [[2, 5], 0.3], [[3, 4], 0.1], [[3, 5], 0.1], [[4, 6], 0.3],
          [[5, 6], 0.4]]]
          (%i4) fl : 0$
          (%i5) for u in out_neighbors(1, net)
               do fl : fl + assoc([1, u], flow)$
          (%i6) fl;
          (%o6)                          0.7

 -- Function: max_independent_set (<gr>)
     Returns a maximum independent set of the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) d : dodecahedron_graph()$
          (%i3) mi : max_independent_set(d);
          (%o3)             [0, 3, 5, 9, 10, 11, 18, 19]
          (%i4) draw_graph(d, show_vertices=mi)$

 -- Function: max_matching (<gr>)
     Returns a maximum matching of the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) d : dodecahedron_graph()$
          (%i3) m : max_matching(d);
          (%o3) [[5, 7], [8, 9], [6, 10], [14, 19], [13, 18], [12, 17],
                                         [11, 16], [0, 15], [3, 4], [1, 2]]
          (%i4) draw_graph(d, show_edges=m)$

 -- Function: min_degree (<gr>)
     Returns the minimum degree of vertices of the graph <gr> and a
     vertex of minimum degree.

     Example:
          (%i1) load (graphs)$
          (%i2) g : random_graph(100, 0.1)$
          (%i3) min_degree(g);
          (%o3)                        [3, 49]
          (%i4) vertex_degree(21, g);
          (%o4)                           9

 -- Function: min_edge_cut (<gr>)
     Returns the minimum edge cut in a connected graph <gr>

 -- Function: min_vertex_cover (<gr>)
     Returns the minimum vertex cover of the graph <gr>.

 -- Function: minimum_spanning_tree (<gr>)
     Returns the minimum spanning tree of the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) g : graph_product(path_graph(10), path_graph(10))$
          (%i3) t : minimum_spanning_tree(g)$
          (%i4) draw_graph(g, show_edges=edges(t))$

 -- Function: neighbors (<v>, <gr>)
     Returns the list of neighbors of the vertex <v> in the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) p : petersen_graph()$
          (%i3) neighbors(3, p);
          (%o3)                       [4, 8, 2]

 -- Function: odd_girth (<gr>)
     Returns the length of the shortest odd cycle in the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) g : graph_product(cycle_graph(4), cycle_graph(7))$
          (%i3) girth(g);
          (%o3)                           4
          (%i4) odd_girth(g);
          (%o4)                           7

 -- Function: out_neighbors (<v>, <gr>)
     Returns the list of out-neighbors of the vertex <v> in the directed
     graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) p : path_digraph(3)$
          (%i3) in_neighbors(2, p);
          (%o3)                          [1]
          (%i4) out_neighbors(2, p);
          (%o4)                          []

 -- Function: planar_embedding (<gr>)
     Returns the list of facial walks in a planar embedding of <gr> and
     `false' if <gr> is not a planar graph.

     The graph <gr> must be biconnected.

     The algorithm used is the Demoucron's algorithm, which is a
     quadratic time algorithm.

     Example:
          (%i1) load (graphs)$
          (%i2) planar_embedding(grid_graph(3,3));
          (%o2) [[3, 6, 7, 8, 5, 2, 1, 0], [4, 3, 0, 1], [3, 4, 7, 6],
                                                [8, 7, 4, 5], [1, 2, 5, 4]]

 -- Function: print_graph (<gr>)
     Prints some information about the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) c5 : cycle_graph(5)$
          (%i3) print_graph(c5)$
          Graph on 5 vertices with 5 edges.
          Adjacencies:
            4 :  0  3
            3 :  4  2
            2 :  3  1
            1 :  2  0
            0 :  4  1
          (%i4) dc5 : cycle_digraph(5)$
          (%i5) print_graph(dc5)$
          Digraph on 5 vertices with 5 arcs.
          Adjacencies:
            4 :  0
            3 :  4
            2 :  3
            1 :  2
            0 :  1
          (%i6) out_neighbors(0, dc5);
          (%o6)                          [1]

 -- Function: radius (<gr>)
     Returns the radius of the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) radius(dodecahedron_graph());
          (%o2)                           5

 -- Function: set_edge_weight (<e>, <w>, <gr>)
     Assigns the weight <w> to the edge <e> in the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) g : create_graph([1, 2], [[[1,2], 1.2]])$
          (%i3) get_edge_weight([1,2], g);
          (%o3)                          1.2
          (%i4) set_edge_weight([1,2], 2.1, g);
          (%o4)                         done
          (%i5) get_edge_weight([1,2], g);
          (%o5)                          2.1

 -- Function: set_vertex_label (<v>, <l>, <gr>)
     Assigns the label <l> to the vertex <v> in the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) g : create_graph([[1, "One"], [2, "Two"]], [[1,2]])$
          (%i3) get_vertex_label(1, g);
          (%o3)                          One
          (%i4) set_vertex_label(1, "oNE", g);
          (%o4)                         done
          (%i5) get_vertex_label(1, g);
          (%o5)                          oNE

 -- Function: shortest_path (<u>, <v>, <gr>)
     Returns the shortest path from <u> to <v> in the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) d : dodecahedron_graph()$
          (%i3) path : shortest_path(0, 7, d);
          (%o3)                   [0, 1, 19, 13, 7]
          (%i4) draw_graph(d, show_edges=vertices_to_path(path))$

 -- Function: shortest_weighted_path (<u>, <v>, <gr>)
     Returns the length of the shortest weighted path and the shortest
     weighted path from <u> to <v> in the graph <gr>.

     The length of a weighted path is the sum of edge weights of edges
     in the path. If an edge has no weight, then it has a default
     weight 1.

     Example:

          (%i1) load (graphs)$
          (%i2) g: petersen_graph(20, 2)$
          (%i3) for e in edges(g) do set_edge_weight(e, random(1.0), g)$
          (%i4) shortest_weighted_path(0, 10, g);
          (%o4) [2.575143920268482, [0, 20, 38, 36, 34, 32, 30, 10]]


 -- Function: strong_components (<gr>)
     Returns the strong components of a directed graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) t : random_tournament(4)$
          (%i3) strong_components(t);
          (%o3)                 [[1], [0], [2], [3]]
          (%i4) vertex_out_degree(3, t);
          (%o4)                           3

 -- Function: topological_sort (<dag>)
     Returns a topological sorting of the vertices of a directed graph
     <dag> or an empty list if <dag> is not a directed acyclic graph.

     Example:
          (%i1) load (graphs)$
          (%i2) g:create_graph(
                   [1,2,3,4,5],
                   [
                    [1,2], [2,5], [5,3],
                    [5,4], [3,4], [1,3]
                   ],
                   directed=true)$
          (%i3) topological_sort(g);
          (%o3)                    [1, 2, 5, 3, 4]

 -- Function: vertex_degree (<v>, <gr>)
     Returns the degree of the vertex <v> in the graph <gr>.

 -- Function: vertex_distance (<u>, <v>, <gr>)
     Returns the length of the shortest path between <u> and <v> in the
     (directed) graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) d : dodecahedron_graph()$
          (%i3) vertex_distance(0, 7, d);
          (%o3)                           4
          (%i4) shortest_path(0, 7, d);
          (%o4)                   [0, 1, 19, 13, 7]

 -- Function: vertex_eccentricity (<v>, <gr>)
     Returns the eccentricity of the vertex <v> in the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) g:cycle_graph(7)$
          (%i3) vertex_eccentricity(0, g);
          (%o3)                           3

 -- Function: vertex_in_degree (<v>, <gr>)
     Returns the in-degree of the vertex <v> in the directed graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) p5 : path_digraph(5)$
          (%i3) print_graph(p5)$
          Digraph on 5 vertices with 4 arcs.
          Adjacencies:
            4 :
            3 :  4
            2 :  3
            1 :  2
            0 :  1
          (%i4) vertex_in_degree(4, p5);
          (%o4)                           1
          (%i5) in_neighbors(4, p5);
          (%o5)                          [3]

 -- Function: vertex_out_degree (<v>, <gr>)
     Returns the out-degree of the vertex <v> in the directed graph
     <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) t : random_tournament(10)$
          (%i3) vertex_out_degree(0, t);
          (%o3)                           2
          (%i4) out_neighbors(0, t);
          (%o4)                        [7, 1]

 -- Function: vertices (<gr>)
     Returns the list of vertices in the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) vertices(complete_graph(4));
          (%o2)                     [3, 2, 1, 0]

53.2.3 Modifying graphs
-----------------------

 -- Function: add_edge (<e>, <gr>)
     Adds the edge <e> to the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) p : path_graph(4)$
          (%i3) neighbors(0, p);
          (%o3)                          [1]
          (%i4) add_edge([0,3], p);
          (%o4)                         done
          (%i5) neighbors(0, p);
          (%o5)                        [3, 1]

 -- Function: add_edges (<e_list>, <gr>)
     Adds all edges in the list <e_list> to the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) g : empty_graph(3)$
          (%i3) add_edges([[0,1],[1,2]], g)$
          (%i4) print_graph(g)$
          Graph on 3 vertices with 2 edges.
          Adjacencies:
            2 :  1
            1 :  2  0
            0 :  1

 -- Function: add_vertex (<v>, <gr>)
     Adds the vertex <v> to the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) g : path_graph(2)$
          (%i3) add_vertex(2, g)$
          (%i4) print_graph(g)$
          Graph on 3 vertices with 1 edges.
          Adjacencies:
            2 :
            1 :  0
            0 :  1

 -- Function: add_vertices (<v_list>, <gr>)
     Adds all vertices in the list <v_list> to the graph <gr>.

 -- Function: connect_vertices (<v_list>, <u_list>, <gr>)
     Connects all vertices from the list <v_list> with the vertices in
     the list <u_list> in the graph <gr>.

     <v_list> and <u_list> can be single vertices or lists of vertices.

     Example:
          (%i1) load (graphs)$
          (%i2) g : empty_graph(4)$
          (%i3) connect_vertices(0, [1,2,3], g)$
          (%i4) print_graph(g)$
          Graph on 4 vertices with 3 edges.
          Adjacencies:
            3 :  0
            2 :  0
            1 :  0
            0 :  3  2  1

 -- Function: contract_edge (<e>, <gr>)
     Contracts the edge <e> in the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) g: create_graph(
                8, [[0,3],[1,3],[2,3],[3,4],[4,5],[4,6],[4,7]])$
          (%i3) print_graph(g)$
          Graph on 8 vertices with 7 edges.
          Adjacencies:
            7 :  4
            6 :  4
            5 :  4
            4 :  7  6  5  3
            3 :  4  2  1  0
            2 :  3
            1 :  3
            0 :  3
          (%i4) contract_edge([3,4], g)$
          (%i5) print_graph(g)$
          Graph on 7 vertices with 6 edges.
          Adjacencies:
            7 :  3
            6 :  3
            5 :  3
            3 :  5  6  7  2  1  0
            2 :  3
            1 :  3
            0 :  3

 -- Function: remove_edge (<e>, <gr>)
     Removes the edge <e> from the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) c3 : cycle_graph(3)$
          (%i3) remove_edge([0,1], c3)$
          (%i4) print_graph(c3)$
          Graph on 3 vertices with 2 edges.
          Adjacencies:
            2 :  0  1
            1 :  2
            0 :  2

 -- Function: remove_vertex (<v>, <gr>)
     Removes the vertex <v> from the graph <gr>.

 -- Function: vertex_coloring (<gr>)
     Returns an optimal coloring of the vertices of the graph <gr>.

     The function returns the chromatic number and a list representing
     the coloring of the vertices of <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) p:petersen_graph()$
          (%i3) vertex_coloring(p);
          (%o3) [3, [[0, 2], [1, 3], [2, 2], [3, 3], [4, 1], [5, 3],
                                           [6, 1], [7, 1], [8, 2], [9, 2]]]

53.2.4 Reading and writing to files
-----------------------------------

 -- Function: dimacs_export (<gr>, <fl>)
 -- Function: dimacs_export (<gr>, <fl>, <comment1>, ..., <commentn>)
     Exports the graph into the file <fl> in the DIMACS format. Optional
     comments will be added to the top of the file.

 -- Function: dimacs_import (<fl>)
     Returns the graph from file <fl> in the DIMACS format.

 -- Function: graph6_decode (<str>)
     Returns the graph encoded in the graph6 format in the string <str>.

 -- Function: graph6_encode (<gr>)
     Returns a string which encodes the graph <gr> in the graph6 format.

 -- Function: graph6_export (<gr_list>, <fl>)
     Exports graphs in the list <gr_list> to the file <fl> in the
     graph6 format.

 -- Function: graph6_import (<fl>)
     Returns a list of graphs from the file <fl> in the graph6 format.

 -- Function: sparse6_decode (<str>)
     Returns the graph encoded in the sparse6 format in the string
     <str>.

 -- Function: sparse6_encode (<gr>)
     Returns a string which encodes the graph <gr> in the sparse6
     format.

 -- Function: sparse6_export (<gr_list>, <fl>)
     Exports graphs in the list <gr_list> to the file <fl> in the
     sparse6 format.

 -- Function: sparse6_import (<fl>)
     Returns a list of graphs from the file <fl> in the sparse6 format.

53.2.5 Visualization
--------------------

 -- Function: draw_graph (<graph>)
 -- Function: draw_graph (<graph>, <option1>, ..., <optionk>)
     Draws the graph using the `draw' package.

     The algorithm used to position vertices is specified by the
     optional argument <program>. The default value is
     `program=spring_embedding'. <spring_embedding> can also use the
     graphviz programs for positioning vertices, but graphviz must be
     installed separately.

     Optional arguments to the <draw_graph> function can be:
        * "show_id=show": if <show> is <true> then ids of the vertices
          are displayed.

        * "show_label=show": if <show> is <true> then labels of the
          vertices are displayed.

        * "label_alignment=pos": how to align the label/id of the
          vertices. Can be `left', `center' or  `right'. The default is
          `left'.

        * "show_weight=show": if <show> is <true> then weights of the
          edges are displayed.

        * "vertex_type=type": defines how vertices are displayed. See
          the <point_type> option for the `draw' package.

        * "vertex_size=size": the size of vertices.

        * "vertex_color=c": color used for displaying vertices.

        * "show_vertices=v_list": display vertices in the list <v_list>
          using a different color.

        * "show_vertex_type=type": defines how vertices in
          <show_vertices> are displayed. See the <point_type> option
          for the `draw' package.

        * "show_vertex_size=size": the size of vertices in
          <show_vertices>.

        * "show_vertex_color=c": color used for displaying vertices in
          the <show_vertices> list.

        * "vertex_partition=part": a partition
          `[[v1,v2,...],...,[vk,...,vn]]' of the vertices of the graph.
          The vertices of each list in the partition will be drawn in a
          different color.

        * "vertex_coloring=col": coloring of the vertices. The coloring
          <col> must be specified in the format as returned by
          <vertex_coloring>.

        * "edge_color=c": color used for displaying edges.

        * "edge_width=width": the width of edges.

        * "edge_type=type": defines how edges are displayed. See the
          <line_type> option for the `draw' package.

        * "show_edges=e_list": display edges in the list <e_list> using
          a different color.

        * "show_edge_color=c": color used for displaying edges in the
          <show_edges> list.

        * "show_edge_width=width": the width of edges in <show_edges>.

        * "show_edge_type=type": defines how edges in <show_edges> are
          displayed. See the <line_type> option for the `draw' package.

        * "edge_partition=partition": a partition
          `[[e1,e2,...],...,[ek,...,em]]' of edges of the graph. The
          edges of each list in the partition will be drawn using a
          different color.

        * "edge_coloring=col": the coloring of edges. The coloring
          <col> must be specified in the format as returned by the
          function <edge_coloring>.

        * "redraw=r": if <redraw> is `true', vertex positions are
          recomputed even if the positions have been saved from a
          previous drawing of the graph.

        * "head_angle=angle": the angle for the arrows displayed on
          arcs (in directed graphs). Default value: 15.

        * "head_length=len": the length for the arrows displayed on
          arcs (in directed graphs). Default value: 0.1.

        * "spring_embedding_depth=depth": the number of iterations in
          the spring embedding graph drawing algorithm. Default value:
          50.

        * "terminal=term": the terminal used for drawing (see the
          <terminal> option in the `draw' package).

        * "file_name=file": the filename of the drawing if terminal is
          not screen.

        * "program=prg": defines the program used for positioning
          vertices of the graph. Can be one of the graphviz programs
          (dot, neato, twopi, circ, fdp), <circular>,
          <spring_embedding> or <planar_embedding>. <planar_embedding>
          is only available for 2-connected planar graphs. When
          `program=spring_embedding', a set of vertices with fixed
          position can be specified with the <fixed_vertices> option.

        * "fixed_vertices=[]": specifies a list of vertices which will
          have positions fixed along a regular polygon. Can be used when
          `program=spring_embedding'.

     Example 1:

          (%i1) load (graphs)$
          (%i2) g:grid_graph(10,10)$
          (%i3) m:max_matching(g)$
          (%i4) draw_graph(g,
             spring_embedding_depth=100,
             show_edges=m, edge_type=dots,
             vertex_size=0)$

     Example 2:

          (%i1) load (graphs)$
          (%i2) g:create_graph(16,
              [
               [0,1],[1,3],[2,3],[0,2],[3,4],[2,4],
               [5,6],[6,4],[4,7],[6,7],[7,8],[7,10],[7,11],
               [8,10],[11,10],[8,9],[11,12],[9,15],[12,13],
               [10,14],[15,14],[13,14]
              ])$
          (%i3) t:minimum_spanning_tree(g)$
          (%i4) draw_graph(
              g,
              show_edges=edges(t),
              show_edge_width=4,
              show_edge_color=green,
              vertex_type=filled_square,
              vertex_size=2
              )$

     Example 3:

          (%i1) load (graphs)$
          (%i2) g:create_graph(16,
              [
               [0,1],[1,3],[2,3],[0,2],[3,4],[2,4],
               [5,6],[6,4],[4,7],[6,7],[7,8],[7,10],[7,11],
               [8,10],[11,10],[8,9],[11,12],[9,15],[12,13],
               [10,14],[15,14],[13,14]
              ])$
          (%i3) mi : max_independent_set(g)$
          (%i4) draw_graph(
              g,
              show_vertices=mi,
              show_vertex_type=filled_up_triangle,
              show_vertex_size=2,
              edge_color=cyan,
              edge_width=3,
              show_id=true,
              text_color=brown
              )$

     Example 4:

          (%i1) load (graphs)$
          (%i2) net : create_graph(
              [0,1,2,3,4,5],
              [
               [[0,1], 3], [[0,2], 2],
               [[1,3], 1], [[1,4], 3],
               [[2,3], 2], [[2,4], 2],
               [[4,5], 2], [[3,5], 2]
              ],
              directed=true
              )$
          (%i3) draw_graph(
              net,
              show_weight=true,
              vertex_size=0,
              show_vertices=[0,5],
              show_vertex_type=filled_square,
              head_length=0.2,
              head_angle=10,
              edge_color="dark-green",
              text_color=blue
              )$

     Example 5:

          (%i1) load(graphs)$
          (%i2) g: petersen_graph(20, 2);
          (%o2)                         GRAPH
          (%i3) draw_graph(g, redraw=true, program=planar_embedding);
          (%o3)                         done

     Example 6:

          (%i1) load(graphs)$
          (%i2) t: tutte_graph();
          (%o2)                         GRAPH
          (%i3) draw_graph(t, redraw=true, fixed_vertices=[1,2,3,4,5,6,7,8,9]);
          (%o3)                         done


 -- Option variable: draw_graph_program
     Default value: <spring_embedding>.

     The default value for the program used to position vertices in
     `draw_graph' program.

 -- Function: vertices_to_path (<v_list>)
     Converts a list <v_list> of vertices to a list of edges of the path
     defined by <v_list>.

 -- Function: vertices_to_cycle (<v_list>)
     Converts a list <v_list> of vertices to a list of edges of the
     cycle defined by <v_list>.


File: maxima.info,  Node: grobner,  Next: impdiff,  Prev: graphs,  Up: Top

54 grobner
**********

* Menu:

* Introduction to grobner ::
* Functions and Variables for grobner ::


File: maxima.info,  Node: Introduction to grobner,  Next: Functions and Variables for grobner,  Prev: Top,  Up: Top

54.1 Introduction to grobner
============================

`grobner' is a package for working with Groebner bases in Maxima.

A tutorial on _Groebner Bases_ can be found at

`http://www.geocities.com/CapeCanaveral/Hall/3131/'

To use the following functions you must load the `grobner.lisp' package.

     load(grobner);

A demo can be started by
     demo("grobner.demo");

or
     batch("grobner.demo")

Some of the calculation in the demo will take a lot of time therefore
the output `grobner-demo.output' of the demo can be found in the same
directory as the demo file.

54.1.1 Notes on the grobner package
-----------------------------------

The package was written by

Marek Rychlik

`http://alamos.math.arizona.edu'

and is released 2002-05-24 under the terms of the General Public
License(GPL) (see file `grobner.lisp'.  This documentation was
extracted from the files
`README', `grobner.lisp', `grobner.demo', `grobner-demo.output'

by Gu"nter Nowak. Suggestions for improvement of the documentation can
be discussed at the _maxima_-mailing-list <maxima@math.utexas.edu>.
The code is a little bit out of date now. Modern implementation use the
fast _F4_ algorithm described in
A new efficient algorithm for computing Gro"bner bases (F4)
Jean-Charles Fauge`re
LIP6/CNRS Universite' Paris VI
January 20, 1999

54.1.2 Implementations of admissible monomial orders in grobner
---------------------------------------------------------------

   * `lex'

     pure lexicographic, default order for monomial comparisons

   * `grlex'

     total degree order, ties broken by lexicographic

   * `grevlex'

     total degree, ties broken by reverse lexicographic

   * `invlex'

     inverse lexicographic order



File: maxima.info,  Node: Functions and Variables for grobner,  Prev: Introduction to grobner,  Up: Top

54.2 Functions and Variables for grobner
========================================

54.2.1 Global switches for grobner
----------------------------------

 -- Option variable: poly_monomial_order
     Default value: `lex'

     This global switch controls which monomial order is used in
     polynomial and Groebner Bases calculations. If not set, `lex' will
     be used.


 -- Option variable: poly_coefficient_ring
     Default value: `expression_ring'

     This switch indicates the coefficient ring of the polynomials that
     will be used in grobner calculations. If not set, _maxima's_
     general expression ring will be used. This variable may be set to
     `ring_of_integers' if desired.


 -- Option variable: poly_primary_elimination_order
     Default value: `false'

     Name of the default order for eliminated variables in
     elimination-based functions. If not set, `lex' will be used.


 -- Option variable: poly_secondary_elimination_order
     Default value: `false'

     Name of the default order for kept variables in elimination-based
     functions. If not set, `lex' will be used.


 -- Option variable: poly_elimination_order
     Default value: `false'

     Name of the default elimination order used in elimination
     calculations. If set, it overrides the settings in variables
     `poly_primary_elimination_order' and
     `poly_secondary_elimination_order'.  The user must ensure that
     this is a true elimination order valid for the number of
     eliminated variables.


 -- Option variable: poly_return_term_list
     Default value: `false'

     If set to `true', all functions in this package will return each
     polynomial as a list of terms in the current monomial order rather
     than a _maxima_ general expression.


 -- Option variable: poly_grobner_debug
     Default value: `false'

     If set to `true', produce debugging and tracing output.


 -- Option variable: poly_grobner_algorithm
     Default value: `buchberger'

     Possible values:
        * `buchberger'

        * `parallel_buchberger'

        * `gebauer_moeller'

     The name of the algorithm used to find the Groebner Bases.


 -- Option variable: poly_top_reduction_only
     Default value: `false'

     If not `false', use top reduction only whenever possible. Top
     reduction means that division algorithm stops after the first
     reduction.


54.2.2 Simple operators in grobner
----------------------------------

`poly_add', `poly_subtract', `poly_multiply' and `poly_expt' are the
arithmetical operations on polynomials.  These are performed using the
internal representation, but the results are converted back to the
_maxima_ general form.

 -- Function: poly_add (<poly1>, <poly2>, <varlist>)
     Adds two polynomials <poly1> and <poly2>.

          (%i1) poly_add(z+x^2*y,x-z,[x,y,z]);
                                              2
          (%o1)                              x  y + x


 -- Function: poly_subtract (<poly1>, <poly2>, <varlist>)
     Subtracts a polynomial <poly2> from <poly1>.

          (%i1) poly_subtract(z+x^2*y,x-z,[x,y,z]);
                                                2
          (%o1)                          2 z + x  y - x


 -- Function: poly_multiply (<poly1>, <poly2>, <varlist>)
     Returns the product of polynomials <poly1> and <poly2>.

          (%i2) poly_multiply(z+x^2*y,x-z,[x,y,z])-(z+x^2*y)*(x-z),expand;
          (%o1)                                  0


 -- Function: poly_s_polynomial (<poly1>, <poly2>, <varlist>)
     Returns the _syzygy polynomial_ (_S-polynomial_) of two
     polynomials <poly1> and <poly2>.


 -- Function: poly_primitive_part (<poly1>, <varlist>)
     Returns the polynomial <poly> divided by the GCD of its
     coefficients.

          (%i1) poly_primitive_part(35*y+21*x,[x,y]);
          (%o1)                              5 y + 3 x


 -- Function: poly_normalize (<poly>, <varlist>)
     Returns the polynomial <poly> divided by the leading coefficient.
     It assumes that the division is possible, which may not always be
     the case in rings which are not fields.


54.2.3 Other functions in grobner
---------------------------------

 -- Function: poly_expand (<poly>, <varlist>)
     This function parses polynomials to internal form and back. It is
     equivalent to `expand(<poly>)' if <poly> parses correctly to a
     polynomial. If the representation is not compatible with a
     polynomial in variables <varlist>, the result is an error.  It can
     be used to test whether an expression correctly parses to the
     internal representation. The following examples illustrate that
     indexed and transcendental function variables are allowed.

          (%i1) poly_expand((x-y)*(y+x),[x,y]);
                                               2    2
          (%o1)                               x  - y
          (%i2) poly_expand((y+x)^2,[x,y]);
                                          2            2
          (%o2)                          y  + 2 x y + x
          (%i3) poly_expand((y+x)^5,[x,y]);
                            5      4         2  3       3  2      4      5
          (%o3)            y  + 5 x y  + 10 x  y  + 10 x  y  + 5 x  y + x
          (%i4) poly_expand(-1-x*exp(y)+x^2/sqrt(y),[x]);
                                                    2
                                            y      x
          (%o4)                       - x %e  + ------- - 1
                                                 sqrt(y)

          (%i5) poly_expand(-1-sin(x)^2+sin(x),[sin(x)]);
                                          2
          (%o5)                      - sin (x) + sin(x) - 1


 -- Function: poly_expt (<poly>, <number>, <varlist>)
     exponentitates <poly> by a positive integer <number>. If <number>
     is not a positive integer number an error will be raised.

          (%i1) poly_expt(x-y,3,[x,y])-(x-y)^3,expand;
          (%o1)                                  0


 -- Function: poly_content (<poly>. <varlist>)
     `poly_content' extracts the GCD of its coefficients

          (%i1) poly_content(35*y+21*x,[x,y]);
          (%o1)                                  7


 -- Function: poly_pseudo_divide (<poly>, <polylist>, <varlist>)
     Pseudo-divide a polynomial <poly> by the list of n polynomials
     <polylist>. Return multiple values. The first value is a list of
     quotients a. The second value is the remainder r. The third
     argument is a scalar coefficient c, such that c*poly can be
     divided by <polylist> within the ring of coefficients, which is
     not necessarily a field. Finally, the fourth value is an integer
     count of the number of reductions performed. The resulting objects
     satisfy the equation:

     c*poly=sum(a[i]*polylist[i],i=1...n)+r.


 -- Function: poly_exact_divide (<poly1>, <poly2>, <varlist>)
     Divide a polynomial <poly1> by another polynomial <poly2>. Assumes
     that exact division with no remainder is possible. Returns the
     quotient.


 -- Function: poly_normal_form (<poly>, <polylist>, <varlist>)
     `poly_normal_form' finds the normal form of a polynomial <poly>
     with respect to a set of polynomials <polylist>.


 -- Function: poly_buchberger_criterion (<polylist>, <varlist>)
     Returns `true' if <polylist> is a Groebner basis with respect to
     the current term order, by using the Buchberger criterion: for
     every two polynomials h1 and h2 in <polylist> the S-polynomial
     S(h1,h2) reduces to 0 modulo <polylist>.


 -- Function: poly_buchberger (<polylist_fl> <varlist>)
     `poly_buchberger' performs the Buchberger algorithm on a list of
     polynomials and returns the resulting Groebner basis.


54.2.4 Standard postprocessing of Groebner Bases
------------------------------------------------

The _k-th elimination Ideal_ I_k of an Ideal I over K[ x[1],...,x[n] ]
is the ideal intersect(I, K[ x[k+1],...,x[n] ]).
The _colon ideal_ I:J is the ideal {h|for all w in J: w*h in I}.
The ideal I:p^inf is the ideal {h| there is a n in N: p^n*h in I}.
The ideal I:J^inf is the ideal {h| there is a n in N and a p in J:
p^n*h in I}.
The _radical ideal_ sqrt(I) is the ideal {h| there is a n in N : h^n in
I }.



 -- Function: poly_reduction (<polylist>, <varlist>)
     `poly_reduction' reduces a list of polynomials <polylist>, so that
     each polynomial is fully reduced with respect to the other
     polynomials.


 -- Function: poly_minimization (<polylist>, <varlist>)
     Returns a sublist of the polynomial list <polylist> spanning the
     same monomial ideal as <polylist> but minimal, i.e. no leading
     monomial of a polynomial in the sublist divides the leading
     monomial of another polynomial.


 -- Function: poly_normalize_list (<polylist>, <varlist>)
     `poly_normalize_list' applies `poly_normalize' to each polynomial
     in the list.  That means it divides every polynomial in a list
     <polylist> by its leading coefficient.


 -- Function: poly_grobner (<polylist>, <varlist>)
     Returns a Groebner basis of the ideal span by the polynomials
     <polylist>. Affected by the global flags.


 -- Function: poly_reduced_grobner (<polylist>, <varlist>)
     Returns a reduced Groebner basis of the ideal span by the
     polynomials <polylist>. Affected by the global flags.


 -- Function: poly_depends_p (<poly>, <var>, <varlist>)
     `poly_depends' tests whether a polynomial depends on a variable
     <var>.


 -- Function: poly_elimination_ideal (<polylist>, <number>, <varlist>)
     `poly_elimination_ideal' returns the grobner basis of the
     number-th elimination ideal of an ideal specified as a list of
     generating polynomials (not necessarily Groebner basis).


 -- Function: poly_colon_ideal (<polylist1>, <polylist2>, <varlist>)
     Returns the reduced Groebner basis of the colon ideal

     I(polylist1):I(polylist2)

     where polylist1 and polylist2 are two lists of polynomials.


 -- Function: poly_ideal_intersection (<polylist1>, <polylist2>,
          <varlist>)
     `poly_ideal_intersection' returns the intersection of two ideals.


 -- Function: poly_lcm (<poly1>, <poly2>, <varlist>)
     Returns the lowest common multiple of <poly1> and <poly2>.


 -- Function: poly_gcd (<poly1>, <poly2>, <varlist>)
     Returns the greatest common divisor of <poly1> and <poly2>.


 -- Function: poly_grobner_equal (<polylist1>, <polylist2>, <varlist>)
     `poly_grobner_equal' tests whether two Groebner Bases generate the
     same ideal.  Returns `true' if two lists of polynomials
     <polylist1> and <polylist2>, assumed to be Groebner Bases,
     generate the same ideal, and `false' otherwise.  This is
     equivalent to checking that every polynomial of the first basis
     reduces to 0 modulo the second basis and vice versa. Note that in
     the example below the first list is not a Groebner basis, and thus
     the result is `false'.

          (%i1) poly_grobner_equal([y+x,x-y],[x,y],[x,y]);
          (%o1)                         false


 -- Function: poly_grobner_subsetp (<polylist1>, <polylist2>, <varlist>)
     `poly_grobner_subsetp' tests whether an ideal generated by
     <polylist1> is contained in the ideal generated by <polylist2>.
     For this test to always succeed, <polylist2> must be a Groebner
     basis.


 -- Function: poly_grobner_member (<poly>, <polylist>, <varlist>)
     Returns `true' if a polynomial <poly> belongs to the ideal
     generated by the polynomial list <polylist>, which is assumed to
     be a Groebner basis. Returns `false' otherwise.

     `poly_grobner_member' tests whether a polynomial belongs to an
     ideal generated by a list of polynomials, which is assumed to be a
     Groebner basis. Equivalent to `normal_form' being 0.


 -- Function: poly_ideal_saturation1 (<polylist>, <poly>, <varlist>)
     Returns the reduced Groebner basis of the saturation of the ideal

     I(polylist):poly^inf

     Geometrically, over an algebraically closed field, this is the set
     of polynomials in the ideal generated by <polylist> which do not
     identically vanish on the variety of <poly>.


 -- Function: poly_ideal_saturation (<polylist1>, <polylist2>,
          <varlist>)
     Returns the reduced Groebner basis of the saturation of the ideal

     I(polylist1):I(polylist2)^inf

     Geometrically, over an algebraically closed field, this is the set
     of polynomials in the ideal generated by <polylist1> which do not
     identically vanish on the variety of <polylist2>.


 -- Function: poly_ideal_polysaturation1 (<polylist1>, <polylist2>,
          <varlist>)
     <polylist2> ist a list of n polynomials `[poly1,...,polyn]'.
     Returns the reduced Groebner basis of the ideal

     I(polylist):poly1^inf:...:polyn^inf

     obtained by a sequence of successive saturations in the polynomials
     of the polynomial list <polylist2> of the ideal generated by the
     polynomial list <polylist1>.


 -- Function: poly_ideal_polysaturation (<polylist>, <polylistlist>,
          <varlist>)
     <polylistlist> is a list of n list of polynomials
     `[polylist1,...,polylistn]'.  Returns the reduced Groebner basis
     of the saturation of the ideal

     I(polylist):I(polylist_1)^inf:...:I(polylist_n)^inf


 -- Function: poly_saturation_extension (<poly>, <polylist>,
          <varlist1>, <varlist2>)
     `poly_saturation_extension' implements the famous Rabinowitz trick.


 -- Function: poly_polysaturation_extension (<poly>, <polylist>,
          <varlist1>, <varlist2>)


File: maxima.info,  Node: impdiff,  Next: implicit_plot,  Prev: grobner,  Up: Top

55 impdiff
**********

* Menu:

* Functions and Variables for impdiff::


File: maxima.info,  Node: Functions and Variables for impdiff,  Prev: impdiff,  Up: impdiff

55.1 Functions and Variables for impdiff
========================================

 -- Function: implicit_derivative
          (<f>,<indvarlist>,<orderlist>,<depvar>)
     This subroutine computes implicit derivatives of multivariable
     functions.  <f> is an array function, the indexes are the
     derivative degree in the <indvarlist> order; <indvarlist> is the
     independent variable list; <orderlist> is the order desired; and
     <depvar> is the dependent variable.

     To use this function write first `load("impdiff")'.



File: maxima.info,  Node: implicit_plot,  Next: interpol,  Prev: impdiff,  Up: Top

56 implicit_plot
****************

* Menu:

* Functions and Variables for implicit_plot::


File: maxima.info,  Node: Functions and Variables for implicit_plot,  Prev: implicit_plot,  Up: implicit_plot

56.1 Functions and Variables for implicit_plot
==============================================

 -- Function: implicit_plot (<expr>, <x_range>, <y_range>)
 -- Function: implicit_plot ([<expr_1>, ..., <expr_n>], <x_range>,
          <y_range>)
     Displays a plot of one or more expressions in implicit form.
     <expr> is the expression to be plotted, <x_range> the range of the
     horizontal axis and <y_range> the range of vertical axis.
     `implicit_plot' respects global setting for the gnuplot driver set
     by the <set_plot_option> function. Options can also be passed to
     `implicit_plot' function as optional arguments.

     `implicit_plot' works by tracking sign changes on the area given
     by <x_range> and <y_range> and can fail for complicated
     expressions.

     `load(implicit_plot)' loads this function.

     Example:
          (%i1) implicit_plot (x^2 = y^3 - 3*y + 1, [x, -4, 4], [y, -4, 4],
           [gnuplot_preamble, "set zeroaxis"]);



File: maxima.info,  Node: interpol,  Next: lapack,  Prev: implicit_plot,  Up: Top

57 interpol
***********

* Menu:

* Introduction to interpol::
* Functions and Variables for interpol::


File: maxima.info,  Node: Introduction to interpol,  Next: Functions and Variables for interpol,  Prev: interpol,  Up: interpol

57.1 Introduction to interpol
=============================

Package `interpol' defines the Lagrangian, the linear and the cubic
splines methods for polynomial interpolation.

   For comments, bugs or suggestions, please contact me at <'mario AT
edu DOT xunta DOT es'>.


File: maxima.info,  Node: Functions and Variables for interpol,  Prev: Introduction to interpol,  Up: interpol

57.2 Functions and Variables for interpol
=========================================

 -- Function: lagrange (<points>)
 -- Function: lagrange (<points>, <option>)
     Computes the polynomial interpolation by the Lagrangian method.
     Argument <points> must be either:

        * a two column matrix, `p:matrix([2,4],[5,6],[9,3])',

        * a list of pairs, `p: [[2,4],[5,6],[9,3]]',

        * a list of numbers, `p: [4,6,3]', in which case the abscissas
          will be assigned automatically to 1, 2, 3, etc.

     In the first two cases the pairs are ordered with respect to the
     first coordinate before making computations.

     With the <option> argument it is possible to select the name for
     the independent variable, which is `'x' by default; to define
     another one, write something like `varname='z'.

     Note that when working with high degree polynomials, floating
     point evaluations are instable.

     Examples:

          (%i1) load(interpol)$
          (%i2) p:[[7,2],[8,2],[1,5],[3,2],[6,7]]$
          (%i3) lagrange(p);
                           4        3         2
                       73 x    701 x    8957 x    5288 x   186
          (%o3)        ----- - ------ + ------- - ------ + ---
                        420     210       420      105      5
          (%i4) f(x):=''%;
                               4        3         2
                           73 x    701 x    8957 x    5288 x   186
          (%o4)    f(x) := ----- - ------ + ------- - ------ + ---
                            420     210       420      105      5
          (%i5) /* Evaluate the polynomial at some points */
                map(f,[2.3,5/7,%pi]);
                                       919062
          (%o5)  [- 1.567534999999992, ------,
                                       84035
                                   4          3           2
                             73 %pi    701 %pi    8957 %pi    5288 %pi   186
                             ------- - -------- + --------- - -------- + ---]
                               420       210         420        105       5
          (%i6) %,numer;
          (%o6) [- 1.567534999999992, 10.9366573451538, 2.89319655125692]
          (%i7) load(draw)$  /* load draw package */
          (%i8) /* Plot the polynomial together with points */
                draw2d(
                  color      = red,
                  key        = "Lagrange polynomial",
                  explicit(f(x),x,0,10),
                  point_size = 3,
                  color      = blue,
                  key        = "Sample points",
                  points(p))$
          (%i9) /* Change variable name */
                lagrange(p, varname=w);
                           4        3         2
                       73 w    701 w    8957 w    5288 w   186
          (%o9)        ----- - ------ + ------- - ------ + ---
                        420     210       420      105      5


 -- Function: charfun2 (<x>, <a>, <b>)
     Returns `true' if number <x> belongs to the interval [a, b), and
     `false' otherwise.


 -- Function: linearinterpol (<points>)
 -- Function: linearinterpol (<points>, <option>)
     Computes the polynomial interpolation by the linear method.
     Argument <points> must be either:

        * a two column matrix, `p:matrix([2,4],[5,6],[9,3])',

        * a list of pairs, `p: [[2,4],[5,6],[9,3]]',

        * a list of numbers, `p: [4,6,3]', in which case the abscissas
          will be assigned automatically to 1, 2, 3, etc.

     In the first two cases the pairs are ordered with respect to the
     first coordinate before making computations.

     With the <option> argument it is possible to select the name for
     the independent variable, which is `'x' by default; to define
     another one, write something like `varname='z'.

     Examples:
          (%i1) load(interpol)$
          (%i2) p: matrix([7,2],[8,3],[1,5],[3,2],[6,7])$
          (%i3) linearinterpol(p);
                  13   3 x
          (%o3)  (-- - ---) charfun2(x, minf, 3)
                  2     2
           + (x - 5) charfun2(x, 7, inf) + (37 - 5 x) charfun2(x, 6, 7)
              5 x
           + (--- - 3) charfun2(x, 3, 6)
               3

          (%i4) f(x):=''%;
                          13   3 x
          (%o4)  f(x) := (-- - ---) charfun2(x, minf, 3)
                          2     2
           + (x - 5) charfun2(x, 7, inf) + (37 - 5 x) charfun2(x, 6, 7)
              5 x
           + (--- - 3) charfun2(x, 3, 6)
               3
          (%i5)  /* Evaluate the polynomial at some points */
                 map(f,[7.3,25/7,%pi]);
                                      62  5 %pi
          (%o5)                 [2.3, --, ----- - 3]
                                      21    3
          (%i6) %,numer;
          (%o6)  [2.3, 2.952380952380953, 2.235987755982989]
          (%i7) load(draw)$  /* load draw package */
          (%i8)  /* Plot the polynomial together with points */
                 draw2d(
                   color      = red,
                   key        = "Linear interpolator",
                   explicit(f(x),x,-5,20),
                   point_size = 3,
                   color      = blue,
                   key        = "Sample points",
                   points(args(p)))$
          (%i9)  /* Change variable name */
                 linearinterpol(p, varname='s);
                 13   3 s
          (%o9) (-- - ---) charfun2(s, minf, 3)
                 2     2
           + (s - 5) charfun2(s, 7, inf) + (37 - 5 s) charfun2(s, 6, 7)
              5 s
           + (--- - 3) charfun2(s, 3, 6)
               3


 -- Function: cspline (<points>)
 -- Function: cspline (<points>, <option1>, <option2>, ...)
     Computes the polynomial interpolation by the cubic splines method.
     Argument <points> must be either:

        * a two column matrix, `p:matrix([2,4],[5,6],[9,3])',

        * a list of pairs, `p: [[2,4],[5,6],[9,3]]',

        * a list of numbers, `p: [4,6,3]', in which case the abscissas
          will be assigned automatically to 1, 2, 3, etc.

     In the first two cases the pairs are ordered with respect to the
     first coordinate before making computations.

     There are three options to fit specific needs:
        * `'d1', default `'unknown', is the first derivative at x_1; if
          it is `'unknown', the second derivative at x_1 is made equal
          to 0 (natural cubic spline); if it is equal to a number, the
          second derivative is calculated based on this number.

        * `'dn', default `'unknown', is the first derivative at x_n; if
          it is `'unknown', the second derivative at x_n is made equal
          to 0 (natural cubic spline); if it is equal to a number, the
          second derivative is calculated based on this number.

        * `'varname', default `'x', is the name of the independent
          variable.

     Examples:
          (%i1) load(interpol)$
          (%i2) p:[[7,2],[8,2],[1,5],[3,2],[6,7]]$
          (%i3) /* Unknown first derivatives at the extremes
                   is equivalent to natural cubic splines */
                cspline(p);
                        3         2
                  1159 x    1159 x    6091 x   8283
          (%o3)  (------- - ------- - ------ + ----) charfun2(x, minf, 3)
                   3288      1096      3288    1096
                      3         2
                2587 x    5174 x    494117 x   108928
           + (- ------- + ------- - -------- + ------) charfun2(x, 7, inf)
                 1644       137       1644      137
                    3          2
              4715 x    15209 x    579277 x   199575
           + (------- - -------- + -------- - ------) charfun2(x, 6, 7)
               1644       274        1644      274
                      3         2
                3287 x    2223 x    48275 x   9609
           + (- ------- + ------- - ------- + ----) charfun2(x, 3, 6)
                 4932       274      1644     274

          (%i4) f(x):=''%$
          (%i5) /* Some evaluations */
                map(f,[2.3,5/7,%pi]), numer;
          (%o5) [1.991460766423356, 5.823200187269903, 2.227405312429507]
          (%i6) load(draw)$  /* load draw package */
          (%i7) /* Plotting interpolating function */
                draw2d(
                  color      = red,
                  key        = "Cubic splines",
                  explicit(f(x),x,0,10),
                  point_size = 3,
                  color      = blue,
                  key        = "Sample points",
                  points(p))$
          (%i8) /* New call, but giving values at the derivatives */
                cspline(p,d1=0,dn=0);
                        3          2
                  1949 x    11437 x    17027 x   1247
          (%o8)  (------- - -------- + ------- + ----) charfun2(x, minf, 3)
                   2256       2256      2256     752
                      3          2
                1547 x    35581 x    68068 x   173546
           + (- ------- + -------- - ------- + ------) charfun2(x, 7, inf)
                  564       564        141      141
                   3          2
              607 x    35147 x    55706 x   38420
           + (------ - -------- + ------- - -----) charfun2(x, 6, 7)
               188       564        141      47
                      3         2
                3895 x    1807 x    5146 x   2148
           + (- ------- + ------- - ------ + ----) charfun2(x, 3, 6)
                 5076       188      141      47
          (%i8) /* Defining new interpolating function */
                g(x):=''%$
          (%i9) /* Plotting both functions together */
                draw2d(
                  color      = black,
                  key        = "Cubic splines (default)",
                  explicit(f(x),x,0,10),
                  color      = red,
                  key        = "Cubic splines (d1=0,dn=0)",
                  explicit(g(x),x,0,10),
                  point_size = 3,
                  color      = blue,
                  key        = "Sample points",
                  points(p))$


 -- Function: ratinterpol (<points>, <numdeg>)
 -- Function: ratinterpol (<points>, <numdeg>, <option1>, <option2>,
          ...)
     Generates a rational interpolator for data given by <points> and
     the degree of the numerator being equal to <numdeg>; the degree of
     the denominator is calculated automatically. Argument <points>
     must be either:

        * a two column matrix, `p:matrix([2,4],[5,6],[9,3])',

        * a list of pairs, `p: [[2,4],[5,6],[9,3]]',

        * a list of numbers, `p: [4,6,3]', in which case the abscissas
          will be assigned automatically to 1, 2, 3, etc.

     In the first two cases the pairs are ordered with respect to the
     first coordinate before making computations.

     There are two options to fit specific needs:
        * `'denterm', default `1', is the independent term of the
          polynomial in the denominator.

        * `'varname', default `'x', is the name of the independent
          variable.

     Examples:

          (%i1) load(interpol)$
          (%i2) load(draw)$
          (%i3) p:[[7.2,2.5],[8.5,2.1],[1.6,5.1],[3.4,2.4],[6.7,7.9]]$
          (%i4) for k:0 thru length(p)-1 do
                  draw2d(
                    explicit(ratinterpol(p,k),x,0,9),
                    point_size = 3,
                    points(p),
                    title = concat("Degree of numerator = ",k),
                    yrange=[0,10])$



File: maxima.info,  Node: lapack,  Next: lbfgs,  Prev: interpol,  Up: Top

58 lapack
*********

* Menu:

* Introduction to lapack::
* Functions and Variables for lapack::


File: maxima.info,  Node: Introduction to lapack,  Next: Functions and Variables for lapack,  Prev: lapack,  Up: lapack

58.1 Introduction to lapack
===========================

`lapack' is a Common Lisp translation (via the program `f2c') of the
Fortran library LAPACK, as obtained from the SLATEC project.


File: maxima.info,  Node: Functions and Variables for lapack,  Prev: Introduction to lapack,  Up: lapack

58.2 Functions and Variables for lapack
=======================================

 -- Function: dgeev (<A>)
 -- Function: dgeev (<A>, <right_p>, <left_p>)
     Computes the eigenvalues and, optionally, the eigenvectors of a
     matrix <A>.  All elements of <A> must be integer or floating point
     numbers.  <A> must be square (same number of rows and columns).
     <A> might or might not be symmetric.

     `dgeev(<A>)' computes only the eigenvalues of <A>.  `dgeev(<A>,
     <right_p>, <left_p>)' computes the eigenvalues of <A> and the
     right eigenvectors when <right_p> = `true' and the left
     eigenvectors when <left_p> = `true'.

     A list of three items is returned.  The first item is a list of
     the eigenvalues.  The second item is `false' or the matrix of
     right eigenvectors.  The third item is `false' or the matrix of
     left eigenvectors.

     The right eigenvector v(j) (the j-th column of the right
     eigenvector matrix) satisfies

     A . v(j) = lambda(j) . v(j)

     where lambda(j) is the corresponding eigenvalue.  The left
     eigenvector u(j) (the j-th column of the left eigenvector matrix)
     satisfies

     u(j)**H . A = lambda(j) . u(j)**H

     where u(j)**H denotes the conjugate transpose of u(j).  The Maxima
     function `ctranspose' computes the conjugate transpose.

     The computed eigenvectors are normalized to have Euclidean norm
     equal to 1, and largest component has imaginary part equal to zero.

     Example:

          (%i1) load (lapack)$
          (%i2) fpprintprec : 6;
          (%o2)                           6
          (%i3) M : matrix ([9.5, 1.75], [3.25, 10.45]);
                                   [ 9.5   1.75  ]
          (%o3)                    [             ]
                                   [ 3.25  10.45 ]
          (%i4) dgeev (M);
          (%o4)          [[7.54331, 12.4067], false, false]
          (%i5) [L, v, u] : dgeev (M, true, true);
                                     [ - .666642  - .515792 ]
          (%o5) [[7.54331, 12.4067], [                      ],
                                     [  .745378   - .856714 ]
                                                  [ - .856714  - .745378 ]
                                                  [                      ]]
                                                  [  .515792   - .666642 ]
          (%i6) D : apply (diag_matrix, L);
                                [ 7.54331     0    ]
          (%o6)                 [                  ]
                                [    0     12.4067 ]
          (%i7) M . v - v . D;
                          [      0.0       - 8.88178E-16 ]
          (%o7)           [                              ]
                          [ - 8.88178E-16       0.0      ]
          (%i8) transpose (u) . M - D . transpose (u);
                               [ 0.0  - 4.44089E-16 ]
          (%o8)                [                    ]
                               [ 0.0       0.0      ]


 -- Function: dgesvd (<A>)
 -- Function: dgesvd (<A>, <left_p>, <right_p>)
     Computes the singular value decomposition (SVD) of a matrix <A>,
     comprising the singular values and, optionally, the left and right
     singular vectors.  All elements of <A> must be integer or floating
     point numbers.  <A> might or might not be square (same number of
     rows and columns).

     Let m be the number of rows, and n the number of columns of <A>.
     The singular value decomposition of <A> comprises three matrices,
     <U>, <Sigma>, and <V^T>, such that

     <A> = <U> . <Sigma> . <V>^T

     where <U> is an m-by-m unitary matrix, <Sigma> is an m-by-n
     diagonal matrix, and <V^T> is an n-by-n unitary matrix.

     Let sigma[i] be a diagonal element of Sigma, that is, <Sigma>[i,
     i] = <sigma>[i].  The elements sigma[i] are the so-called singular
     values of <A>; these are real and nonnegative, and returned in
     descending order.  The first min(m, n) columns of <U> and <V> are
     the left and right singular vectors of <A>.  Note that `dgesvd'
     returns the transpose of <V>, not <V> itself.

     `dgesvd(<A>)' computes only the singular values of <A>.
     `dgesvd(<A>, <left_p>, <right_p>)' computes the singular values of
     <A> and the left singular vectors when <left_p> = `true' and the
     right singular vectors when <right_p> = `true'.

     A list of three items is returned.  The first item is a list of
     the singular values.  The second item is `false' or the matrix of
     left singular vectors.  The third item is `false' or the matrix of
     right singular vectors.

     Example:

          (%i1) load (lapack)$
          (%i2) fpprintprec : 6;
          (%o2)                           6
          (%i3) M: matrix([1, 2, 3], [3.5, 0.5, 8], [-1, 2, -3], [4, 9, 7]);
                                  [  1    2    3  ]
                                  [               ]
                                  [ 3.5  0.5   8  ]
          (%o3)                   [               ]
                                  [ - 1   2   - 3 ]
                                  [               ]
                                  [  4    9    7  ]
          (%i4) dgesvd (M);
          (%o4)      [[14.4744, 6.38637, .452547], false, false]
          (%i5) [sigma, U, VT] : dgesvd (M, true, true);
          (%o5) [[14.4744, 6.38637, .452547],
          [ - .256731  .00816168   .959029    - .119523 ]
          [                                             ]
          [ - .526456   .672116   - .206236   - .478091 ]
          [                                             ],
          [  .107997   - .532278  - .0708315  - 0.83666 ]
          [                                             ]
          [ - .803287  - .514659  - .180867    .239046  ]
          [ - .374486  - .538209  - .755044 ]
          [                                 ]
          [  .130623   - .836799   0.5317   ]]
          [                                 ]
          [ - .917986   .100488    .383672  ]
          (%i6) m : length (U);
          (%o6)                           4
          (%i7) n : length (VT);
          (%o7)                           3
          (%i8) Sigma:
                  genmatrix(lambda ([i, j], if i=j then sigma[i] else 0),
                            m, n);
                            [ 14.4744     0        0    ]
                            [                           ]
                            [    0     6.38637     0    ]
          (%o8)             [                           ]
                            [    0        0     .452547 ]
                            [                           ]
                            [    0        0        0    ]
          (%i9) U . Sigma . VT - M;
                    [  1.11022E-15        0.0       1.77636E-15 ]
                    [                                           ]
                    [  1.33227E-15    1.66533E-15       0.0     ]
          (%o9)     [                                           ]
                    [ - 4.44089E-16  - 8.88178E-16  4.44089E-16 ]
                    [                                           ]
                    [  8.88178E-16    1.77636E-15   8.88178E-16 ]
          (%i10) transpose (U) . U;
                 [     1.0      5.55112E-17    2.498E-16     2.77556E-17  ]
                 [                                                        ]
                 [ 5.55112E-17      1.0       5.55112E-17    4.16334E-17  ]
          (%o10) [                                                        ]
                 [  2.498E-16   5.55112E-17       1.0       - 2.08167E-16 ]
                 [                                                        ]
                 [ 2.77556E-17  4.16334E-17  - 2.08167E-16       1.0      ]
          (%i11) VT . transpose (VT);
                    [      1.0           0.0      - 5.55112E-17 ]
                    [                                           ]
          (%o11)    [      0.0           1.0       5.55112E-17  ]
                    [                                           ]
                    [ - 5.55112E-17  5.55112E-17       1.0      ]


 -- Function: dlange (<norm>, <A>)
 -- Function: zlange (<norm>, <A>)
     Computes a norm or norm-like function of the matrix <A>.

    `max'
          Compute max(abs(A(i, j))) where i and j range over the rows
          and columns, respectively, of <A>.  Note that this function
          is not a proper matrix norm.

    `one_norm'
          Compute the L[1] norm of <A>, that is, the maximum of the sum
          of the absolute value of elements in each column.

    `inf_norm'
          Compute the L[inf] norm of <A>, that is, the maximum of the
          sum of the absolute value of elements in each row.

    `frobenius'
          Compute the Frobenius norm of <A>, that is, the square root
          of the sum of squares of the matrix elements.



File: maxima.info,  Node: lbfgs,  Next: lindstedt,  Prev: lapack,  Up: Top

59 lbfgs
********

* Menu:

* Introduction to lbfgs::
* Functions and Variables for lbfgs::


File: maxima.info,  Node: Introduction to lbfgs,  Next: Functions and Variables for lbfgs,  Prev: Top,  Up: Top

59.1 Introduction to lbfgs
==========================

`lbfgs' is an implementation of the L-BFGS algorithm [1] to solve
unconstrained minimization problems via a limited-memory quasi-Newton
(BFGS) algorithm.  It is called a limited-memory method because a
low-rank approximation of the Hessian matrix inverse is stored instead
of the entire Hessian inverse.  The program was originally written in
Fortran [2] by Jorge Nocedal, incorporating some functions originally
written by Jorge J. More' and David J. Thuente, and translated into
Lisp automatically via the program `f2cl'.  The Maxima package `lbfgs'
comprises the translated code plus an interface function which manages
some details.

   References:

   [1] D. Liu and J. Nocedal. "On the limited memory BFGS method for
large scale optimization". Mathematical Programming B 45:503-528 (1989)

   [2] `http://netlib.org/opt/lbfgs_um.shar'


File: maxima.info,  Node: Functions and Variables for lbfgs,  Prev: Introduction to lbfgs,  Up: Top

59.2 Functions and Variables for lbfgs
======================================

 -- Function: lbfgs (<FOM>, <X>, <X0>, <epsilon>, <iprint>)
     Finds an approximate solution of the unconstrained minimization of
     the figure of merit <FOM> over the list of variables <X>, starting
     from initial estimates <X0>, such that norm grad FOM < epsilon
     max(1, norm X).

     The algorithm applied is a limited-memory quasi-Newton (BFGS)
     algorithm [1].  It is called a limited-memory method because a
     low-rank approximation of the Hessian matrix inverse is stored
     instead of the entire Hessian inverse.  Each iteration of the
     algorithm is a line search, that is, a search along a ray in the
     variables <X>, with the search direction computed from the
     approximate Hessian inverse.  The FOM is always decreased by a
     successful line search.  Usually (but not always) the norm of the
     gradient of FOM also decreases.

     <iprint> controls progress messages printed by `lbfgs'.

    `iprint[1]'
          `<iprint>[1]' controls the frequency of progress messages.
         `iprint[1] < 0'
               No progress messages.

         `iprint[1] = 0'
               Messages at the first and last iterations.

         `iprint[1] > 0'
               Print a message every `<iprint>[1]' iterations.

    `iprint[2]'
          `<iprint>[2]' controls the verbosity of progress messages.
         `iprint[2] = 0'
               Print out iteration count, number of evaluations of
               <FOM>, value of <FOM>, norm of the gradient of <FOM>,
               and step length.

         `iprint[2] = 1'
               Same as `<iprint>[2] = 0', plus <X0> and the gradient of
               <FOM> evaluated at <X0>.

         `iprint[2] = 2'
               Same as `<iprint>[2] = 1', plus values of <X> at each
               iteration.

         `iprint[2] = 3'
               Same as `<iprint>[2] = 2', plus the gradient of <FOM> at
               each iteration.

     The columns printed by `lbfgs' are the following.

    `I'
          Number of iterations. It is incremented for each line search.

    `NFN'
          Number of evaluations of the figure of merit.

    `FUNC'
          Value of the figure of merit at the end of the most recent
          line search.

    `GNORM'
          Norm of the gradient of the figure of merit at the end of the
          most recent line search.

    `STEPLENGTH'
          An internal parameter of the search algorithm.

     Additional information concerning details of the algorithm are
     found in the comments of the original Fortran code [2].

     See also `lbfgs_nfeval_max' and `lbfgs_ncorrections'.

     References:

     [1] D. Liu and J. Nocedal. "On the limited memory BFGS method for
     large scale optimization". Mathematical Programming B 45:503-528
     (1989)

     [2] `http://netlib.org/opt/lbfgs_um.shar'

     Examples:

     The same FOM as computed by FGCOMPUTE in the program sdrive.f in
     the LBFGS package from Netlib.  Note that the variables in
     question are subscripted variables.  The FOM has an exact minimum
     equal to zero at u[k] = 1 for k = 1, ..., 8.

          (%i1) load (lbfgs);
          (%o1)   /usr/share/maxima/5.10.0cvs/share/lbfgs/lbfgs.mac
          (%i2) t1[j] := 1 - u[j];
          (%o2)                     t1  := 1 - u
                                      j         j
          (%i3) t2[j] := 10*(u[j + 1] - u[j]^2);
                                                    2
          (%o3)                t2  := 10 (u      - u )
                                 j         j + 1    j
          (%i4) n : 8;
          (%o4)                           8
          (%i5) FOM : sum (t1[2*j - 1]^2 + t2[2*j - 1]^2, j, 1, n/2);
                           2 2           2              2 2           2
          (%o5) 100 (u  - u )  + (1 - u )  + 100 (u  - u )  + (1 - u )
                      8    7           7           6    5           5
                               2 2           2              2 2           2
                  + 100 (u  - u )  + (1 - u )  + 100 (u  - u )  + (1 - u )
                          4    3           3           2    1           1
          (%i6) lbfgs (FOM, '[u[1],u[2],u[3],u[4],u[5],u[6],u[7],u[8]],
                 [-1.2, 1, -1.2, 1, -1.2, 1, -1.2, 1], 1e-3, [1, 0]);
          *************************************************
            N=    8   NUMBER OF CORRECTIONS=25
                 INITIAL VALUES
           F=  9.680000000000000D+01   GNORM=  4.657353755084532D+02
          *************************************************

           I NFN   FUNC                    GNORM                   STEPLENGTH

           1   3   1.651479526340304D+01   4.324359291335977D+00   7.926153934390631D-04
           2   4   1.650209316638371D+01   3.575788161060007D+00   1.000000000000000D+00
           3   5   1.645461701312851D+01   6.230869903601577D+00   1.000000000000000D+00
           4   6   1.636867301275588D+01   1.177589920974980D+01   1.000000000000000D+00
           5   7   1.612153014409201D+01   2.292797147151288D+01   1.000000000000000D+00
           6   8   1.569118407390628D+01   3.687447158775571D+01   1.000000000000000D+00
           7   9   1.510361958398942D+01   4.501931728123680D+01   1.000000000000000D+00
           8  10   1.391077875774294D+01   4.526061463810632D+01   1.000000000000000D+00
           9  11   1.165625686278198D+01   2.748348965356917D+01   1.000000000000000D+00
          10  12   9.859422687859137D+00   2.111494974231644D+01   1.000000000000000D+00
          11  13   7.815442521732281D+00   6.110762325766556D+00   1.000000000000000D+00
          12  15   7.346380905773160D+00   2.165281166714631D+01   1.285316401779533D-01
          13  16   6.330460634066370D+00   1.401220851762050D+01   1.000000000000000D+00
          14  17   5.238763939851439D+00   1.702473787613255D+01   1.000000000000000D+00
          15  18   3.754016790406701D+00   7.981845727704576D+00   1.000000000000000D+00
          16  20   3.001238402309352D+00   3.925482944716691D+00   2.333129631296807D-01
          17  22   2.794390709718290D+00   8.243329982546473D+00   2.503577283782332D-01
          18  23   2.563783562918759D+00   1.035413426521790D+01   1.000000000000000D+00
          19  24   2.019429976377856D+00   1.065187312346769D+01   1.000000000000000D+00
          20  25   1.428003167670903D+00   2.475962450826961D+00   1.000000000000000D+00
          21  27   1.197874264861340D+00   8.441707983493810D+00   4.303451060808756D-01
          22  28   9.023848941942773D-01   1.113189216635162D+01   1.000000000000000D+00
          23  29   5.508226405863770D-01   2.380830600326308D+00   1.000000000000000D+00
          24  31   3.902893258815567D-01   5.625595816584421D+00   4.834988416524465D-01
          25  32   3.207542206990315D-01   1.149444645416472D+01   1.000000000000000D+00
          26  33   1.874468266362791D-01   3.632482152880997D+00   1.000000000000000D+00
          27  34   9.575763380706598D-02   4.816497446154354D+00   1.000000000000000D+00
          28  35   4.085145107543406D-02   2.087009350166495D+00   1.000000000000000D+00
          29  36   1.931106001379290D-02   3.886818608498966D+00   1.000000000000000D+00
          30  37   6.894000721499670D-03   3.198505796342214D+00   1.000000000000000D+00
          31  38   1.443296033051864D-03   1.590265471025043D+00   1.000000000000000D+00
          32  39   1.571766603154336D-04   3.098257063980634D-01   1.000000000000000D+00
          33  40   1.288011776581970D-05   1.207784183577257D-02   1.000000000000000D+00
          34  41   1.806140173752971D-06   4.587890233385193D-02   1.000000000000000D+00
          35  42   1.769004645459358D-07   1.790537375052208D-02   1.000000000000000D+00
          36  43   3.312164100763217D-10   6.782068426119681D-04   1.000000000000000D+00


           THE MINIMIZATION TERMINATED WITHOUT DETECTING ERRORS.
           IFLAG = 0
          (%o6) [u  = 1.000005339815974, u  = 1.000009942839805,
                  1                       2
          u  = 1.000005339815974, u  = 1.000009942839805,
           3                       4
          u  = 1.000005339815974, u  = 1.000009942839805,
           5                       6
          u  = 1.000005339815974, u  = 1.000009942839805]
           7                       8

     A regression problem.  The FOM is the mean square difference
     between the predicted value F(X[i]) and the observed value Y[i].
     The function F is a bounded monotone function (a so-called
     "sigmoidal" function).  In this example, `lbfgs' computes
     approximate values for the parameters of F and `plot2d' displays a
     comparison of F with the observed data.

          (%i1) load (lbfgs);
          (%o1)   /usr/share/maxima/5.10.0cvs/share/lbfgs/lbfgs.mac
          (%i2) FOM : '((1/length(X))*sum((F(X[i]) - Y[i])^2, i, 1,
                                                          length(X)));
                                         2
                         sum((F(X ) - Y ) , i, 1, length(X))
                                 i     i
          (%o2)          -----------------------------------
                                      length(X)
          (%i3) X : [1, 2, 3, 4, 5];
          (%o3)                    [1, 2, 3, 4, 5]
          (%i4) Y : [0, 0.5, 1, 1.25, 1.5];
          (%o4)                [0, 0.5, 1, 1.25, 1.5]
          (%i5) F(x) := A/(1 + exp(-B*(x - C)));
                                             A
          (%o5)            F(x) := ----------------------
                                   1 + exp((- B) (x - C))
          (%i6) ''FOM;
                          A               2            A                2
          (%o6) ((----------------- - 1.5)  + (----------------- - 1.25)
                    - B (5 - C)                  - B (4 - C)
                  %e            + 1            %e            + 1
                      A             2            A               2
           + (----------------- - 1)  + (----------------- - 0.5)
                - B (3 - C)                - B (2 - C)
              %e            + 1          %e            + 1
                       2
                      A
           + --------------------)/5
                - B (1 - C)     2
             (%e            + 1)
          (%i7) estimates : lbfgs (FOM, '[A, B, C], [1, 1, 1], 1e-4, [1, 0]);
          *************************************************
            N=    3   NUMBER OF CORRECTIONS=25
                 INITIAL VALUES
           F=  1.348738534246918D-01   GNORM=  2.000215531936760D-01
          *************************************************

          I  NFN  FUNC                    GNORM                   STEPLENGTH
          1    3  1.177820636622582D-01   9.893138394953992D-02   8.554435968992371D-01
          2    6  2.302653892214013D-02   1.180098521565904D-01   2.100000000000000D+01
          3    8  1.496348495303005D-02   9.611201567691633D-02   5.257340567840707D-01
          4    9  7.900460841091139D-03   1.325041647391314D-02   1.000000000000000D+00
          5   10  7.314495451266917D-03   1.510670810312237D-02   1.000000000000000D+00
          6   11  6.750147275936680D-03   1.914964958023047D-02   1.000000000000000D+00
          7   12  5.850716021108205D-03   1.028089194579363D-02   1.000000000000000D+00
          8   13  5.778664230657791D-03   3.676866074530332D-04   1.000000000000000D+00
          9   14  5.777818823650782D-03   3.010740179797255D-04   1.000000000000000D+00


           THE MINIMIZATION TERMINATED WITHOUT DETECTING ERRORS.
           IFLAG = 0
          (%o7) [A = 1.461933911464101, B = 1.601593973254802,
                                                     C = 2.528933072164854]
          (%i8) plot2d ([F(x), [discrete, X, Y]], [x, -1, 6]), ''estimates;
          (%o8)


 -- Variable: lbfgs_nfeval_max
     Default value: 100

     `lbfgs_nfeval_max' is the maximum number of evaluations of the
     figure of merit (FOM) in `lbfgs'.  When `lbfgs_nfeval_max' is
     reached, `lbfgs' returns the result of the last successful line
     search.


 -- Variable: lbfgs_ncorrections
     Default value: 25

     `lbfgs_ncorrections' is the number of corrections applied to the
     approximate inverse Hessian matrix which is maintained by `lbfgs'.



File: maxima.info,  Node: lindstedt,  Next: linearalgebra,  Prev: lbfgs,  Up: Top

60 lindstedt
************

* Menu:

* Functions and Variables for lindstedt::


File: maxima.info,  Node: Functions and Variables for lindstedt,  Prev: lindstedt,  Up: lindstedt

60.1 Functions and Variables for lindstedt
==========================================

 -- Function: Lindstedt (<eq>,<pvar>,<torder>,<ic>)
     This is a first pass at a Lindstedt code.  It can solve problems
     with initial conditions entered, which can be arbitrary constants,
     (just not <%k1> and <%k2>) where the initial conditions on the
     perturbation equations are z[i]=0, z'[i]=0 for i>0. <ic> is the
     list of initial conditions.

     Problems occur when initial conditions are not given, as the
     constants in the perturbation equations are the same as the zero
     order equation solution.  Also, problems occur when the initial
     conditions for the perturbation equations are not z[i]=0, z'[i]=0
     for i>0, such as the Van der Pol equation.

     Example:
          (%i1) load("makeOrders")$

          (%i2) load("lindstedt")$

          (%i3) Lindstedt('diff(x,t,2)+x-(e*x^3)/6,e,2,[1,0]);
                    2
                   e  (cos(5 T) - 24 cos(3 T) + 23 cos(T))
          (%o3) [[[---------------------------------------
                                    36864
             e (cos(3 T) - cos(T))
           - --------------------- + cos(T)],
                      192
                    2
                 7 e    e
          T = (- ---- - -- + 1) t]]
                 3072   16

     To use this function write first `load("makeOrders")' and
     `load("lindstedt")'.



File: maxima.info,  Node: linearalgebra,  Next: lsquares,  Prev: lindstedt,  Up: Top

61 linearalgebra
****************

* Menu:

* Introduction to linearalgebra::
* Functions and Variables for linearalgebra::


File: maxima.info,  Node: Introduction to linearalgebra,  Next: Functions and Variables for linearalgebra,  Prev: linearalgebra,  Up: linearalgebra

61.1 Introduction to linearalgebra
==================================

`linearalgebra' is a collection of functions for linear algebra.

   Example:

     (%i1) M : matrix ([1, 2], [1, 2]);
                                 [ 1  2 ]
     (%o1)                       [      ]
                                 [ 1  2 ]
     (%i2) nullspace (M);
                                    [  1  ]
                                    [     ]
     (%o2)                     span([   1 ])
                                    [ - - ]
                                    [   2 ]
     (%i3) columnspace (M);
                                     [ 1 ]
     (%o3)                      span([   ])
                                     [ 1 ]
     (%i4) ptriangularize (M - z*ident(2), z);
                              [ 1   2 - z   ]
     (%o4)                    [             ]
                              [           2 ]
                              [ 0  3 z - z  ]
     (%i5) M : matrix ([1, 2, 3], [4, 5, 6], [7, 8, 9]) - z*ident(3);
                          [ 1 - z    2      3   ]
                          [                     ]
     (%o5)                [   4    5 - z    6   ]
                          [                     ]
                          [   7      8    9 - z ]
     (%i6) MM : ptriangularize (M, z);
                   [ 4  5 - z            6            ]
                   [                                  ]
                   [                2                 ]
                   [     66        z    102 z   132   ]
                   [ 0   --      - -- + ----- + ---   ]
     (%o6)         [     49        7     49     49    ]
                   [                                  ]
                   [               3        2         ]
                   [           49 z    245 z    147 z ]
                   [ 0    0    ----- - ------ - ----- ]
                   [            264      88      44   ]
     (%i7) algebraic : true;
     (%o7)                         true
     (%i8) tellrat (MM [3, 3]);
                              3       2
     (%o8)                  [z  - 15 z  - 18 z]
     (%i9) MM : ratsimp (MM);
                    [ 4  5 - z           6           ]
                    [                                ]
                    [                2               ]
     (%o9)          [     66      7 z  - 102 z - 132 ]
                    [ 0   --    - ------------------ ]
                    [     49              49         ]
                    [                                ]
                    [ 0    0             0           ]
     (%i10) nullspace (MM);
                             [        1         ]
                             [                  ]
                             [   2              ]
                             [  z  - 14 z - 16  ]
                             [  --------------  ]
     (%o10)             span([        8         ])
                             [                  ]
                             [    2             ]
                             [   z  - 18 z - 12 ]
                             [ - -------------- ]
                             [         12       ]
     (%i11) M : matrix ([1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12],
                        [13, 14, 15, 16]);
                            [ 1   2   3   4  ]
                            [                ]
                            [ 5   6   7   8  ]
     (%o11)                 [                ]
                            [ 9   10  11  12 ]
                            [                ]
                            [ 13  14  15  16 ]
     (%i12) columnspace (M);
                                [ 1  ]  [ 2  ]
                                [    ]  [    ]
                                [ 5  ]  [ 6  ]
     (%o12)                span([    ], [    ])
                                [ 9  ]  [ 10 ]
                                [    ]  [    ]
                                [ 13 ]  [ 14 ]
     (%i13) apply ('orthogonal_complement, args (nullspace (transpose (M))));
                                [ 0 ]  [  1  ]
                                [   ]  [     ]
                                [ 1 ]  [  0  ]
     (%o13)                span([   ], [     ])
                                [ 2 ]  [ - 1 ]
                                [   ]  [     ]
                                [ 3 ]  [ - 2 ]


File: maxima.info,  Node: Functions and Variables for linearalgebra,  Prev: Introduction to linearalgebra,  Up: linearalgebra

61.2 Functions and Variables for linearalgebra
==============================================

 -- Function: addmatrices (<f>, <M_1>, ..., <M_n>)
     Using the function <f> as the addition function, return the sum of
     the matrices <M_1>, ..., <M_n>. The function <f> must accept any
     number of arguments (a Maxima nary function).

     Examples:

          (%i1) m1 : matrix([1,2],[3,4])$
          (%i2) m2 : matrix([7,8],[9,10])$
          (%i3) addmatrices('max,m1,m2);
          (%o3) matrix([7,8],[9,10])
          (%i4) addmatrices('max,m1,m2,5*m1);
          (%o4) matrix([7,10],[15,20])


 -- Function: blockmatrixp (<M>)
     Return true if and only if <M> is a matrix and every entry of <M>
     is a matrix.


 -- Function: columnop (<M>, <i>, <j>, <theta>)
     If <M> is a matrix, return the matrix that results from doing the
     column operation `C_i <- C_i - <theta> * C_j'. If <M> doesn't have
     a row <i> or <j>, signal an error.


 -- Function: columnswap (<M>, <i>, <j>)
     If <M> is a matrix, swap columns <i> and <j>.  If <M> doesn't have
     a column <i> or <j>, signal an error.


 -- Function: columnspace (<M>)
     If <M> is a matrix, return `span (v_1, ..., v_n)', where the set
     `{v_1, ..., v_n}' is a basis for the column space of <M>.  The span
     of the empty set is `{0}'. Thus, when the column space has only
     one member, return `span ()'.


 -- Function: copy (<e>)
     Return a copy of the Maxima expression <e>. Although <e> can be any
     Maxima expression, the copy function is the most useful when <e>
     is either a list or a matrix; consider:
          (%i1) m : [1,[2,3]]$
          (%i2) mm : m$
          (%i3) mm[2][1] : x$
          (%i4) m;
          (%o4)                      [1,[x,3]]
          (%i5) mm;
          (%o5)                      [1,[x,3]]
     Let's try the same experiment, but this time let <mm> be a copy of
     <m>
          (%i6) m : [1,[2,3]]$
          (%i7) mm : copy(m)$
          (%i8) mm[2][1] : x$
          (%i9) m;
          (%o9)                     [1,[2,3]]
          (%i10) mm;
          (%o10)                    [1,[x,3]]
     This time, the assignment to <mm> does not change the value of <m>.


 -- Function: cholesky (<M>)
 -- Function: cholesky (<M>, <field>)
     Return the Cholesky factorization of the matrix selfadjoint (or
     hermitian) matrix <M>. The second argument defaults to
     'generalring.' For a description of the possible values for
     <field>, see `lu_factor'.


 -- Function: ctranspose (<M>)
     Return the complex conjugate transpose of the matrix <M>. The
     function `ctranspose' uses `matrix_element_transpose' to transpose
     each matrix element.


 -- Function: diag_matrix (<d_1>, <d_2>,...,<d_n>)
     Return a diagonal matrix with diagonal entries <d_1>,
     <d_2>,...,<d_n>.  When the diagonal entries are matrices, the zero
     entries of the returned matrix are zero matrices of the
     appropriate size; for example:
          (%i1) diag_matrix(diag_matrix(1,2),diag_matrix(3,4));

                                      [ [ 1  0 ]  [ 0  0 ] ]
                                      [ [      ]  [      ] ]
                                      [ [ 0  2 ]  [ 0  0 ] ]
          (%o1)                       [                    ]
                                      [ [ 0  0 ]  [ 3  0 ] ]
                                      [ [      ]  [      ] ]
                                      [ [ 0  0 ]  [ 0  4 ] ]
          (%i2) diag_matrix(p,q);

                                             [ p  0 ]
          (%o2)                              [      ]
                                             [ 0  q ]


 -- Function: dotproduct (<u>, <v>)
     Return the dotproduct of vectors <u> and <v>.  This is the same as
     `conjugate (transpose (<u>)) . <v>'.  The arguments <u> and <v>
     must be column vectors.


 -- Function: eigens_by_jacobi (<A>)
 -- Function: eigens_by_jacobi (<A>, <field_type>)
     Computes the eigenvalues and eigenvectors of <A> by the method of
     Jacobi rotations.  <A> must be a symmetric matrix (but it need not
     be positive definite nor positive semidefinite).  <field_type>
     indicates the computational field, either `floatfield' or
     `bigfloatfield'.  If <field_type> is not specified, it defaults to
     `floatfield'.

     The elements of <A> must be numbers or expressions which evaluate
     to numbers via `float' or `bfloat' (depending on <field_type>).

     Examples:

          (%i1) S: matrix([1/sqrt(2), 1/sqrt(2)],[-1/sqrt(2), 1/sqrt(2)]);
                               [     1         1    ]
                               [  -------   ------- ]
                               [  sqrt(2)   sqrt(2) ]
          (%o1)                [                    ]
                               [      1        1    ]
                               [ - -------  ------- ]
                               [   sqrt(2)  sqrt(2) ]
          (%i2) L : matrix ([sqrt(3), 0], [0, sqrt(5)]);
                                [ sqrt(3)     0    ]
          (%o2)                 [                  ]
                                [    0     sqrt(5) ]
          (%i3) M : S . L . transpose (S);
                      [ sqrt(5)   sqrt(3)  sqrt(5)   sqrt(3) ]
                      [ ------- + -------  ------- - ------- ]
                      [    2         2        2         2    ]
          (%o3)       [                                      ]
                      [ sqrt(5)   sqrt(3)  sqrt(5)   sqrt(3) ]
                      [ ------- - -------  ------- + ------- ]
                      [    2         2        2         2    ]
          (%i4) eigens_by_jacobi (M);
          The largest percent change was 0.1454972243679
          The largest percent change was 0.0
          number of sweeps: 2
          number of rotations: 1
          (%o4) [[1.732050807568877, 2.23606797749979],
                                  [  0.70710678118655   0.70710678118655 ]
                                  [                                      ]]
                                  [ - 0.70710678118655  0.70710678118655 ]
          (%i5) float ([[sqrt(3), sqrt(5)], S]);
          (%o5) [[1.732050807568877, 2.23606797749979],
                                  [  0.70710678118655   0.70710678118655 ]
                                  [                                      ]]
                                  [ - 0.70710678118655  0.70710678118655 ]
          (%i6) eigens_by_jacobi (M, bigfloatfield);
          The largest percent change was 1.454972243679028b-1
          The largest percent change was 0.0b0
          number of sweeps: 2
          number of rotations: 1
          (%o6) [[1.732050807568877b0, 2.23606797749979b0],
                          [  7.071067811865475b-1   7.071067811865475b-1 ]
                          [                                              ]]
                          [ - 7.071067811865475b-1  7.071067811865475b-1 ]


 -- Function: get_lu_factors (<x>)
     When `<x> = lu_factor (<A>)', then `get_lu_factors' returns a list
     of the form `[P, L, U]', where <P> is a permutation matrix, <L> is
     lower triangular with ones on the diagonal, and <U> is upper
     triangular, and `<A> = <P> <L> <U>'.


 -- Function: hankel (<col>)
 -- Function: hankel (<col>, <row>)
     Return a Hankel matrix <H>. The first column of <H> is <col>;
     except for the first entry, the last row of <H> is <row>. The
     default for <row> is the zero vector with the same length as <col>.


 -- Function: hessian (<f>, <x>)
     Returns the Hessian matrix of <f> with respect to the list of
     variables <x>.  The `(i, j)'-th element of the Hessian matrix is
     `diff(<f>, <x>[i], 1, <x>[j], 1)'.

     Examples:

          (%i1) hessian (x * sin (y), [x, y]);
                               [   0       cos(y)   ]
          (%o1)                [                    ]
                               [ cos(y)  - x sin(y) ]
          (%i2) depends (F, [a, b]);
          (%o2)                       [F(a, b)]
          (%i3) hessian (F, [a, b]);
                                  [   2      2   ]
                                  [  d F    d F  ]
                                  [  ---   ----- ]
                                  [    2   da db ]
                                  [  da          ]
          (%o3)                   [              ]
                                  [   2      2   ]
                                  [  d F    d F  ]
                                  [ -----   ---  ]
                                  [ da db     2  ]
                                  [         db   ]


 -- Function: hilbert_matrix (<n>)
     Return the <n> by <n> Hilbert matrix. When <n> isn't a positive
     integer, signal an error.


 -- Function: identfor (<M>)
 -- Function: identfor (<M>, <fld>)
     Return an identity matrix that has the same shape as the matrix
     <M>.  The diagonal entries of the identity matrix are the
     multiplicative identity of the field <fld>; the default for <fld>
     is <generalring>.

     The first argument <M> should be a square matrix or a non-matrix.
     When <M> is a matrix, each entry of <M> can be a square matrix -
     thus <M> can be a blocked Maxima matrix. The matrix can be blocked
     to any (finite) depth.

     See also `zerofor'


 -- Function: invert_by_lu (<M>, <(rng generalring)>)
     Invert a matrix <M> by using the LU factorization.  The LU
     factorization is done using the ring <rng>.


 -- Function: jacobian (<f>, <x>)
     Returns the Jacobian matrix of the list of functions <f> with
     respect to the list of variables <x>.  The `(i, j)'-th element of
     the Jacobian matrix is `diff(<f>[i], <x>[j])'.

     Examples:

          (%i1) jacobian ([sin (u - v), sin (u * v)], [u, v]);
                            [ cos(v - u)  - cos(v - u) ]
          (%o1)             [                          ]
                            [ v cos(u v)   u cos(u v)  ]
          (%i2) depends ([F, G], [y, z]);
          (%o2)                  [F(y, z), G(y, z)]
          (%i3) jacobian ([F, G], [y, z]);
                                     [ dF  dF ]
                                     [ --  -- ]
                                     [ dy  dz ]
          (%o3)                      [        ]
                                     [ dG  dG ]
                                     [ --  -- ]
                                     [ dy  dz ]


 -- Function: kronecker_product (<A>, <B>)
     Return the Kronecker product of the matrices <A> and <B>.


 -- Function: listp (<e>, <p>)
 -- Function: listp (<e>)
     Given an optional argument <p>, return `true' if <e> is a Maxima
     list and <p> evaluates to `true' for every list element.  When
     `listp' is not given the optional argument, return `true' if <e> is
     a Maxima list.  In all other cases, return `false'.


 -- Function: locate_matrix_entry (<M>, <r_1>, <c_1>, <r_2>, <c_2>,
          <f>, <rel>)
     The first argument must be a matrix; the arguments <r_1> through
     <c_2> determine a sub-matrix of <M> that consists of rows <r_1>
     through <r_2> and columns <c_1> through <c_2>.

     Find a entry in the sub-matrix <M> that satisfies some property.
     Three cases:

     (1) `<rel> = 'bool' and <f> a predicate:

     Scan the sub-matrix from left to right then top to bottom, and
     return the index of the first entry that satisfies the predicate
     <f>. If no matrix entry satisfies <f>, return `false'.

     (2) `<rel> = 'max' and <f> real-valued:

     Scan the sub-matrix looking for an entry that maximizes <f>.
     Return the index of a maximizing entry.

     (3) `<rel> = 'min' and <f> real-valued:

     Scan the sub-matrix looking for an entry that minimizes <f>.
     Return the index of a minimizing entry.


 -- Function: lu_backsub (<M>, <b>)
     When `<M> = lu_factor (<A>, <field>)', then `lu_backsub (<M>,
     <b>)' solves the linear system `<A> <x> = <b>'.


 -- Function: lu_factor (<M>, <field>)
     Return a list of the form `[<LU>, <perm>, <fld>]', or `[<LU>,
     <perm>, <fld>, <lower-cnd> <upper-cnd>]', where

     (1) The matrix <LU> contains the factorization of <M> in a packed
     form. Packed       form means three things: First, the rows of
     <LU> are permuted according to the       list <perm>.  If, for
     example, <perm> is the list `[3,2,1]', the actual first row
     of the <LU> factorization is the third row of the matrix <LU>.
     Second,       the lower triangular factor of m is the lower
     triangular part of <LU> with the       diagonal entries replaced
     by all ones. Third, the upper triangular factor of       <M> is
     the upper triangular part of <LU>.

     (2) When the field is either `floatfield' or `complexfield',
     the numbers <lower-cnd> and <upper-cnd> are lower and upper bounds
     for the       infinity norm condition number of <M>.  For all
     fields, the condition number       might not be estimated; for
     such fields, `lu_factor' returns a two item list.        Both the
     lower and upper bounds can differ from their true values by
     arbitrarily large factors. (See also `mat_cond'.)

     The argument <M> must be a square matrix.

     The optional argument <fld> must be a symbol that determines a
     ring or field. The pre-defined   fields and rings are:

     (a) `generalring' - the ring of Maxima expressions,     (b)
     `floatfield' -  the field of floating point numbers of the type
     double,     (c) `complexfield' -  the field of complex floating
     point numbers of the         type double,     (d) `crering'  - the
     ring of Maxima CRE expressions,     (e) `rationalfield' - the
     field of rational numbers,     (f) `runningerror' - track the all
     floating point rounding errors,     (g) `noncommutingring' - the
     ring of Maxima expressions where multiplication is the
     non-commutative dot operator.

     When the field is `floatfield', `complexfield', or `runningerror',
     the algorithm uses partial pivoting; for all other fields, rows
     are switched only when needed to avoid a zero pivot.

     Floating point addition arithmetic isn't associative, so the
     meaning of 'field' differs from the mathematical definition.

     A member of the field `runningerror' is a two member Maxima list
     of the form `[x,n]',where <x> is a floating point number and `n'
     is an integer. The relative difference between the 'true' value of
     `x' and `x' is approximately bounded by the machine epsilon times
     `n'. The running error bound drops some terms that of the order
     the square of the machine epsilon.

     There is no user-interface for defining a new field. A user that is
     familiar with Common Lisp should be able to define a new field.
     To do this, a user must define functions for the arithmetic
     operations and functions for converting from the field
     representation to Maxima and back. Additionally, for ordered
     fields (where partial pivoting will be used), a user must define
     functions for the magnitude and for comparing field members.
     After that all that remains is to define a Common Lisp structure
     `mring'.  The file `mring' has many examples.

     To compute the factorization, the first task is to convert each
     matrix entry to a member of the indicated field. When conversion
     isn't possible, the factorization halts with an error message.
     Members of the field needn't be Maxima expressions.  Members of the
     `complexfield', for example, are Common Lisp complex numbers. Thus
     after computing the factorization, the matrix entries must be
     converted to Maxima expressions.

     See also  `get_lu_factors'.

     Examples:

          (%i1) w[i,j] := random (1.0) + %i * random (1.0);
          (%o1)          w     := random(1.) + %i random(1.)
                          i, j
          (%i2) showtime : true$
          Evaluation took 0.00 seconds (0.00 elapsed)
          (%i3) M : genmatrix (w, 100, 100)$
          Evaluation took 7.40 seconds (8.23 elapsed)
          (%i4) lu_factor (M, complexfield)$
          Evaluation took 28.71 seconds (35.00 elapsed)
          (%i5) lu_factor (M, generalring)$
          Evaluation took 109.24 seconds (152.10 elapsed)
          (%i6) showtime : false$

          (%i7) M : matrix ([1 - z, 3], [3, 8 - z]);
                                  [ 1 - z    3   ]
          (%o7)                   [              ]
                                  [   3    8 - z ]
          (%i8) lu_factor (M, generalring);
                    [ 1 - z         3        ]
                    [                        ]
          (%o8)    [[   3            9       ], [1, 2], generalring]
                    [ -----  - z - ----- + 8 ]
                    [ 1 - z        1 - z     ]
          (%i9) get_lu_factors (%);
                            [   1    0 ]  [ 1 - z         3        ]
                  [ 1  0 ]  [          ]  [                        ]
          (%o9)  [[      ], [   3      ], [                9       ]]
                  [ 0  1 ]  [ -----  1 ]  [   0    - z - ----- + 8 ]
                            [ 1 - z    ]  [              1 - z     ]
          (%i10) %[1] . %[2] . %[3];
                                  [ 1 - z    3   ]
          (%o10)                  [              ]
                                  [   3    8 - z ]


 -- Function: mat_cond (<M>, 1)
 -- Function: mat_cond (<M>, inf)
     Return the <p>-norm matrix condition number of the matrix <m>. The
     allowed values for <p> are 1 and <inf>.  This function uses the LU
     factorization to invert the matrix <m>. Thus the running time for
     `mat_cond' is proportional to the cube of the matrix size;
     `lu_factor' determines lower and upper bounds for the infinity
     norm condition number in time proportional to the square of the
     matrix size.


 -- Function: mat_norm (<M>, 1)
 -- Function: mat_norm (<M>, inf)
 -- Function: mat_norm (<M>, frobenius)
     Return the matrix <p>-norm of the matrix <M>.  The allowed values
     for <p> are 1, `inf', and `frobenius' (the Frobenius matrix norm).
     The matrix <M> should be an unblocked matrix.


 -- Function: matrixp (<e>, <p>)
 -- Function: matrixp (<e>)
     Given an optional argument <p>, return `true' if <e> is a matrix
     and <p> evaluates to `true' for every matrix element.  When
     `matrixp' is not given an optional argument, return `true' if `e'
     is a matrix.  In all other cases, return `false'.

     See also `blockmatrixp'


 -- Function: matrix_size (<M>)
     Return a two member list that gives the number of rows and
     columns, respectively of the matrix <M>.


 -- Function: mat_fullunblocker (<M>)
     If <M> is a block matrix, unblock the matrix to all levels. If <M>
     is a matrix, return <M>; otherwise, signal an error.


 -- Function: mat_trace (<M>)
     Return the trace of the matrix <M>. If <M> isn't a matrix, return a
     noun form. When <M> is a block matrix, `mat_trace(M)' returns the
     same value as does `mat_trace(mat_unblocker(m))'.


 -- Function: mat_unblocker (<M>)
     If <M> is a block matrix, unblock <M> one level. If <M> is a
     matrix, `mat_unblocker (M)' returns <M>; otherwise, signal an
     error.

     Thus if each entry of <M> is matrix, `mat_unblocker (M)' returns an
     unblocked matrix, but if each entry of <M> is a block matrix,
     `mat_unblocker (M)' returns a block matrix with one less level of
     blocking.

     If you use block matrices, most likely you'll want to set
     `matrix_element_mult' to `"."' and `matrix_element_transpose' to
     `'transpose'. See also `mat_fullunblocker'.

     Example:

          (%i1) A : matrix ([1, 2], [3, 4]);
                                      [ 1  2 ]
          (%o1)                       [      ]
                                      [ 3  4 ]
          (%i2) B : matrix ([7, 8], [9, 10]);
                                      [ 7  8  ]
          (%o2)                       [       ]
                                      [ 9  10 ]
          (%i3) matrix ([A, B]);
                               [ [ 1  2 ]  [ 7  8  ] ]
          (%o3)                [ [      ]  [       ] ]
                               [ [ 3  4 ]  [ 9  10 ] ]
          (%i4) mat_unblocker (%);
                                   [ 1  2  7  8  ]
          (%o4)                    [             ]
                                   [ 3  4  9  10 ]


 -- Function: nonnegintegerp (<n>)
     Return `true' if and only if `<n> >= 0' and <n> is an integer.


 -- Function: nullspace (<M>)
     If <M> is a matrix, return `span (v_1, ..., v_n)', where the set
     `{v_1, ..., v_n}' is a basis for the nullspace of <M>.  The span
     of the empty set is `{0}'.  Thus, when the nullspace has only one
     member, return `span ()'.


 -- Function: nullity (<M>)
     If <M> is a matrix, return the dimension of the nullspace of <M>.


 -- Function: orthogonal_complement (<v_1>, ..., <v_n>)
     Return `span (u_1, ..., u_m)', where the set `{u_1, ..., u_m}' is a
     basis for the orthogonal complement of the set `(v_1, ..., v_n)'.

     Each vector <v_1> through <v_n> must be a column vector.


 -- Function: polynomialp (<p>, <L>, <coeffp>, <exponp>)
 -- Function: polynomialp (<p>, <L>, <coeffp>)
 -- Function: polynomialp (<p>, <L>)
     Return `true' if <p> is a polynomial in the variables in the list
     <L>, The predicate <coeffp> must evaluate to `true' for each
     coefficient, and the predicate <exponp> must evaluate to `true'
     for all exponents of the variables in <L>. If you want to use a
     non-default value for <exponp>, you must supply <coeffp> with a
     value even if you want to use the default for <coeffp>.

     `polynomialp (<p>, <L>, <coeffp>)' is equivalent to `polynomialp
     (<p>, <L>, <coeffp>, 'nonnegintegerp)'.

     `polynomialp (<p>, <L>)' is equivalent to `polynomialp (<p>, L<,>
     'constantp, 'nonnegintegerp)'.

     The polynomial needn't be expanded:

          (%i1) polynomialp ((x + 1)*(x + 2), [x]);
          (%o1)                         true
          (%i2) polynomialp ((x + 1)*(x + 2)^a, [x]);
          (%o2)                         false

     An example using non-default values for coeffp and exponp:

          (%i1) polynomialp ((x + 1)*(x + 2)^(3/2), [x], numberp, numberp);
          (%o1)                         true
          (%i2) polynomialp ((x^(1/2) + 1)*(x + 2)^(3/2), [x], numberp,
                                                                  numberp);
          (%o2)                         true

     Polynomials with two variables:

          (%i1) polynomialp (x^2 + 5*x*y + y^2, [x]);
          (%o1)                         false
          (%i2) polynomialp (x^2 + 5*x*y + y^2, [x, y]);
          (%o2)                         true


 -- Function: polytocompanion (<p>, <x>)
     If <p> is a polynomial in <x>, return the companion matrix of <p>.
     For a monic polynomial <p> of degree <n>, we have `<p> = (-1)^<n>
     charpoly (polytocompanion (<p>, <x>))'.

     When <p> isn't a polynomial in <x>, signal an error.


 -- Function: ptriangularize (<M>, <v>)
     If <M> is a matrix with each entry a polynomial in <v>, return a
     matrix <M2> such that

     (1) <M2> is upper triangular,

     (2) `<M2> = <E_n> ... <E_1> <M>', where <E_1> through <E_n> are
     elementary matrices whose entries are polynomials in <v>,

     (3) `|det (<M>)| = |det (<M2>)|',

     Note: This function doesn't check that every entry is a polynomial
     in <v>.


 -- Function: rowop (<M>, <i>, <j>, <theta>)
     If <M> is a matrix, return the matrix that results from doing the
     row operation `R_i <- R_i - theta * R_j'. If <M> doesn't have a row
     <i> or <j>, signal an error.


 -- Function: rank (<M>)
     Return the rank of that matrix <M>. The rank is the dimension of
     the column space. Example:
          (%i1) rank(matrix([1,2],[2,4]));
          (%o1)                                  1
          (%i2) rank(matrix([1,b],[c,d]));
          Proviso:  {d - b c # 0}
          (%o2)                                  2


 -- Function: rowswap (<M>, <i>, <j>)
     If <M> is a matrix, swap rows <i> and <j>. If <M> doesn't have a
     row <i> or <j>, signal an error.


 -- Function: toeplitz (<col>)
 -- Function: toeplitz (<col>, <row>)
     Return a Toeplitz matrix <T>. The first first column of <T> is
     <col>; except for the first entry, the first row of <T> is <row>.
     The default for <row> is complex conjugate of <col>. Example:
          (%i1)  toeplitz([1,2,3],[x,y,z]);

                                            [ 1  y  z ]
                                            [         ]
          (%o1)                             [ 2  1  y ]
                                            [         ]
                                            [ 3  2  1 ]
          (%i2)  toeplitz([1,1+%i]);

                                        [   1     1 - %I ]
          (%o2)                         [                ]
                                        [ %I + 1    1    ]


 -- Function: vandermonde_matrix ([<x_1>, ..., <x_n>])
     Return a <n> by <n> matrix whose <i>-th row is `[1, <x_i>,
     <x_i>^2, ... <x_i>^(<n>-1)]'.


 -- Function: zerofor (<M>)
 -- Function: zerofor (<M>, <fld>)
     Return a zero  matrix that has the same shape as the matrix <M>.
     Every entry of the zero matrix is the additive identity of the
     field <fld>; the default for <fld> is <generalring>.

     The first argument <M> should be a square matrix or a non-matrix.
     When <M> is a matrix, each entry of <M> can be a square matrix -
     thus <M> can be a blocked Maxima matrix. The matrix can be blocked
     to any (finite) depth.

     See also `identfor'


 -- Function: zeromatrixp (<M>)
     If <M> is not a block matrix, return `true' if `is (equal (<e>,
     0))' is true for each element <e> of the matrix <M>.  If <M> is a
     block matrix, return `true' if `zeromatrixp' evaluates to `true'
     for each element of <e>.



File: maxima.info,  Node: lsquares,  Next: makeOrders,  Prev: linearalgebra,  Up: Top

62 lsquares
***********

* Menu:

* Introduction to lsquares::
* Functions and Variables for lsquares::


File: maxima.info,  Node: Introduction to lsquares,  Next: Functions and Variables for lsquares,  Prev: lsquares,  Up: lsquares

62.1 Introduction to lsquares
=============================

`lsquares' is a collection of functions to implement the method of
least squares to estimate parameters for a model from numerical data.

