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


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

42.3 Functions and Variables for pictures
=========================================

 -- 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: 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: 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: negative_picture (<pic>)

     Returns the negative of a (<level> or <rgb>) picture.

 -- Function: picture_equalp (<x>,<y>)

     Returns 'true' in case of equal pictures, and 'false' otherwise.

 -- Function: picturep (<x>)

     Returns 'true' if the argument is a well formed image, and 'false'
     otherwise.

 -- Function: read_xpm (<xpm_file>)

     Reads a file in xpm and returns a picture object.

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

 -- 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)})


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

42.4 Functions and Variables for worldmap
=========================================

This package automatically loads package 'draw'.

42.4.1 Variables and Functions
------------------------------

 -- 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'.

 -- 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(worldmap)$
          (%i2) european_borders:
                     region_boundaries(-31.81,74.92,49.84,32.06)$
          (%i3) numbered_boundaries(european_borders)$

 -- 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(worldmap)$
          (%i2) /* A continent */
                make_poly_continent(Africa)$
          (%i3) apply(draw2d, %)$
          (%i4) /* A list of countries */
                make_poly_continent([Germany,Denmark,Poland])$
          (%i5) apply(draw2d, %)$

 -- 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(worldmap)$
          (%i2) make_poly_country(India)$
          (%i3) apply(draw2d, %)$

 -- 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(worldmap)$
          (%i2) Bhutan;
          (%o2)                        [[171, 173, 1143]]
          (%i3) boundaries_array[171];
          (%o3) {Array:
                 #(88.750549 27.14727 88.806351 27.25305 88.901367 27.282221
                   88.917877 27.321039)}
          (%i4) boundaries_array[173];
          (%o4) {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)}
          (%i5) boundaries_array[1143];
          (%o5) {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)}
          (%i6) Bhutan_polygon: make_polygon([171,173,1143])$
          (%i7) draw2d(Bhutan_polygon)$

 -- Function: region_boundaries (<x1>, <y1>, <x2>, <y2>)

     Detects polygonal segments of global variable 'boundaries_array'
     fully 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(worldmap)$
          (%i2) region_boundaries(10.4,41.5,20.7,35.4);
          (%o2)                [1846, 1863, 1864, 1881, 1888, 1894]
          (%i3) draw2d(geomap(%))$

 -- Function: region_boundaries_plus (<x1>, <y1>, <x2>, <y2>)

     Detects polygonal segments of global variable 'boundaries_array'
     containing at least one vertex in the rectangle defined by vertices
     (<x1>, <y1>) -upper left- and (<x2>, <y2>) -bottom right-.

     Example:

          (%i1) load(worldmap)$
          (%i2) region_boundaries_plus(10.4,41.5,20.7,35.4);
          (%o2) [1060, 1062, 1076, 1835, 1839, 1844, 1846, 1858,
                 1861, 1863, 1864, 1871, 1881, 1888, 1894, 1897]
          (%i3) draw2d(geomap(%))$

42.4.2 Graphic objects
----------------------

 -- 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(worldmap)$
          (%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]))$

     The auxiliary package 'worldmap' sets the global variable
     'boundaries_array' to the real world boundaries in coordinates.
     The data is in the public domain and come from
     <http://www-cger.nies.go.jp/grid-e/gridtxt/grid19.html>.  The
     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).  The package 'worldmap' automatically loads package
     'worldmap'.

          (%i1) load(worldmap)$
          (%i2) c1: gr2d(geomap([Canada,United_States,
                                 Mexico,Cuba]))$
          (%i3) c2: gr2d(geomap(Africa))$
          (%i4) c3: gr2d(geomap(Oceania,China,Japan))$
          (%i5) c4: gr2d(geomap([France,Portugal,Spain,
                                 Morocco,Western_Sahara]))$
          (%i6) 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(worldmap)$
          (%i2) 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))$
          (%i3) 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(worldmap)$
               (%i2) 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(worldmap)$
               (%i2) 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(worldmap)$
               (%i2) draw3d(geomap(World_coastlines,
                                   [conic_projection,0,0,0,1,90]))$

     See also <http://riotorto.users.sf.net/gnuplot/geomap> for more
     elaborated examples.


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

43 drawdf
*********

* Menu:

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


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

43.1 Introduction to drawdf
===========================

The function 'drawdf' draws the direction field of a first-order
Ordinary Differential Equation (ODE) or a system of two autonomous
first-order ODE's.

Since this is an additional package, in order to use it you must first
load it with 'load(drawdf)'.  Drawdf is built upon the 'draw' package,
which requires Gnuplot 4.2.

To plot the direction field of a single ODE, the ODE must be written in
the form:
            dy
            -- = F(x,y)
            dx

and the function <F> should be given as the argument for 'drawdf'.  If
the independent and dependent variables are not <x>, and <y>, as in the
equation above, then those two variables should be named explicitly in a
list given as an argument to the drawdf command (see the examples).

To plot the direction field of a set of two autonomous ODE's, they must
be written in the form
            dx             dy
            -- = G(x,y)    -- = F(x,y)
            dt             dt

and the argument for 'drawdf' should be a list with the two functions
<G> and <F>, in that order; namely, the first expression in the list
will be taken to be the time derivative of the variable represented on
the horizontal axis, and the second expression will be the time
derivative of the variable represented on the vertical axis.  Those two
variables do not have to be <x> and <y>, but if they are not, then the
second argument given to drawdf must be another list naming the two
variables, first the one on the horizontal axis and then the one on the
vertical axis.

If only one ODE is given, 'drawdf' will implicitly admit 'x=t', and
'G(x,y)=1', transforming the non-autonomous equation into a system of
two autonomous equations.


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

43.2 Functions and Variables for drawdf
=======================================

43.2.1 Functions
----------------

 -- Function: drawdf (<dydx>, ...options and objects...)
 -- Function: drawdf (<dvdu>, '['<u>,<v>']', ...options and objects...)
 -- Function: drawdf (<dvdu>, '['<u>,<umin>,<umax>']',
          '['<v>,<vmin>,<vmax>']', ...options and objects...)
 -- Function: drawdf ('['<dxdt>,<dydt>']', ...options and objects...)
 -- Function: drawdf ('['<dudt>,<dvdt>']', '['<u>,<v>']', ...options and
          objects...)
 -- Function: drawdf ('['<dudt>,<dvdt>']', '['<u>,<umin>,<umax>']',
          '['<v>,<vmin>,<vmax>']', ...options and objects...)

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

     The first argument specifies the derivative(s), and must be either
     an expression or a list of two expressions.  <dydx>, <dxdt> and
     <dydt> are expressions that depend on <x> and <y>.  <dvdu>, <dudt>
     and <dvdt> are expressions that depend on <u> and <v>.

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

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

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

     The additional graphic objects supported by 'drawdf' include:
     'solns_at', 'points_at', 'saddles_at', 'soln_at', 'point_at', and
     'saddle_at'.

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

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

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

     See also 'draw2d'.

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

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

     Examples:

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

     For backward compatibility, 'drawdf' accepts most of the parameters
     supported by plotdf.

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

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

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

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

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

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

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

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

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

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

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

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

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

     'show_field=false' suppresses the field entirely.

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

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

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

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

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


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

44 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

44.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")'.

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

44.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: 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.

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 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

45 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

45.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.  The convenience function 'known_units' returns a list of the
built-in and user-declared units, while 'display_known_unit_conversions'
displays the set of known conversions in an easy-to-read format.

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' recognizes the prefixes m-, k-, M, and G- (for milli-, kilo-,
mega-, and giga-) as applied to SI base units and SI derived units, but
such prefixes are applied only when indicated by an explicit conversion.

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

45.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 symbols of physical constants persist in evaluated
expressions until their values are fetched by 'constvalue'.

'physical_constants' includes some auxilliary information, namely, 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'.

     (%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;
     Computing conversions to base units; may take a moment.
                          366838848464007200
     (%o5)                ------------------ ` J
                                  9
     (%i6) E `` GJ;
                           458548560580009
     (%o6)                 --------------- ` GJ
                              11250000
     (%i7) float (%);
     (%o7)              4.0759872051556356e+7 ` GJ


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

45.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) load (ezunits)$
          (%i2) foo : 10 ` m;
          (%o2)                        10 ` m
          (%i3) qty (foo);
          (%o3)                          10
          (%i4) units (foo);
          (%o4)                           m
          (%i5) dimensions (foo);
          (%o5)                        length

     "Customary" units.

          (%i1) load (ezunits)$
          (%i2) bar : x ` acre;
          (%o2)                       x ` acre
          (%i3) dimensions (bar);
                                             2
          (%o3)                        length
          (%i4) fundamental_units (bar);
                                          2
          (%o4)                          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*day, baz2);
                                    500   gallon
          (%o5)                     --- ` ------
                                     7     day

     Arithmetic operations on dimensional quantities.

          (%i1) load (ezunits)$
          (%i2) 100 ` kg + 200 ` kg;
          (%o2)                       300 ` kg
          (%i3) 100 ` m^3 - 100 ` m^3;
                                            3
          (%o3)                        0 ` m
          (%i4) (10 ` kg) * (17 ` m/s^2);
                                           kg m
          (%o4)                      170 ` ----
                                             2
                                            s
          (%i5) (x ` m) / (y ` s);
                                        x   m
          (%o5)                         - ` -
                                        y   s
          (%i6) (a ` m)^2;
                                        2    2
          (%o6)                        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*yard^2,Btu = 1055*J,cfm = feet^3/minute,
                 cm = m/100,day = 86400*s,feet = 381*m/1250,ft = feet,
                 g = kg/1000,gallon = 757*l/200,GHz = 1000000000*Hz,
                 GOhm = 1000000000*Ohm,GPa = 1000000000*Pa,
                 GWb = 1000000000*Wb,Gg = 1000000*kg,Gm = 1000000000*m,
                 Gmol = 1000000*mol,Gs = 1000000000*s,ha = hectare,
                 hectare = 100*m^2,hour = 3600*s,Hz = 1/s,inch = feet/12,
                 km = 1000*m,kmol = 1000*mol,ks = 1000*s,l = liter,
                 lbf = pound_force,lbm = pound_mass,liter = m^3/1000,
                 metric_ton = Mg,mg = kg/1000000,MHz = 1000000*Hz,
                 microgram = kg/1000000000,micrometer = m/1000000,
                 micron = micrometer,microsecond = s/1000000,
                 mile = 5280*feet,minute = 60*s,mm = m/1000,
                 mmol = mol/1000,month = 2629800*s,MOhm = 1000000*Ohm,
                 MPa = 1000000*Pa,ms = s/1000,MWb = 1000000*Wb,
                 Mg = 1000*kg,Mm = 1000000*m,Mmol = 1000000000*mol,
                 Ms = 1000000*s,ns = s/1000000000,ounce = pound_mass/16,
                 oz = ounce,Ohm = s*J/C^2,
                 pound_force = 32*ft*pound_mass/s^2,
                 pound_mass = 200*kg/441,psi = pound_force/inch^2,
                 Pa = N/m^2,week = 604800*s,Wb = J/A,yard = 3*feet,
                 year = 31557600*s,C = s*A,F = C^2/J,GA = 1000000000*A,
                 GC = 1000000000*C,GF = 1000000000*F,GH = 1000000000*H,
                 GJ = 1000000000*J,GK = 1000000000*K,GN = 1000000000*N,
                 GS = 1000000000*S,GT = 1000000000*T,GV = 1000000000*V,
                 GW = 1000000000*W,H = J/A^2,J = m*N,kA = 1000*A,
                 kC = 1000*C,kF = 1000*F,kH = 1000*H,kHz = 1000*Hz,
                 kJ = 1000*J,kK = 1000*K,kN = 1000*N,kOhm = 1000*Ohm,
                 kPa = 1000*Pa,kS = 1000*S,kT = 1000*T,kV = 1000*V,
                 kW = 1000*W,kWb = 1000*Wb,mA = A/1000,mC = C/1000,
                 mF = F/1000,mH = H/1000,mHz = Hz/1000,mJ = J/1000,
                 mK = K/1000,mN = N/1000,mOhm = Ohm/1000,mPa = Pa/1000,
                 mS = S/1000,mT = T/1000,mV = V/1000,mW = W/1000,
                 mWb = Wb/1000,MA = 1000000*A,MC = 1000000*C,
                 MF = 1000000*F,MH = 1000000*H,MJ = 1000000*J,
                 MK = 1000000*K,MN = 1000000*N,MS = 1000000*S,
                 MT = 1000000*T,MV = 1000000*V,MW = 1000000*W,
                 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;
          Computing conversions to base units; may take a moment.
                                      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/hour;
                                     720   Btu
          (%o6)                      --- ` ----
                                     211   hour
          (%i7) %, numer;
                                                  Btu
          (%o7)               3.412322274881517 ` ----
                                                  hour
          (%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;
          Computing conversions to base units; may take a moment.
                                     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;
          Computing conversions to base units; may take a moment.
                                  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*hour,
                                         MWh = 1000*kWh, bell = 1800*s);
          (%o3)                         done
          (%i4) 1 ` kW*s `` MWh;
          Computing conversions to base units; may take a moment.
                                       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 these functions.

     Examples:

     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 via 'declare_units', or an expression containing
     either or both of those.

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

     'load(ezunits)' loads these functions.

     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) units (aa);
          (%o2)                           1
          (%i3) declare_units (aa, J);
          (%o3)                           J
          (%i4) units (aa);
          (%o4)                           J
          (%i5) units (aa^2);
                                          2
          (%o5)                          J
          (%i6) foo : 100 ` kg;
          (%o6)                       100 ` kg
          (%i7) units (aa * foo);
          (%o7)                         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 ``.  <u> and <v> are both
     multiplicative terms, in which any variables are units, or both
     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.  This
     limitation might 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 * day);
          (%o2)                         done
          (%i3) 100 ` nautical_mile / fortnight `` m/s;
          Computing conversions to base units; may take a moment.
                                      463    m
          (%o3)                       ---- ` -
                                      3024   s

     Unit conversions expressed by equations of literal dimensional
     expressions.

          (%i1) load (ezunits)$
          (%i2) declare_unit_conversion (1 ` fluid_ounce = 2 ` tablespoon);
          (%o2)                         done
          (%i3) declare_unit_conversion (1 ` tablespoon = 3 ` teaspoon);
          (%o3)                         done
          (%i4) 15 ` fluid_ounce `` teaspoon;
          Computing conversions to base units; may take a moment.
          (%o4)                     90 ` teaspoon

 -- Function: declare_dimensions (<a_1>, <d_1>, ..., <a_n>, <d_n>)
 -- Function: remove_dimensions (<a_1>, ..., <a_n>)

     'declare_dimensions' declares <a_1>, ..., <a_n> to have dimensions
     <d_1>, ..., <d_n>, respectively.

     Each <a_k> is a symbol or a list of symbols.  If it is a list, then
     every symbol in <a_k> is declared to have dimension <d_k>.

     'remove_dimensions' reverts the effect of 'declare_dimensions'.

     'load(ezunits)' loads these functions.

     Examples:

          (%i1) load (ezunits) $
          (%i2) declare_dimensions ([x, y, z], length, [t, u], time);
          (%o2)                         done
          (%i3) dimensions (y^2/u);
                                             2
                                       length
          (%o3)                        -------
                                        time
          (%i4) fundamental_units (y^2/u);
          0 errors, 0 warnings
                                          2
                                         m
          (%o4)                          --
                                         s

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

     'declare_fundamental_dimensions' declares fundamental dimensions.
     Symbols <d_1>, <d_2>, <d_3>, ...  are appended to the list of
     fundamental dimensions, if they are not already on the list.

     'remove_fundamental_dimensions' reverts the effect of
     'declare_fundamental_dimensions'.

     'fundamental_dimensions' is the list of fundamental dimensions.  By
     default, the list comprises several physical dimensions.

     'load(ezunits)' loads these functions.

     Examples:

          (%i1) load (ezunits) $
          (%i2) fundamental_dimensions;
          (%o2) [length, mass, time, current, temperature, quantity]
          (%i3) declare_fundamental_dimensions (money, cattle, happiness);
          (%o3)                         done
          (%i4) fundamental_dimensions;
          (%o4) [length, mass, time, current, temperature, quantity,
                                                  money, cattle, happiness]
          (%i5) remove_fundamental_dimensions (cattle, happiness);
          (%o5)                         done
          (%i6) fundamental_dimensions;
          (%o6) [length, mass, time, current, temperature, quantity, money]

 -- Function: declare_fundamental_units (<u_1>, <d_1>, ..., <u_n>,
          <d_n>)
 -- Function: remove_fundamental_units (<u_1>, ..., <u_n>)

     'declare_fundamental_units' declares <u_1>, ..., <u_n> to have
     dimensions <d_1>, ..., <d_n>, respectively.  All arguments must be
     symbols.

     After calling 'declare_fundamental_units', 'dimensions(<u_k>)'
     returns <d_k> for each argument <u_1>, ..., <u_n>, and
     'fundamental_units(<d_k>)' returns <u_k> for each argument <d_1>,
     ..., <d_n>.

     'remove_fundamental_units' reverts the effect of
     'declare_fundamental_units'.

     'load(ezunits)' loads these functions.

     Examples:

          (%i1) load (ezunits) $
          (%i2) declare_fundamental_dimensions (money, cattle, happiness);
          (%o2)                         done
          (%i3) declare_fundamental_units (dollar, money, goat,
                                           cattle, smile, happiness);
          (%o3)                 [dollar, goat, smile]
          (%i4) dimensions (100 ` dollar/goat/km^2);
                                       money
          (%o4)                    --------------
                                                2
                                   cattle length
          (%i5) dimensions (x ` smile/kg);
                                      happiness
          (%o5)                       ---------
                                        mass
          (%i6) fundamental_units (money*cattle/happiness);
          0 errors, 0 warnings
                                     dollar goat
          (%o6)                      -----------
                                        smile

 -- 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/hour);
                                       acre ft
          (%o3)                        -------
                                        hour
          (%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/hour);
                                       acre ft
          (%o4)                        -------
                                        hour
          (%i5) dimensions_as_list (foo);
          (%o5)                 [3, 0, - 1, 0, 0, 0]

 -- Function: fundamental_units (<x>)
 -- Function: fundamental_units ()

     'fundamental_units(<x>)' returns the units associated with the
     fundamental dimensions of <x>.  as determined by 'dimensions(<x>)'.

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

     'fundamental_units()' returns the list of all known fundamental
     units, as declared by 'declare_fundamental_units'.

     'load(ezunits)' loads this function.

     Examples:

          (%i1) load (ezunits)$
          (%i2) fundamental_units ();
          (%o2)                 [m, kg, s, A, K, mol]
          (%i3) fundamental_units (100 ` mile/hour);
                                          m
          (%o3)                           -
                                          s
          (%i4) declare_units (aa, g/foot^2);
                                          g
          (%o4)                         -----
                                            2
                                        foot
          (%i5) fundamental_units (aa);
                                         kg
          (%o5)                          --
                                          2
                                         m

 -- Function: dimensionless (<L>)

     Returns a basis for the dimensionless quantities which can be
     formed from a list <L> of dimensional quantities.

     'load(ezunits)' loads this function.

     Examples:

          (%i1) load (ezunits) $
          (%i2) dimensionless ([x ` m, y ` m/s, z ` s]);
          0 errors, 0 warnings
          0 errors, 0 warnings
                                         y z
          (%o2)                         [---]
                                          x

     Dimensionless quantities derived from fundamental physical
     quantities.  Note that the first element on the list is
     proportional to the fine-structure constant.

          (%i1) load (ezunits) $
          (%i2) load (physical_constants) $
          (%i3) dimensionless([%h_bar, %m_e, %m_P, %%e, %c, %e_0]);
          0 errors, 0 warnings
          0 errors, 0 warnings
                                        2
                                     %%e        %m_e
          (%o3)                [--------------, ----]
                                %c %e_0 %h_bar  %m_P

 -- Function: natural_unit (<expr>, [<v_1>, ..., <v_n>])

     Finds exponents <e_1>, ..., <e_n> such that 'dimension(<expr>) =
     dimension(<v_1>^<e_1> ... <v_n>^<e_n>)'.

     'load(ezunits)' loads this function.

     Examples:


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

46 f90
******

* Menu:

* Functions and Variables for f90::


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

46.1 Functions and Variables for f90
====================================

 -- Function: f90 (<expr_1>, ..., <expr_n>)

     Prints one or more expressions <expr_1>, ..., <expr_n> as a Fortran
     90 program.  Output is printed to the standard output.

     'f90' prints output in the so-called "free form" input format for
     Fortran 90: there is no special attention to column positions.
     Long lines are split at a fixed width with the ampersand '&'
     continuation character.

     'load(f90)' loads this function.  See also the function 'fortran'.

     Examples:

          (%i1) load (f90)$
          (%i2) foo : expand ((xxx + yyy + 7)^4);
                   4            3         3        2    2             2
          (%o2) yyy  + 4 xxx yyy  + 28 yyy  + 6 xxx  yyy  + 84 xxx yyy
                    2        3             2
           + 294 yyy  + 4 xxx  yyy + 84 xxx  yyy + 588 xxx yyy + 1372 yyy
                4         3          2
           + xxx  + 28 xxx  + 294 xxx  + 1372 xxx + 2401
          (%i3) f90 ('foo = foo);
          foo = 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
          (%o3)                         false

     Multiple expressions.  Capture standard output into a file via the
     'with_stdout' function.

          (%i1) load (f90)$
          (%i2) foo : sin (3*x + 1) - cos (7*x - 2);
          (%o2)              sin(3 x + 1) - cos(7 x - 2)
          (%i3) with_stdout ("foo.f90",
                             f90 (x=0.25, y=0.625, 'foo=foo, 'stop, 'end));
          (%o3)                         false
          (%i4) printfile ("foo.f90");
          x = 0.25
          y = 0.625
          foo = sin(3*x+1)-cos(7*x-2)
          stop
          end
          (%o4)                        foo.f90


File: maxima.info,  Node: finance,  Next: fractals,  Prev: f90,  Up: Top

47 finance
**********

* Menu:

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


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

47.1 Introduction to finance
============================

This is the Finance Package (Ver 0.1).

In all the functions, <rate> is the compound interest rate, <num> is the
number of periods and must be postivive and <flow> refers to cash flow
so if you have an Output the flow is negative and positive for Inputs.

Note that before using the functions defined in this package, you have
to load it writing 'load(finance)$'.

Author: Nicolas Guarin Zapata.


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

47.2 Functions and Variables for finance
========================================

 -- Function: days360 (<year1>, <month1>, <day1>, <year2>, <month2>,
          <day2>)

     Calculates the distance between 2 dates, assuming 360 days years,
     30 days months.

     Example:

          (%i1) load(finance)$
          (%i2) days360(2008,12,16,2007,3,25);
          (%o2)                      - 621

 -- Function: fv (<rate>, <PV>, <num>)

     We can calculate the future value of a Present one given a certain
     interest rate.  <rate> is the interest rate, <PV> is the present
     value and <num> is the number of periods.

     Example:

          (%i1) load(finance)$
          (%i2) fv(0.12,1000,3);
          (%o2)                     1404.928

 -- Function: pv (<rate>, <FV>, <num>)

     We can calculate the present value of a Future one given a certain
     interest rate.  <rate> is the interest rate, <FV> is the future
     value and <num> is the number of periods.

     Example:

          (%i1) load(finance)$
          (%i2) pv(0.12,1000,3);
          (%o2)                711.7802478134108

 -- Function: graph_flow (<val>)

     Plots the money flow in a time line, the positive values are in
     blue and upside; the negative ones are in red and downside.  The
     direction of the flow is given by the sign of the value.  <val> is
     a list of flow values.

     Example:

          (%i1) load(finance)$
          (%i2) graph_flow([-5000,-3000,800,1300,1500,2000])$

 -- Function: annuity_pv (<rate>, <PV>, <num>)

     We can calculate the annuity knowing the present value (like an
     ammount), it is a constant and periodic payment.  <rate> is the
     interest rate, <PV> is the present value and <num> is the number of
     periods.

     Example:

          (%i1) load(finance)$
          (%i2) annuity_pv(0.12,5000,10);
          (%o2)                884.9208207992202

 -- Function: annuity_fv (<rate>, <FV>, <num>)

     We can calculate the annuity knowing the desired value (future
     value), it is a constant and periodic payment.  <rate> is the
     interest rate, <FV> is the future value and <num> is the number of
     periods.

     Example:

          (%i1) load(finance)$
          (%i2) annuity_fv(0.12,65000,10);
          (%o2)                3703.970670389863

 -- Function: geo_annuity_pv (<rate>, <growing_rate>, <PV>, <num>)

     We can calculate the annuity knowing the present value (like an
     ammount), in a growing periodic payment.  <rate> is the interest
     rate, <growing_rate> is the growing rate, <PV> is the present value
     and <num> is the number of periods.

     Example:

          (%i1) load(finance)$
          (%i2) geo_annuity_pv(0.14,0.05,5000,10);
          (%o2)                802.6888176505123

 -- Function: geo_annuity_fv (<rate>, <growing_rate>, <FV>,<num>)

     We can calculate the annuity knowing the desired value (future
     value), in a growing periodic payment.  <rate> is the interest
     rate, <growing_rate> is the growing rate, <FV> is the future value
     and <num> is the number of periods.

     Example:

          (%i1) load(finance)$
          (%i2) geo_annuity_fv(0.14,0.05,5000,10);
          (%o2)                216.5203395312695

 -- Function: amortization (<rate>, <ammount>, <num>)

     Amortization table determinated by a specific rate.  <rate> is the
     interest rate, <ammount> is the ammount value, and <num> is the
     number of periods.

     Example:

          (%i1) load(finance)$
          (%i2) amortization(0.05,56000,12)$
                "n"    "Balance"     "Interest"   "Amortization"  "Payment"
               0.000     56000.000         0.000         0.000         0.000
               1.000     52481.777      2800.000      3518.223      6318.223
               2.000     48787.643      2624.089      3694.134      6318.223
               3.000     44908.802      2439.382      3878.841      6318.223
               4.000     40836.019      2245.440      4072.783      6318.223
               5.000     36559.597      2041.801      4276.422      6318.223
               6.000     32069.354      1827.980      4490.243      6318.223
               7.000     27354.599      1603.468      4714.755      6318.223
               8.000     22404.106      1367.730      4950.493      6318.223
               9.000     17206.088      1120.205      5198.018      6318.223
              10.000     11748.170       860.304      5457.919      6318.223
              11.000      6017.355       587.408      5730.814      6318.223
              12.000         0.000       300.868      6017.355      6318.223

 -- Function: arit_amortization (<rate>, <increment>, <ammount>, <num>)

     The amortization table determinated by a specific rate and with
     growing payment can be claculated by 'arit_amortization'.  Notice
     that the payment is not constant, it presents an arithmetic
     growing, increment is then the difference between two consecutive
     rows in the "Payment" column.  <rate> is the interest rate,
     <increment> is the increment, <ammount> is the ammount value, and
     <num> is the number of periods.

     Example:

          (%i1) load(finance)$
          (%i2) arit_amortization(0.05,1000,56000,12)$
                "n"    "Balance"     "Interest"   "Amortization"  "Payment"
               0.000     56000.000         0.000         0.000         0.000
               1.000     57403.679      2800.000     -1403.679      1396.321
               2.000     57877.541      2870.184      -473.863      2396.321
               3.000     57375.097      2893.877       502.444      3396.321
               4.000     55847.530      2868.755      1527.567      4396.321
               5.000     53243.586      2792.377      2603.945      5396.321
               6.000     49509.443      2662.179      3734.142      6396.321
               7.000     44588.594      2475.472      4920.849      7396.321
               8.000     38421.703      2229.430      6166.892      8396.321
               9.000     30946.466      1921.085      7475.236      9396.321
              10.000     22097.468      1547.323      8848.998     10396.321
              11.000     11806.020      1104.873     10291.448     11396.321
              12.000        -0.000       590.301     11806.020     12396.321

 -- Function: geo_amortization (<rate>, <growing_rate>, <ammount>,
          <num>)

     The amortization table determinated by rate, ammount, and number of
     periods can be found by 'geo_amortization'.  Notice that the
     payment is not constant, it presents a geometric growing,
     <growing_rate> is then the quotient between two consecutive rows in
     the "Payment" column.  <rate> is the interest rate, <ammount> is
     the ammount value, and <num> is the number of periods.

     Example:

          (%i1) load(finance)$
          (%i2) geo_amortization(0.05,0.03,56000,12)$
                "n"    "Balance"     "Interest"   "Amortization"  "Payment"
               0.000     56000.000         0.000         0.000         0.000
               1.000     53365.296      2800.000      2634.704      5434.704
               2.000     50435.816      2668.265      2929.480      5597.745
               3.000     47191.930      2521.791      3243.886      5765.677
               4.000     43612.879      2359.596      3579.051      5938.648
               5.000     39676.716      2180.644      3936.163      6116.807
               6.000     35360.240      1983.836      4316.475      6300.311
               7.000     30638.932      1768.012      4721.309      6489.321
               8.000     25486.878      1531.947      5152.054      6684.000
               9.000     19876.702      1274.344      5610.176      6884.520
              10.000     13779.481       993.835      6097.221      7091.056
              11.000      7164.668       688.974      6614.813      7303.787
              12.000         0.000       358.233      7164.668      7522.901

 -- Function: saving (<rate>, <ammount>, <num>)

     The table that represents the values in a constant and periodic
     saving can be found by 'saving'.  <ammount> represents the desired
     quantity and num the number of periods to save.

     Example:

          (%i1) load(finance)$
          (%i2) saving(0.15,12000,15)$
                "n"    "Balance"     "Interest"   "Payment"
               0.000         0.000         0.000         0.000
               1.000       252.205         0.000       252.205
               2.000       542.240        37.831       252.205
               3.000       875.781        81.336       252.205
               4.000      1259.352       131.367       252.205
               5.000      1700.460       188.903       252.205
               6.000      2207.733       255.069       252.205
               7.000      2791.098       331.160       252.205
               8.000      3461.967       418.665       252.205
               9.000      4233.467       519.295       252.205
              10.000      5120.692       635.020       252.205
              11.000      6141.000       768.104       252.205
              12.000      7314.355       921.150       252.205
              13.000      8663.713      1097.153       252.205
              14.000     10215.474      1299.557       252.205
              15.000     12000.000      1532.321       252.205

 -- Function: npv (<rate>, <val>)

     Calculates de present value of a value series to evaluate the
     viability in a project.  <flowValues> es una lista con los valores
     para cada periodo.

     Example:

          (%i1) load(finance)$
          (%i2) npv(0.25,[100,500,323,124,300]);
          (%o2)                714.4703999999999

 -- Function: irr (<val>, <IO>)

     IRR (Internal Rate of Return) is the value of rate which makes Net
     Present Value zero.  <flowValues> los valores para cada periodo
     (para periodos mayores a 0) y <I0> el valor para el periodo cero.

     Example:

          (%i1) load(finance)$
          (%i2) res:irr([-5000,0,800,1300,1500,2000],0)$
          (%i3) rhs(res[1][1]);
          (%o3)                .03009250374237132

 -- Function: benefit_cost (<rate>, <input>, <output>)

     Calculates the ratio Benefit/Cost.  Benefit is the Net Present
     Value (NPV) of the inputs, and Cost is the Net Present Value (NPV)
     of the outputs.  Notice that if there is not an input or output
     value in a specific period, the input/output would be a zero for
     that period.  <rate> is the interest rate, <input> is a list of
     input values, and <output> is a list of output values.

     Example:

          (%i1) load(finance)$
          (%i2) benefit_cost(0.24,[0,300,500,150],[100,320,0,180]);
          (%o2)               1.427249324905784


File: maxima.info,  Node: fractals,  Next: ggf,  Prev: finance,  Up: Top

48 fractals
***********

* Menu:

* Introduction to fractals::
* Definitions for IFS fractals::
* Definitions for complex fractals::
* Definitions for Koch snowflakes::
* Definitions for Peano maps::


File: maxima.info,  Node: Introduction to fractals,  Next: Definitions for IFS fractals,  Prev: fractals,  Up: fractals

48.1 Introduction to fractals
=============================

This package defines some well known fractals:

   * with random IFS (Iterated Function System): the Sierpinsky
     triangle, a Tree and a Fern
   * Complex Fractals: the Mandelbrot and Julia Sets
   * the Koch snowflake sets
   * Peano maps: the Sierpinski and Hilbert maps

Author: José Ramírez Labrador.

For questions, suggestions and bugs, please feel free to contact me at
pepe DOT ramirez AAATTT uca DOT es


File: maxima.info,  Node: Definitions for IFS fractals,  Next: Definitions for complex fractals,  Prev: Introduction to fractals,  Up: fractals

48.2 Definitions for IFS fractals
=================================

Some fractals can be generated by iterative applications of contractive
affine transformations in a random way; see Hoggar S. G., "Mathematics
for computer graphics", Cambridge University Press 1994.

We define a list with several contractive affine transformations, and we
randomly select the transformation in a recursive way.  The probability
of the choice of a transformation must be related with the contraction
ratio.

You can change the transformations and find another fractal

 -- Function: sierpinskiale (<n>)

     Sierpinski Triangle: 3 contractive maps; .5 contraction constant
     and translations; all maps have the same contraction ratio.
     Argument <n> must be great enougth, 10000 or greater.

     Example:

          (%i1) load(fractals)$
          (%i2) n: 10000$
          (%i3) plot2d([discrete,sierpinskiale(n)], [style,dots])$

 -- Function: treefale (<n>)

     3 contractive maps all with the same contraction ratio.  Argument
     <n> must be great enougth, 10000 or greater.

     Example:

          (%i1) load(fractals)$
          (%i2) n: 10000$
          (%i3) plot2d([discrete,treefale(n)], [style,dots])$

 -- Function: fernfale (<n>)

     4 contractive maps, the probability to choice a transformation must
     be related with the contraction ratio.  Argument <n> must be great
     enougth, 10000 or greater.

     Example:

          (%i1) load(fractals)$
          (%i2) n: 10000$
          (%i3) plot2d([discrete,fernfale(n)], [style,dots])$


File: maxima.info,  Node: Definitions for complex fractals,  Next: Definitions for Koch snowflakes,  Prev: Definitions for IFS fractals,  Up: Top

48.3 Definitions for complex fractals
=====================================

 -- Function: mandelbrot_set (<x>, <y>)

     Mandelbrot set.

     Example:

     This program is time consuming because it must make a lot of
     operations; the computing time is also related with the number of
     grid points.

          (%i1) load(fractals)$
          (%i2) plot3d (mandelbrot_set, [x, -2.5, 1], [y, -1.5, 1.5],
                          [gnuplot_preamble, "set view map"],
                          [gnuplot_pm3d, true],
                          [grid, 150, 150])$

 -- Function: julia_set (<x>, <y>)

     Julia sets.

     This program is time consuming because it must make a lot of
     operations; the computing time is also related with the number of
     grid points.

     Example:

          (%i1) load(fractals)$
          (%i2) plot3d (julia_set, [x, -2, 1], [y, -1.5, 1.5],
                          [gnuplot_preamble, "set view map"],
                          [gnuplot_pm3d, true],
                          [grid, 150, 150])$

     See also 'julia_parameter'.

 -- Option variable: julia_parameter
     Default value: '%i'

     Complex parameter for Julia fractals.  Its default value is '%i';
     we suggest the values '-.745+%i*.113002', '-.39054-%i*.58679',
     '-.15652+%i*1.03225', '-.194+%i*.6557' and '.011031-%i*.67037'.

 -- Function: julia_sin (<x>, <y>)

     While function 'julia_set' implements the transformation
     'julia_parameter+z^2', function 'julia_sin' implements
     'julia_parameter*sin(z)'.  See source code for more details.

     This program runs slowly because it calculates a lot of sines.

     Example:

     This program is time consuming because it must make a lot of
     operations; the computing time is also related with the number of
     grid points.

          (%i1) load(fractals)$
          (%i2) julia_parameter:1+.1*%i$
          (%i3) plot3d (julia_sin, [x, -2, 2], [y, -3, 3],
                          [gnuplot_preamble, "set view map"],
                          [gnuplot_pm3d, true],
                          [grid, 150, 150])$

     See also 'julia_parameter'.


File: maxima.info,  Node: Definitions for Koch snowflakes,  Next: Definitions for Peano maps,  Prev: Definitions for complex fractals,  Up: Top

48.4 Definitions for Koch snowflakes
====================================

 -- Function: snowmap (<ent>, <nn>)

     Koch snowflake sets.  Function 'snowmap' plots the snow Koch map
     over the vertex of an initial closed polygonal, in the complex
     plane.  Here the orientation of the polygon is important.  Argument
     <nn> is the number of recursive applications of Koch
     transformation; <nn> must be small (5 or 6).

     Examples:

          (%i1) load(fractals)$
          (%i2) plot2d([discrete,
                        snowmap([1,exp(%i*%pi*2/3),exp(-%i*%pi*2/3),1],4)])$
          (%i3) plot2d([discrete,
                        snowmap([1,exp(-%i*%pi*2/3),exp(%i*%pi*2/3),1],4)])$
          (%i4) plot2d([discrete, snowmap([0,1,1+%i,%i,0],4)])$
          (%i5) plot2d([discrete, snowmap([0,%i,1+%i,1,0],4)])$


File: maxima.info,  Node: Definitions for Peano maps,  Prev: Definitions for Koch snowflakes,  Up: fractals

48.5 Definitions for Peano maps
===============================

Continuous curves that cover an area.  Warning: the number of points
exponentially grows with <n>.

 -- Function: hilbertmap (<nn>)

     Hilbert map.

     Argument <nn> must be small (5, for example).  Maxima can crash if
     <nn> is 7 or greater.

     Example:

          (%i1) load(fractals)$
          (%i2) plot2d([discrete,hilbertmap(6)])$

 -- Function: sierpinskimap (<nn>)

     Sierpinski map.

     Argument <nn> must be small (5, for example).  Maxima can crash if
     <nn> is 7 or greater.

     Example:

          (%i1) load(fractals)$
          (%i2) plot2d([discrete,sierpinskimap(6)])$


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

49 ggf
******

* Menu:

* Functions and Variables for ggf::


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

49.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

50 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

50.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

50.2 Functions and Variables for graphs
=======================================

50.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: cuboctahedron_graph (<n>)
     Returns the cuboctahedron graph.

 -- 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: great_rhombicosidodecahedron_graph ()
     Returns the great rhombicosidodecahedron graph.

 -- Function: great_rhombicuboctahedron_graph ()
     Returns the great rhombicuboctahedron graph.

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

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

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

 -- Function: icosidodecahedron_graph ()
     Returns the icosidodecahedron 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: small_rhombicosidodecahedron_graph ()
     Returns the small rhombicosidodecahedron graph.

 -- Function: small_rhombicuboctahedron_graph ()
     Returns the small rhombicuboctahedron graph.

 -- Function: snub_cube_graph ()
     Returns the snub cube graph.

 -- Function: snub_dodecahedron_graph ()
     Returns the snub dodecahedron graph.

 -- Function: truncated_cube_graph ()
     Returns the truncated cube graph.

 -- Function: truncated_dodecahedron_graph ()
     Returns the truncated dodecahedron graph.

 -- Function: truncated_icosahedron_graph ()
     Returns the truncated icosahedron graph.

 -- Function: truncated_tetrahedron_graph ()
     Returns the truncated tetrahedron graph.

 -- 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.

50.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 the graph <gr>.

     See also 'min_edge_cut'.

 -- 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 edges in the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) p : petersen_graph()$
          (%i3) graph_size(p);
          (%o3)                          15

 -- Function: graph_order (<gr>)
     Returns the number of vertices in the graph <gr>.

     Example:
          (%i1) load (graphs)$
          (%i2) p : petersen_graph()$
          (%i3) graph_order(p);
          (%o3)                          10

 -- 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 the graph <gr>.

     See also 'edge_connectivity'.

 -- Function: min_vertex_cover (<gr>)
     Returns the minimum vertex cover of the graph <gr>.

 -- Function: min_vertex_cut (<gr>)
     Returns the minimum vertex cut in the graph <gr>.

     See also 'vertex_connectivity'.

 -- 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_connectivity (<g>)
     Returns the vertex connectivity of the graph <g>.

     See also 'min_vertex_cut'.

 -- 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]

 -- 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]]]

 -- Function: wiener_index (<gr>)
     Returns the Wiener index of the graph <gr>.

     Example:
          (%i2) wiener_index(dodecahedron_graph());
          (%o2)                          500

50.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>.

50.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.

50.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'.  <draw_graph> can also use the graphviz
     programs for positioning vertices, but graphviz must be installed
     separately.

     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.

 -- draw_graph option: show_id
     Default value: <false>

     If <true> then ids of the vertices are displayed.

 -- draw_graph option: show_label
     Default value: <false>

     If <true> then labels of the vertices are displayed.

 -- draw_graph option: label_alignment
     Default value: <center>

     Determines how to align the labels/ids of the vertices.  Can be
     'left', 'center' or 'right'.

 -- draw_graph option: show_weight
     Default value: <false>

     If <true> then weights of the edges are displayed.

 -- draw_graph option: vertex_type
     Default value: <circle>

     Defines how vertices are displayed.  See the <point_type> option
     for the 'draw' package for possible values.

 -- draw_graph option: vertex_size
     The size of vertices.

 -- draw_graph option: vertex_color
     The color used for displaying vertices.

 -- draw_graph option: show_vertices
     Default value: []

     Display selected vertices in the using a different color.

 -- draw_graph option: show_vertex_type
     Defines how vertices specified in <show_vertices> are displayed.
     See the <point_type> option for the 'draw' package for possible
     values.

 -- draw_graph option: show_vertex_size
     The size of vertices in <show_vertices>.

 -- draw_graph option: show_vertex_color
     The color used for displaying vertices in the <show_vertices> list.

 -- draw_graph option: vertex_partition
     Default value: []

     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.

 -- draw_graph option: vertex_coloring
     Specifies coloring of the vertices.  The coloring <col> must be
     specified in the format as returned by <vertex_coloring>.

 -- draw_graph option: edge_color
     The color used for displaying edges.

 -- draw_graph option: edge_width
     The width of edges.

 -- draw_graph option: edge_type
     Defines how edges are displayed.  See the <line_type> option for
     the 'draw' package.

 -- draw_graph option: show_edges
     Display edges specified in the list <e_list> using a different
     color.

 -- draw_graph option: show_edge_color
     The color used for displaying edges in the <show_edges> list.

 -- draw_graph option: show_edge_width
     The width of edges in <show_edges>.

 -- draw_graph option: show_edge_type
     Defines how edges in <show_edges> are displayed.  See the
     <line_type> option for the 'draw' package.

 -- draw_graph option: edge_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.

 -- draw_graph option: edge_coloring
     The coloring of edges.  The coloring must be specified in the
     format as returned by the function <edge_coloring>.

 -- draw_graph option: redraw
     Default value: <false>

     If 'true', vertex positions are recomputed even if the positions
     have been saved from a previous drawing of the graph.

 -- draw_graph option: head_angle
     Default value: 15

     The angle for the arrows displayed on arcs (in directed graphs).

 -- draw_graph option: head_length
     Default value: 0.1

     The length for the arrows displayed on arcs (in directed graphs).

 -- draw_graph option: spring_embedding_depth
     Default value: 50

     The number of iterations in the spring embedding graph drawing
     algorithm.

 -- draw_graph option: terminal
     The terminal used for drawing (see the <terminal> option in the
     'draw' package).

 -- draw_graph option: file_name
     The filename of the drawing if terminal is not screen.

 -- draw_graph option: program
     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.

 -- draw_graph option: fixed_vertices
     Specifies a list of vertices which will have positions fixed along
     a regular polygon.  Can be used when 'program=spring_embedding'.

 -- 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: groups,  Prev: graphs,  Up: Top

51 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

51.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.

51.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 Gü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 Gröbner bases (F4)", Jean-Charles Faugère, LIP6/CNRS
Université Paris VI, January 20, 1999.

51.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

51.2 Functions and Variables for grobner
========================================

51.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.

51.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>.

          (%i1) 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.

51.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.

51.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>.

     See also 'ezgcd', 'gcd', 'gcdex', and 'gcdivide'.

     Example:

          (%i1) p1:6*x^3+19*x^2+19*x+6;
                                  3       2
          (%o1)                6 x  + 19 x  + 19 x + 6
          (%i2) p2:6*x^5+13*x^4+12*x^3+13*x^2+6*x;
                            5       4       3       2
          (%o2)          6 x  + 13 x  + 12 x  + 13 x  + 6 x
          (%i3) poly_gcd(p1, p2, [x]);
                                      2
          (%o3)                    6 x  + 13 x + 6

 -- 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: groups,  Next: impdiff,  Prev: grobner,  Up: Top

52 groups
*********

* Menu:

* Functions and Variables for Groups::


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

52.1 Functions and Variables for Groups
=======================================

 -- Function: todd_coxeter (<relations>, <subgroup>)
 -- Function: todd_coxeter (<relations>)

     Find the order of G/H where G is the Free Group modulo <relations>,
     and H is the subgroup of G generated by <subgroup>.  <subgroup> is
     an optional argument, defaulting to [].  In doing this it produces
     a multiplication table for the right action of G on G/H, where the
     cosets are enumerated [H,Hg2,Hg3,...].  This can be seen internally
     in the variable 'todd_coxeter_state'.

     Example:

          (%i1) symet(n):=create_list(
                  if (j - i) = 1 then (p(i,j))^^3 else
                      if (not i = j) then (p(i,j))^^2 else
                          p(i,i) , j, 1, n-1, i, 1, j);
                                                                 <3>
          (%o1) symet(n) := create_list(if j - i = 1 then p(i, j)

                                          <2>
           else (if not i = j then p(i, j)    else p(i, i)), j, 1, n - 1,

          i, 1, j)
          (%i2) p(i,j) := concat(x,i).concat(x,j);
          (%o2)        p(i, j) := concat(x, i) . concat(x, j)
          (%i3) symet(5);
                   <2>           <3>    <2>           <2>           <3>
          (%o3) [x1   , (x1 . x2)   , x2   , (x1 . x3)   , (x2 . x3)   ,

                      <2>           <2>           <2>           <3>    <2>
                    x3   , (x1 . x4)   , (x2 . x4)   , (x3 . x4)   , x4   ]
          (%i4) todd_coxeter(%o3);

          Rows tried 426
          (%o4)                          120
          (%i5) todd_coxeter(%o3,[x1]);

          Rows tried 213
          (%o5)                          60
          (%i6) todd_coxeter(%o3,[x1,x2]);

          Rows tried 71
          (%o6)                          20


File: maxima.info,  Node: impdiff,  Next: interpol,  Prev: groups,  Up: Top

53 impdiff
**********

* Menu:

* Functions and Variables for impdiff::


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

53.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: interpol,  Next: lapack,  Prev: impdiff,  Up: Top

54 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

54.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

54.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 unstable.

     Examples:

          (%i1) load(interpol)$
          (%i2) p:[[7,2],[8,2],[1,5],[3,2],[6,7]]$
          (%i3) lagrange(p);
                 (x - 7) (x - 6) (x - 3) (x - 1)
          (%o3)  -------------------------------
                               35
             (x - 8) (x - 6) (x - 3) (x - 1)
           - -------------------------------
                           12
             7 (x - 8) (x - 7) (x - 3) (x - 1)
           + ---------------------------------
                            30
             (x - 8) (x - 7) (x - 6) (x - 1)
           - -------------------------------
                           60
             (x - 8) (x - 7) (x - 6) (x - 3)
           + -------------------------------
                           84
          (%i4) f(x):=''%;
                         (x - 7) (x - 6) (x - 3) (x - 1)
          (%o4)  f(x) := -------------------------------
                                       35
             (x - 8) (x - 6) (x - 3) (x - 1)
           - -------------------------------
                           12
             7 (x - 8) (x - 7) (x - 3) (x - 1)
           + ---------------------------------
                            30
             (x - 8) (x - 7) (x - 6) (x - 1)
           - -------------------------------
                           60
             (x - 8) (x - 7) (x - 6) (x - 3)
           + -------------------------------
                           84
          (%i5) /* Evaluate the polynomial at some points */
                expand(map(f,[2.3,5/7,%pi]));
                                            4          3           2
                              919062  73 %pi    701 %pi    8957 %pi
          (%o5)  [- 1.567535, ------, ------- - -------- + ---------
                              84035     420       210         420
                                                       5288 %pi   186
                                                     - -------- + ---]
                                                         105       5
          (%i6) %,numer;
          (%o6) [- 1.567535, 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);
                 (w - 7) (w - 6) (w - 3) (w - 1)
          (%o9)  -------------------------------
                               35
             (w - 8) (w - 6) (w - 3) (w - 1)
           - -------------------------------
                           12
             7 (w - 8) (w - 7) (w - 3) (w - 1)
           + ---------------------------------
                            30
             (w - 8) (w - 7) (w - 6) (w - 1)
           - -------------------------------
                           60
             (w - 8) (w - 7) (w - 6) (w - 3)
           + -------------------------------
                           84

 -- 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>)

     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 is one option to fit specific needs:
        * ''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

55 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

55.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

55.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: dgeqrf (<A>)

     Computes the QR decomposition of the matrix <A>.  All elements of
     <A> must be integer or floating point numbers.  <A> may or may not
     have the same number of rows and columns.

     A list of two items is returned.  The first item is the matrix <Q>,
     which is a square, orthonormal matrix which has the same number of
     rows as <A>.  The second item is the matrix <R>, which is the same
     size as <A>, and which has all elements equal to zero below the
     diagonal.  The product '<Q> . <R>', where "."  is the
     noncommutative multiplication operator, is equal to <A> (ignoring
     floating point round-off errors).

     Examples:

          (%i1) load (lapack) $
          (%i2) fpprintprec : 6 $
          (%i3) M : matrix ([1, -3.2, 8], [-11, 2.7, 5.9]) $
          (%i4) [q, r] : dgeqrf (M);
                 [ - .0905357  .995893  ]
          (%o4) [[                      ],
                 [  .995893    .0905357 ]
                                         [ - 11.0454   2.97863   5.15148 ]
                                         [                               ]]
                                         [     0      - 2.94241  8.50131 ]
          (%i5) q . r - M;
                   [ - 7.77156E-16   1.77636E-15   - 8.88178E-16 ]
          (%o5)    [                                             ]
                   [      0.0       - 1.33227E-15   8.88178E-16  ]
          (%i6) mat_norm (%, 1);
          (%o6)                      3.10862E-15

 -- Function: dgesv (<A>, <b>)

     Computes the solution <x> of the linear equation <A> <x> = <b>,
     where <A> is a square matrix, and <b> is a matrix of the same
     number of rows as <A> and any number of columns.  The return value
     <x> is the same size as <b>.

     The elements of <A> and <b> must evaluate to real floating point
     numbers via 'float'; thus elements may be any numeric type,
     symbolic numerical constants, or expressions which evaluate to
     floats.  The elements of <x> are always floating point numbers.
     All arithmetic is carried out as floating point operations.

     'dgesv' computes the solution via the LU decomposition of <A>.

     Examples:

     'dgesv' computes the solution of the linear equation <A> <x> = <b>.

          (%i1) A : matrix ([1, -2.5], [0.375, 5]);
                                         [   1    - 2.5 ]
          (%o1)                          [              ]
                                         [ 0.375    5   ]
          (%i2) b : matrix ([1.75], [-0.625]);
                                            [  1.75   ]
          (%o2)                             [         ]
                                            [ - 0.625 ]
          (%i3) x : dgesv (A, b);
                                      [  1.210526315789474  ]
          (%o3)                       [                     ]
                                      [ - 0.215789473684211 ]
          (%i4) dlange (inf_norm, b - A.x);
          (%o4)                                 0.0

     <b> is a matrix with the same number of rows as <A> and any number
     of columns.  <x> is the same size as <b>.

          (%i1) A : matrix ([1, -0.15], [1.82, 2]);
                                         [  1    - 0.15 ]
          (%o1)                          [              ]
                                         [ 1.82    2    ]
          (%i2) b : matrix ([3.7, 1, 8], [-2.3, 5, -3.9]);
                                        [  3.7   1    8   ]
          (%o2)                         [                 ]
                                        [ - 2.3  5  - 3.9 ]
          (%i3) x : dgesv (A, b);
                [  3.103827540695117  1.20985481742191    6.781786185657722 ]
          (%o3) [                                                           ]
                [ -3.974483062032557  1.399032116146062  -8.121425428948527 ]
          (%i4) dlange (inf_norm, b - A . x);
          (%o4)                       1.1102230246251565E-15

     The elements of <A> and <b> must evaluate to real floating point
     numbers.

          (%i1) A : matrix ([5, -%pi], [1b0, 11/17]);
                                         [   5    - %pi ]
                                         [              ]
          (%o1)                          [         11   ]
                                         [ 1.0b0   --   ]
                                         [         17   ]
          (%i2) b : matrix ([%e], [sin(1)]);
                                            [   %e   ]
          (%o2)                             [        ]
                                            [ sin(1) ]
          (%i3) x : dgesv (A, b);
                                       [ 0.690375643155986 ]
          (%o3)                        [                   ]
                                       [ 0.233510982552952 ]
          (%i4) dlange (inf_norm, b - A . x);
          (%o4)                        2.220446049250313E-16

 -- 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.

 -- Function: dgemm (<A>, <B>)
 -- Function: dgemm (<A>, <B>, <options>)

     Compute the product of two matrices and optionally add the product
     to a third matrix.

     In the simplest form, 'dgemm(<A>, <B>)' computes the product of the
     two real matrices, <A> and <B>.

     In the second form, 'dgemm' computes the <alpha> * <A> * <B> +
     <beta> * <C> where <A>, <B>, <C> are real matrices of the
     appropriate sizes and <alpha> and <beta> are real numbers.
     Optionally, <A> and/or <B> can be transposed before computing the
     product.  The extra parameters are specifed by optional keyword
     arguments: The keyword arguments are optional and may be specified
     in any order.  They all take the form 'key=val'.  The keyword
     arguments are:

     'C'
          The matrix <C> that should be added.  The default is 'false',
          which means no matrix is added.
     'alpha'
          The product of <A> and <B> is multiplied by this value.  The
          default is 1.
     'beta'
          If a matrix <C> is given, this value multiplies <C> before it
          is added.  The default value is 0, which implies that <C> is
          not added, even if <C> is given.  Hence, be sure to specify a
          non-zero value for <beta>.
     'transpose_a'
          If 'true', the transpose of <A> is used instead of <A> for the
          product.  The default is 'false'.
     'transpose_b'
          If 'true', the transpose of <B> is used instead of <B> for the
          product.  The default is 'false'.

     Examples:

          (%i1) load (lapack)$
          (%i2) A : matrix([1,2,3],[4,5,6],[7,8,9]);
                                            [ 1  2  3 ]
                                            [         ]
          (%o2)                             [ 4  5  6 ]
                                            [         ]
                                            [ 7  8  9 ]
          (%i3) B : matrix([-1,-2,-3],[-4,-5,-6],[-7,-8,-9]);
                                         [ - 1  - 2  - 3 ]
                                         [               ]
          (%o3)                          [ - 4  - 5  - 6 ]
                                         [               ]
                                         [ - 7  - 8  - 9 ]
          (%i4) C : matrix([3,2,1],[6,5,4],[9,8,7]);
                                            [ 3  2  1 ]
                                            [         ]
          (%o4)                             [ 6  5  4 ]
                                            [         ]
                                            [ 9  8  7 ]
          (%i5) dgemm(A,B);
                                   [ - 30.0   - 36.0   - 42.0  ]
                                   [                           ]
          (%o5)                    [ - 66.0   - 81.0   - 96.0  ]
                                   [                           ]
                                   [ - 102.0  - 126.0  - 150.0 ]
          (%i6) A . B;
                                      [ - 30   - 36   - 42  ]
                                      [                     ]
          (%o6)                       [ - 66   - 81   - 96  ]
                                      [                     ]
                                      [ - 102  - 126  - 150 ]
          (%i7) dgemm(A,B,transpose_a=true);
                                   [ - 66.0  - 78.0   - 90.0  ]
                                   [                          ]
          (%o7)                    [ - 78.0  - 93.0   - 108.0 ]
                                   [                          ]
                                   [ - 90.0  - 108.0  - 126.0 ]
          (%i8) transpose(A) . B;
                                     [ - 66  - 78   - 90  ]
                                     [                    ]
          (%o8)                      [ - 78  - 93   - 108 ]
                                     [                    ]
                                     [ - 90  - 108  - 126 ]
          (%i9) dgemm(A,B,c=C,beta=1);
                                   [ - 27.0  - 34.0   - 41.0  ]
                                   [                          ]
          (%o9)                    [ - 60.0  - 76.0   - 92.0  ]
                                   [                          ]
                                   [ - 93.0  - 118.0  - 143.0 ]
          (%i10) A . B + C;
                                      [ - 27  - 34   - 41  ]
                                      [                    ]
          (%o10)                      [ - 60  - 76   - 92  ]
                                      [                    ]
                                      [ - 93  - 118  - 143 ]
          (%i11) dgemm(A,B,c=C,beta=1, alpha=-1);
                                      [ 33.0   38.0   43.0  ]
                                      [                     ]
          (%o11)                      [ 72.0   86.0   100.0 ]
                                      [                     ]
                                      [ 111.0  134.0  157.0 ]
          (%i12) -A . B + C;
                                         [ 33   38   43  ]
                                         [               ]
          (%o12)                         [ 72   86   100 ]
                                         [               ]
                                         [ 111  134  157 ]

