This is octave.info, produced by makeinfo version 6.1 from octave.texi.

START-INFO-DIR-ENTRY
* Octave: (octave).           Interactive language for numerical computations.

END-INFO-DIR-ENTRY

   Copyright © 1996-2016 John W. Eaton.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


File: octave.info,  Node: Graphics Object Properties,  Next: Searching Properties,  Prev: Graphics Objects,  Up: Graphics Data Structures

15.3.3 Graphics Object Properties
---------------------------------

* Menu:

* Root Figure Properties::
* Figure Properties::
* Axes Properties::
* Line Properties::
* Text Properties::
* Image Properties::
* Patch Properties::
* Surface Properties::
* Light Properties::
* Uimenu Properties::
* Uibuttongroup Properties::
* Uicontextmenu Properties::
* Uipanel Properties::
* Uicontrol Properties::
* Uitoolbar Properties::
* Uipushtool Properties::
* Uitoggletool Properties::

In this Section the graphics object properties are discussed in detail,
starting with the root figure properties and continuing through the
objects hierarchy.  The documentation about a specific graphics object
can be displayed using ‘doc’ function, e.g., ‘doc ("axes properties")’
will show *note Axes Properties::.

   The allowed values for radio (string) properties can be retrieved
programmatically or displayed using the one or two arguments call to
‘set’ function.  *Note set: XREFset.

   In the following documentation, default values are enclosed in { }.


File: octave.info,  Node: Root Figure Properties,  Next: Figure Properties,  Up: Graphics Object Properties

15.3.3.1 Root Figure Properties
...............................

The ‘root figure’ properties are:

‘__modified__’: "off" | {"on"}

‘beingdeleted’: {"off"} | "on"
     ‘beingdeleted’ is unused.

‘busyaction’: "cancel" | {"queue"}
     ‘busyaction’ is unused.

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘callbackobject’ (read-only): graphics handle, def. ‘[](0x0)’
     Graphics handle of the current object whose callback is executing.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the root’s children.

‘clipping’: "off" | {"on"}
     ‘clipping’ is unused.

‘commandwindowsize’ (read-only): def. ‘[0 0]’

‘createfcn’: string | function handle, def. ‘[](0x0)’
     ‘createfcn’ is unused.

‘currentfigure’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the current figure.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     ‘deletefcn’ is unused.

‘fixedwidthfontname’: string, def. "Courier"

‘handlevisibility’: "callback" | "off" | {"on"}
     ‘handlevisibility’ is unused.

‘hittest’: "off" | {"on"}
     ‘hittest’ is unused.

‘interruptible’: "off" | {"on"}
     ‘interruptible’ is unused.

‘monitorpositions’ (read-only):
     ‘monitorpositions’ is unused.

‘parent’: graphics handle, def. ‘[](0x0)’
     Root figure has no parent graphics object.  ‘parent’ is always
     empty.

‘pointerlocation’: two-element vector, def. ‘[0 0]’
     ‘pointerlocation’ is unused.

‘pointerwindow’ (read-only): graphics handle, def. ‘0’
     ‘pointerwindow’ is unused.

‘screendepth’ (read-only): double

‘screenpixelsperinch’ (read-only): double

‘screensize’ (read-only): four-element vector

‘selected’: {"off"} | "on"
     ‘selected’ is unused.

‘selectionhighlight’: "off" | {"on"}
     ‘selectionhighlight’ is unused.

‘showhiddenhandles’: {"off"} | "on"
     If ‘showhiddenhandles’ is "on", all graphics objects handles are
     visible in their parents’ children list, regardless of the value of
     their ‘handlevisibility’ property.

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "root"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     ‘uicontextmenu’ is unused.

‘units’: "centimeters" | "inches" | "normalized" | {"pixels"} | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     ‘visible’ is unused.


File: octave.info,  Node: Figure Properties,  Next: Axes Properties,  Prev: Root Figure Properties,  Up: Graphics Object Properties

15.3.3.2 Figure Properties
..........................

The ‘figure’ properties are:

‘__modified__’: "off" | {"on"}

‘alphamap’: def. 64-by-1 double
     Transparency is not yet implemented for figure objects.  ‘alphamap’
     is unused.

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the figure’s children.

‘clipping’: "off" | {"on"}
     ‘clipping’ is unused.

‘closerequestfcn’: string | function handle, def. "closereq"

‘color’: colorspec, def. ‘[1 1 1]’
     Color of the figure background.  *Note colorspec: Colors.

‘colormap’: N-by-3 matrix, def. 64-by-3 double
     A matrix containing the RGB color map for the current axes.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after figure has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (0, "defaultfigurecreatefcn", 'disp ("figure
     created!")')’.

‘currentaxes’: graphics handle, def. ‘[](0x0)’
     Handle to the graphics object of the current axes.

‘currentcharacter’ (read-only): def. ""
     ‘currentcharacter’ is unused.

‘currentobject’ (read-only): graphics handle, def. ‘[](0x0)’

‘currentpoint’ (read-only): two-element vector, def. ‘[0; 0]’
     A 1-by-2 matrix which holds the coordinates of the point over which
     the mouse pointer was when a mouse event occurred.  The X and Y
     coordinates are in units defined by the figure’s ‘units’ property
     and their origin is the lower left corner of the plotting area.

     Events which set ‘currentpoint’ are
     A mouse button was pressed
          always
     A mouse button was released
          only if the figure’s callback ‘windowbuttonupfcn’ is defined
     The pointer was moved while pressing the mouse button (drag)
          only if the figure’s callback ‘windowbuttonmotionfcn’ is
          defined

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before figure is deleted.

‘dockcontrols’: {"off"} | "on"
     ‘dockcontrols’ is unused.

‘filename’: string, def. ""
     The filename used when saving the plot figure.

‘graphicssmoothing’: "off" | {"on"}
     Use smoothing techniques to reduce the appearance of jagged lines.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the figure’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}

‘integerhandle’: "off" | {"on"}
     Assign the next lowest unused integer as the Figure number.

‘interruptible’: "off" | {"on"}

‘inverthardcopy’: "off" | {"on"}
     Replace the figure and axes background color with white when
     printing.

‘keypressfcn’: string | function handle, def. ‘[](0x0)’

‘keyreleasefcn’: string | function handle, def. ‘[](0x0)’
     With ‘keypressfcn’, the keyboard callback functions.  These
     callback functions are called when a key is pressed/released
     respectively.  The functions are called with two input arguments.
     The first argument holds the handle of the calling figure.  The
     second argument holds an event structure which has the following
     members:
     ‘Character:’
          The ASCII value of the key
     ‘Key:’
          Lowercase value of the key
     ‘Modifier:’
          A cell array containing strings representing the modifiers
          pressed with the key.

‘menubar’: {"figure"} | "none"
     Control the display of the figure menu bar in the upper left of the
     figure.

‘name’: string, def. ""
     Name to be displayed in the figure title bar.  The name is
     displayed to the right of any title determined by the ‘numbertitle’
     property.

‘nextplot’: {"add"} | "new" | "replace" | "replacechildren"

‘numbertitle’: "off" | {"on"}
     Display "Figure" followed by the numerical figure handle value in
     the figure title bar.

‘outerposition’: four-element vector, def. ‘[-1 -1 -1 -1]’

‘paperorientation’: "landscape" | {"portrait"}
     The value for the ‘papersize’, and ‘paperposition’ properties
     depends upon ‘paperorientation’.  The horizontal and vertical
     values for ‘papersize’ and ‘paperposition’ reverse order when
     ‘paperorientation’ is switched between ‘"portrait"’ and
     ‘"landscape"’.

‘paperposition’: four-element vector, def. ‘[0.25000 2.50000 8.00000 6.00000]’
     Vector ‘[left bottom width height]’ defining the position and size
     of the figure (in ‘paperunits’ units) on the printed page.  The
     position ‘[left bottom]’ defines the lower left corner of the
     figure on the page, and the size is defined by ‘[width height]’.
     For output formats not implicitly rendered on paper, ‘width’ and
     ‘height’ define the size of the image and the position information
     is ignored.  Setting ‘paperposition’ also forces the
     ‘paperpositionmode’ property to be set to "manual".

‘paperpositionmode’: "auto" | {"manual"}
     If ‘paperpositionmode’ is set to "auto", the ‘paperposition’
     property is automatically computed: the printed figure will have
     the same size as the on-screen figure and will be centered on the
     output page.  Setting the ‘paperpositionmode’ to ‘"auto"’ does not
     modify the value of the ‘paperposition’ property.

‘papersize’: two-element vector, def. ‘[8.5000 11.0000]’
     Vector ‘[width height]’ defining the size of the paper for
     printing.  Setting the ‘papersize’ property to a value, not
     associated with one of the defined ‘papertypes’ and consistent with
     the setting for ‘paperorientation’, forces the ‘papertype’ property
     to the value "<custom>".  If ‘papersize’ is set to a value
     associated with a supported ‘papertype’ and consistent with the
     ‘paperorientation’, the ‘papertype’ value is modified to the
     associated value.

‘papertype’: "<custom>" | "a" | "a0" | "a1" | "a2" | "a3" | "a4" | "a5" | "arch-a" | "arch-b" | "arch-c" | "arch-d" | "arch-e" | "b" | "b0" | "b1" | "b2" | "b3" | "b4" | "b5" | "c" | "d" | "e" | "tabloid" | "uslegal" | {"usletter"}
     Name of the paper used for printed output.  Setting ‘papertype’
     also changes ‘papersize’, while maintaining consistency with the
     ‘paperorientation’ property.

‘paperunits’: "centimeters" | {"inches"} | "normalized" | "points"
     The unit used to compute the ‘paperposition’ property.  For
     ‘paperunits’ set to ‘"pixels"’, the conversion between physical
     units (ex: ‘"inches"’) and ‘"pixels"’ is dependent on the
     ‘screenpixelsperinch’ property of the root object.

‘parent’: graphics handle, def. ‘0’
     Handle of the parent graphics object.

‘pointer’: {"arrow"} | "botl" | "botr" | "bottom" | "circle" | "cross" | "crosshair" | "custom" | "fleur" | "fullcrosshair" | "hand" | "ibeam" | "left" | "right" | "top" | "topl" | "topr" | "watch"
     ‘pointer’ is unused.

‘pointershapecdata’: def. 16-by-16 double
     ‘pointershapecdata’ is unused.

‘pointershapehotspot’: def. ‘[0 0]’
     ‘pointershapehotspot’ is unused.

‘position’: four-element vector, def. ‘[300 200 560 420]’
     Specify the position and size of the figure.  The four elements of
     the vector are the coordinates of the lower left corner and width
     and height of the figure.  *Note units property: XREFfigureunits.

‘renderer’: {"opengl"} | "painters"

‘renderermode’: {"auto"} | "manual"

‘resize’: "off" | {"on"}
     ‘resize’ is unused.

‘resizefcn’: string | function handle, def. ‘[](0x0)’
     ‘resizefcn’ is deprecated.  Use ‘sizechangedfcn’ instead.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘selectiontype’: "alt" | "extend" | {"normal"} | "open"

‘sizechangedfcn’: string | function handle, def. ‘[](0x0)’
     Callback triggered when the figure window size is changed.

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘toolbar’: {"auto"} | "figure" | "none"
     Control the display of the toolbar along the bottom of the figure
     window.  When set to "auto", the display is based on the value of
     the ‘menubar’ property.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "figure"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this figure object.

‘units’: "centimeters" | "characters" | "inches" | "normalized" | {"pixels"} | "points"
     The unit used to compute the ‘position’ and ‘outerposition’
     properties.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the figure is not rendered on screen.

‘windowbuttondownfcn’: string | function handle, def. ‘[](0x0)’
     *Note windowbuttonupfcn property: XREFfigurewindowbuttonupfcn.

‘windowbuttonmotionfcn’: string | function handle, def. ‘[](0x0)’
     *Note windowbuttonupfcn property: XREFfigurewindowbuttonupfcn.

‘windowbuttonupfcn’: string | function handle, def. ‘[](0x0)’
     With ‘windowbuttondownfcn’ and ‘windowbuttonmotionfcn’, the mouse
     callback functions.  These callback functions are called when a
     mouse button is pressed, dragged, or released respectively.  When
     these callback functions are executed, the ‘currentpoint’ property
     holds the current coordinates of the cursor.

‘windowkeypressfcn’: string | function handle, def. ‘[](0x0)’

‘windowkeyreleasefcn’: string | function handle, def. ‘[](0x0)’

‘windowscrollwheelfcn’: string | function handle, def. ‘[](0x0)’

‘windowstyle’: "docked" | "modal" | {"normal"}
     The window style of a figure.  One of the following values:
     ‘normal’
          Set the window style as non modal.
     ‘modal’
          Set the window as modal so that it will stay on top of all
          normal figures.
     ‘docked’
          Setting the window style as docked currently does not dock the
          window.

     Changing modes of a visible figure may cause the figure to close
     and reopen.


File: octave.info,  Node: Axes Properties,  Next: Line Properties,  Prev: Figure Properties,  Up: Graphics Object Properties

15.3.3.3 Axes Properties
........................

The ‘axes’ properties are:

‘__modified__’: "off" | {"on"}

‘activepositionproperty’: {"outerposition"} | "position"

‘alim’: def. ‘[0 1]’
     Transparency is not yet implemented for axes objects.  ‘alim’ is
     unused.

‘alimmode’: {"auto"} | "manual"

‘ambientlightcolor’: def. ‘[1 1 1]’
     Light is not yet implemented for axes objects.  ‘ambientlightcolor’
     is unused.

‘beingdeleted’: {"off"} | "on"

‘box’: {"off"} | "on"
     Control whether the axes has a surrounding box.

‘boxstyle’: {"back"} | "full"
     ‘boxstyle’ is unused.

‘busyaction’: "cancel" | {"queue"}

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’

‘cameraposition’: three-element vector, def. ‘[0.50000 0.50000 9.16025]’

‘camerapositionmode’: {"auto"} | "manual"

‘cameratarget’: three-element vector, def. ‘[0.50000 0.50000 0.50000]’

‘cameratargetmode’: {"auto"} | "manual"

‘cameraupvector’: three-element vector, def. ‘[-0 1 0]’

‘cameraupvectormode’: {"auto"} | "manual"

‘cameraviewangle’: scalar, def. ‘6.6086’

‘cameraviewanglemode’: {"auto"} | "manual"

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the axes’s children.

‘clim’: two-element vector, def. ‘[0 1]’
     Define the limits for the color axis of image children.  Setting
     ‘clim’ also forces the ‘climmode’ property to be set to "manual".
     *Note pcolor function: XREFpcolor.

‘climmode’: {"auto"} | "manual"

‘clipping’: "off" | {"on"}
     ‘clipping’ is unused.

‘clippingstyle’: {"3dbox"} | "rectangle"
     ‘clippingstyle’ is unused.

‘color’: colorspec, def. ‘[1 1 1]’
     Color of the axes background.  *Note colorspec: Colors.

‘colororder’: N-by-3 RGB matrix, def. 7-by-3 double
     RGB values used by plot function for automatic line coloring.

‘colororderindex’: def. ‘1’
     ‘colororderindex’ is unused.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after axes has been created.
     Function is set by using default property on root object, e.g.,
     ‘set (0, "defaultaxescreatefcn", 'disp ("axes created!")')’.

‘currentpoint’: 2-by-3 matrix, def. 2-by-3 double
     Matrix ‘[xf, yf, zf; xb, yb, zb]’ which holds the coordinates (in
     axes data units) of the point over which the mouse pointer was when
     the mouse button was pressed.  If a mouse callback function is
     defined, ‘currentpoint’ holds the pointer coordinates at the time
     the mouse button was pressed.  For 3-D plots, the first row of the
     returned matrix specifies the point nearest to the current camera
     position and the second row the furthest point.  The two points
     forms a line which is perpendicular to the screen.

‘dataaspectratio’: three-element vector, def. ‘[1 1 1]’
     Specify the relative height and width of the data displayed in the
     axes.  Setting ‘dataaspectratio’ to ‘[1, 2]’ causes the length of
     one unit as displayed on the x-axis to be the same as the length of
     2 units on the y-axis.  Setting ‘dataaspectratio’ also forces the
     ‘dataaspectratiomode’ property to be set to "manual".

‘dataaspectratiomode’: {"auto"} | "manual"

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before axes is deleted.

‘drawmode’: "fast" | {"normal"}

‘fontangle’: "italic" | {"normal"}

‘fontname’: string, def. "*"
     Name of the font used for axes annotations.

‘fontsize’: scalar, def. ‘10’
     Size of the font used for axes annotations.  *Note
     fontunits property: XREFaxesfontunits.

‘fontsmoothing’: "off" | {"on"}
     ‘fontsmoothing’ is unused.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Unit used to interpret ‘fontsize’ property.

‘fontweight’: "bold" | {"normal"}

‘gridalpha’: def. ‘0.15000’
     Transparency is not yet implemented for axes objects.  ‘gridalpha’
     is unused.

‘gridalphamode’: {"auto"} | "manual"
     ‘gridalphamode’ is unused.

‘gridcolor’: def. ‘[0.15000 0.15000 0.15000]’
     ‘gridcolor’ is unused.

‘gridcolormode’: {"auto"} | "manual"
     ‘gridcolormode’ is unused.

‘gridlinestyle’: {"-"} | "–" | "-." | ":" | "none"

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the axes’s handle is not visible in
     its parent’s "children" property.

‘hittest’: "off" | {"on"}

‘interruptible’: "off" | {"on"}

‘labelfontsizemultiplier’: def. ‘1.1000’
     ‘labelfontsizemultiplier’ is unused.

‘layer’: {"bottom"} | "top"
     Control whether the axes is drawn below child graphics objects
     (ticks, labels, etc. covered by plotted objects) or above.

‘linestyleorder’: def. "-"
     ‘linestyleorder’ is unused.

‘linestyleorderindex’: def. ‘1’
     ‘linestyleorderindex’ is unused.

‘linewidth’: def. ‘0.50000’

‘minorgridalpha’: def. ‘0.25000’
     Transparency is not yet implemented for axes objects.
     ‘minorgridalpha’ is unused.

‘minorgridalphamode’: {"auto"} | "manual"
     ‘minorgridalphamode’ is unused.

‘minorgridcolor’: def. ‘[0.10000 0.10000 0.10000]’
     ‘minorgridcolor’ is unused.

‘minorgridcolormode’: {"auto"} | "manual"
     ‘minorgridcolormode’ is unused.

‘minorgridlinestyle’: "-" | "–" | "-." | {":"} | "none"

‘mousewheelzoom’: scalar in the range (0, 1), def. ‘0.50000’
     Fraction of axes limits to zoom for each wheel movement.

‘nextplot’: "add" | {"replace"} | "replacechildren"

‘outerposition’: four-element vector, def. ‘[0 0 1 1]’
     Specify the position of the plot including titles, axes, and
     legend.  The four elements of the vector are the coordinates of the
     lower left corner and width and height of the plot, in units
     normalized to the width and height of the plot window.  For
     example, ‘[0.2, 0.3, 0.4, 0.5]’ sets the lower left corner of the
     axes at (0.2, 0.3) and the width and height to be 0.4 and 0.5
     respectively.  *Note position property: XREFaxesposition.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘pickableparts’: "all" | "none" | {"visible"}
     ‘pickableparts’ is unused.

‘plotboxaspectratio’: def. ‘[1 1 1]’

‘plotboxaspectratiomode’: {"auto"} | "manual"

‘position’: four-element vector, def. ‘[0.13000 0.11000 0.77500 0.81500]’
     Specify the position of the plot excluding titles, axes, and
     legend.  The four elements of the vector are the coordinates of the
     lower left corner and width and height of the plot, in units
     normalized to the width and height of the plot window.  For
     example, ‘[0.2, 0.3, 0.4, 0.5]’ sets the lower left corner of the
     axes at (0.2, 0.3) and the width and height to be 0.4 and 0.5
     respectively.  *Note outerposition property: XREFaxesouterposition.

‘projection’: {"orthographic"} | "perspective"
     ‘projection’ is unused.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘sortmethod’: "childorder" | {"depth"}
     ‘sortmethod’ is unused.

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘tickdir’: {"in"} | "out"
     Control whether axes tick marks project "in" to the plot box or
     "out".

‘tickdirmode’: {"auto"} | "manual"

‘ticklabelinterpreter’: "latex" | "none" | {"tex"}
     Control the way x/y/zticklabel properties are interpreted.  *Note
     Use of the interpreter property: XREFinterpreterusage.

‘ticklength’: two-element vector, def. ‘[0.010000 0.025000]’
     Two-element vector ‘[2Dlen 3Dlen]’ specifying the length of the
     tickmarks relative to the longest visible axis.

‘tightinset’ (read-only): def. ‘[0.042857 0.038106 0.000000 0.023810]’

‘title’: graphics handle
     Graphics handle of the title text object.

‘titlefontsizemultiplier’: def. ‘1.1000’
     ‘titlefontsizemultiplier’ is unused.

‘titlefontweight’: {"bold"} | "normal"
     ‘titlefontweight’ is unused.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "axes"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this axes object.

‘units’: "centimeters" | "characters" | "inches" | {"normalized"} | "pixels" | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘view’: two-element vector, def. ‘[0 90]’
     Two-element vector ‘[azimuth elevation]’ specifying the viewpoint
     for three-dimensional plots

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the axes is not rendered on screen.

‘xaxislocation’: {"bottom"} | "origin" | "top" | "zero"

‘xcolor’: {colorspec} | "none", def. ‘[0.15000 0.15000 0.15000]’
     Color of the x-axis.  *Note colorspec: Colors.

‘xcolormode’: {"auto"} | "manual"
     ‘xcolormode’ is unused.

‘xdir’: {"normal"} | "reverse"

‘xgrid’: {"off"} | "on"
     Control whether major x grid lines are displayed.

‘xlabel’: graphics handle
     Graphics handle of the x label text object.

‘xlim’: two-element vector, def. ‘[0 1]’
     Two-element vector ‘[xmin xmax]’ specifying the limits for the
     x-axis.  Setting ‘xlim’ also forces the ‘xlimmode’ property to be
     set to "manual".  *Note xlim function: XREFxlim.

‘xlimmode’: {"auto"} | "manual"

‘xminorgrid’: {"off"} | "on"
     Control whether minor x grid lines are displayed.

‘xminortick’: {"off"} | "on"

‘xscale’: {"linear"} | "log"

‘xtick’: vector
     Position of x tick marks.  Setting ‘xtick’ also forces the
     ‘xtickmode’ property to be set to "manual".

‘xticklabel’: string | cell array of strings, def. 1-by-6 cell
     Labels of x tick marks.  Setting ‘xticklabel’ also forces the
     ‘xticklabelmode’ property to be set to "manual".

‘xticklabelmode’: {"auto"} | "manual"

‘xticklabelrotation’: def. ‘0’
     ‘xticklabelrotation’ is unused.

‘xtickmode’: {"auto"} | "manual"

‘yaxislocation’: {"left"} | "origin" | "right" | "zero"

‘ycolor’: {colorspec} | "none", def. ‘[0.15000 0.15000 0.15000]’
     Color of the y-axis.  *Note colorspec: Colors.

‘ycolormode’: {"auto"} | "manual"
     ‘ycolormode’ is unused.

‘ydir’: {"normal"} | "reverse"

‘ygrid’: {"off"} | "on"
     Control whether major y grid lines are displayed.

‘ylabel’: graphics handle
     Graphics handle of the y label text object.

‘ylim’: two-element vector, def. ‘[0 1]’
     Two-element vector ‘[ymin ymax]’ specifying the limits for the
     y-axis.  Setting ‘ylim’ also forces the ‘ylimmode’ property to be
     set to "manual".  *Note ylim function: XREFylim.

‘ylimmode’: {"auto"} | "manual"

‘yminorgrid’: {"off"} | "on"
     Control whether minor y grid lines are displayed.

‘yminortick’: {"off"} | "on"

‘yscale’: {"linear"} | "log"

‘ytick’: vector
     Position of y tick marks.  Setting ‘ytick’ also forces the
     ‘ytickmode’ property to be set to "manual".

‘yticklabel’: string | cell array of strings, def. 1-by-6 cell
     Labels of y tick marks.  Setting ‘yticklabel’ also forces the
     ‘yticklabelmode’ property to be set to "manual".

‘yticklabelmode’: {"auto"} | "manual"

‘yticklabelrotation’: def. ‘0’
     ‘yticklabelrotation’ is unused.

‘ytickmode’: {"auto"} | "manual"

‘zcolor’: {colorspec} | "none", def. ‘[0.15000 0.15000 0.15000]’
     Color of the z-axis.  *Note colorspec: Colors.

‘zcolormode’: {"auto"} | "manual"
     ‘zcolormode’ is unused.

‘zdir’: {"normal"} | "reverse"

‘zgrid’: {"off"} | "on"
     Control whether major z grid lines are displayed.

‘zlabel’: graphics handle
     Graphics handle of the z label text object.

‘zlim’: two-element vector, def. ‘[0 1]’
     Two-element vector ‘[zmin zmaz]’ specifying the limits for the
     z-axis.  Setting ‘zlim’ also forces the ‘zlimmode’ property to be
     set to "manual".  *Note zlim function: XREFzlim.

‘zlimmode’: {"auto"} | "manual"

‘zminorgrid’: {"off"} | "on"
     Control whether minor z grid lines are displayed.

‘zminortick’: {"off"} | "on"

‘zscale’: {"linear"} | "log"

‘ztick’: vector
     Position of z tick marks.  Setting ‘ztick’ also forces the
     ‘ztickmode’ property to be set to "manual".

‘zticklabel’: string | cell array of strings, def. 1-by-6 cell
     Labels of z tick marks.  Setting ‘zticklabel’ also forces the
     ‘zticklabelmode’ property to be set to "manual".

‘zticklabelmode’: {"auto"} | "manual"

‘zticklabelrotation’: def. ‘0’
     ‘zticklabelrotation’ is unused.

‘ztickmode’: {"auto"} | "manual"


File: octave.info,  Node: Line Properties,  Next: Text Properties,  Prev: Axes Properties,  Up: Graphics Object Properties

15.3.3.4 Line Properties
........................

The ‘line’ properties are:

‘__modified__’: "off" | {"on"}

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the line is clipped in its parent axes
     limits.

‘color’: colorspec, def. ‘[0 0 0]’
     Color of the line object.  *Note colorspec: Colors.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after line has been created.
     Function is set by using default property on root object, e.g.,
     ‘set (0, "defaultlinecreatefcn", 'disp ("line created!")')’.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before line is deleted.

‘displayname’: string | cell array of strings, def. ""
     Text for the legend entry corresponding to this line.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the line’s handle is not visible in
     its parent’s "children" property.

‘hittest’: "off" | {"on"}

‘interpreter’: "latex" | "none" | {"tex"}

‘interruptible’: "off" | {"on"}

‘linestyle’: {"-"} | "–" | "-." | ":" | "none"
     *Note Line Styles::.

‘linewidth’: def. ‘0.50000’
     Width of the line object measured in points.

‘marker’: "*" | "+" | "." | "<" | ">" | "^" | "d" | "diamond" | "h" | "hexagram" | {"none"} | "o" | "p" | "pentagram" | "s" | "square" | "v" | "x"
     Shape of the marker for each data point.  *Note Marker Styles::.

‘markeredgecolor’: {"auto"} | "none"
     Color of the edge of the markers.  When set to "auto", the marker
     edges have the same color as the line.  If set to "none", no marker
     edges are displayed.  This property can also be set to any color.
     *Note colorspec: Colors.

‘markerfacecolor’: "auto" | {"none"}
     Color of the face of the markers.  When set to "auto", the marker
     faces have the same color as the line.  If set to "none", the
     marker faces are not displayed.  This property can also be set to
     any color.  *Note colorspec: Colors.

‘markersize’: scalar, def. ‘6’
     Size of the markers measured in points.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "line"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this line object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the line is not rendered on screen.

‘xdata’: vector, def. ‘[0 1]’
     Vector of x data to be plotted.

‘xdatasource’: string, def. ""
     Name of a vector in the current base workspace to use as x data.

‘ydata’: vector, def. ‘[0 1]’
     Vector of y data to be plotted.

‘ydatasource’: string, def. ""
     Name of a vector in the current base workspace to use as y data.

‘zdata’: vector, def. ‘[](0x0)’
     Vector of z data to be plotted.

‘zdatasource’: string, def. ""
     Name of a vector in the current base workspace to use as z data.


File: octave.info,  Node: Text Properties,  Next: Image Properties,  Prev: Line Properties,  Up: Graphics Object Properties

15.3.3.5 Text Properties
........................

The ‘text’ properties are:

‘__modified__’: "off" | {"on"}

‘backgroundcolor’: colorspec, def. "none"
     Background area is not yet implemented for text objects.
     ‘backgroundcolor’ is unused.

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the text is clipped in its parent axes
     limits.

‘color’: colorspec, def. ‘[0 0 0]’
     Color of the text.  *Note colorspec: Colors.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after text has been created.
     Function is set by using default property on root object, e.g.,
     ‘set (0, "defaulttextcreatefcn", 'disp ("text created!")')’.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before text is deleted.

‘displayname’: def. ""

‘edgecolor’: colorspec, def. "none"
     Background area is not yet implemented for text objects.
     ‘edgecolor’ is unused.

‘editing’: {"off"} | "on"

‘extent’ (read-only): def. ‘[0.000000 -0.005843 0.000000 0.032136]’

‘fontangle’: "italic" | {"normal"} | "oblique"
     Flag whether the font is italic or normal.  ‘fontangle’ is
     currently unused.

‘fontname’: string, def. "*"
     The font used for the text.

‘fontsize’: scalar, def. ‘10’
     The font size of the text as measured in ‘fontunits’.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     The units used to interpret ‘fontsize’ property.

‘fontweight’: "bold" | "demi" | "light" | {"normal"}
     Control variant of base font used: bold, light, normal, etc.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the text’s handle is not visible in
     its parent’s "children" property.

‘hittest’: "off" | {"on"}

‘horizontalalignment’: "center" | {"left"} | "right"

‘interpreter’: "latex" | "none" | {"tex"}
     Control the way the "string" property is interpreted.  *Note
     Use of the interpreter property: XREFinterpreterusage.

‘interruptible’: "off" | {"on"}

‘linestyle’: {"-"} | "–" | "-." | ":" | "none"
     Background area is not yet implemented for text objects.
     ‘linestyle’ is unused.

‘linewidth’: scalar, def. ‘0.50000’
     Background area is not yet implemented for text objects.
     ‘linewidth’ is unused.

‘margin’: scalar, def. ‘2’
     Background area is not yet implemented for text objects.  ‘margin’
     is unused.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘position’: four-element vector, def. ‘[0 0 0]’
     Vector ‘[X0 Y0 Z0]’ where X0, Y0 and Z0 indicate the position of
     the text anchor as defined by ‘verticalalignment’ and
     ‘horizontalalignment’.

‘rotation’: scalar, def. ‘0’
     The angle of rotation for the displayed text, measured in degrees.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘string’: string, def. ""
     The text object string content.

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "text"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this text object.

‘units’: "centimeters" | {"data"} | "inches" | "normalized" | "pixels" | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘verticalalignment’: "baseline" | "bottom" | "cap" | {"middle"} | "top"

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the text is not rendered on screen.


File: octave.info,  Node: Image Properties,  Next: Patch Properties,  Prev: Text Properties,  Up: Graphics Object Properties

15.3.3.6 Image Properties
.........................

The ‘image’ properties are:

‘__modified__’: "off" | {"on"}

‘alphadata’: scalar | matrix, def. ‘1’
     Transparency is not yet implemented for image objects.  ‘alphadata’
     is unused.

‘alphadatamapping’: "direct" | {"none"} | "scaled"
     Transparency is not yet implemented for image objects.
     ‘alphadatamapping’ is unused.

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’

‘cdata’: matrix, def. 64-by-64 double

‘cdatamapping’: {"direct"} | "scaled"

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the image is clipped in its parent axes
     limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after image has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (0, "defaultimagecreatefcn", 'disp ("image
     created!")')’.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before image is deleted.

‘displayname’: string | cell array of strings, def. ""
     Text for the legend entry corresponding to this image.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the image’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}

‘interruptible’: "off" | {"on"}

‘parent’: graphics handle
     Handle of the parent graphics object.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "image"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this image object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the image is not rendered on screen.

‘xdata’: two-element vector, def. ‘[1 64]’
     Two-element vector ‘[xmin xmax]’ specifying the x coordinates of
     the first and last columns of the image.

     Setting ‘xdata’ to the empty matrix ([]) will restore the default
     value of ‘[1 columns(image)]’.

‘ydata’: two-element vector, def. ‘[1 64]’
     Two-element vector ‘[ymin ymax]’ specifying the y coordinates of
     the first and last rows of the image.

     Setting ‘ydata’ to the empty matrix ([]) will restore the default
     value of ‘[1 rows(image)]’.


File: octave.info,  Node: Patch Properties,  Next: Surface Properties,  Prev: Image Properties,  Up: Graphics Object Properties

15.3.3.7 Patch Properties
.........................

The ‘patch’ properties are:

‘__modified__’: "off" | {"on"}

‘alphadatamapping’: "direct" | "none" | {"scaled"}
     Transparency is not yet implemented for patch objects.
     ‘alphadatamapping’ is unused.

‘ambientstrength’: scalar, def. ‘0.30000’
     Strength of the ambient light.  Value between 0.0 and 1.0

‘backfacelighting’: "lit" | {"reverselit"} | "unlit"
     "lit": The normals are used as is for lighting.  "reverselit": The
     normals are always oriented towards the point of view.  "unlit":
     Faces with normals pointing away from the point of view are unlit.

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’

‘cdata’: scalar | matrix, def. ‘[](0x0)’
     Data defining the patch object color.  Patch color can be defined
     for faces or for vertices.

     If ‘cdata’ is a scalar index into the current colormap or a RGB
     triplet, it defines the color of all faces.

     If ‘cdata’ is an N-by-1 vector of indices or an N-by-3 (RGB)
     matrix, it defines the color of each one of the N faces.

     If ‘cdata’ is an N-by-M or an N-by-M-by-3 (RGB) matrix, it defines
     the color at each vertex.

‘cdatamapping’: "direct" | {"scaled"}

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the patch is clipped in its parent axes
     limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after patch has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (0, "defaultpatchcreatefcn", 'disp ("patch
     created!")')’.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before patch is deleted.

‘diffusestrength’: scalar, def. ‘0.60000’
     Strength of the diffuse reflex.  Value between 0.0 (no diffuse
     reflex) and 1.0 (full diffuse reflex).

‘displayname’: def. ""
     Text of the legend entry corresponding to this patch.

‘edgealpha’: scalar | matrix, def. ‘1’
     Transparency is not yet implemented for patch objects.  ‘edgealpha’
     is unused.

‘edgecolor’: def. ‘[0 0 0]’

‘edgelighting’: "flat" | "gouraud" | {"none"} | "phong"
     When set to a value other than "none", the edges of the object are
     drawn with light and shadow effects.  Supported values are "none"
     (no lighting effects), "flat" (facetted look) and "gouraud" (linear
     interpolation of the lighting effects between the vertices).
     "phong" is deprecated and has the same effect as "gouraud".

‘facealpha’: scalar | matrix, def. ‘1’
     Transparency is not yet implemented for patch objects.  ‘facealpha’
     is unused.

‘facecolor’: {colorspec} | "none" | "flat" | "interp", def. ‘[0 0 0]’

‘facelighting’: {"flat"} | "gouraud" | "none" | "phong"
     When set to a value other than "none", the faces of the object are
     drawn with light and shadow effects.  Supported values are "none"
     (no lighting effects), "flat" (facetted look) and "gouraud" (linear
     interpolation of the lighting effects between the vertices).
     "phong" is deprecated and has the same effect as "gouraud".

‘facenormals’: def. ‘[](0x0)’

‘facenormalsmode’: {"auto"} | "manual"

‘faces’: def. ‘[1 2 3]’

‘facevertexalphadata’: scalar | matrix, def. ‘[](0x0)’
     Transparency is not yet implemented for patch objects.
     ‘facevertexalphadata’ is unused.

‘facevertexcdata’: def. ‘[](0x0)’

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the patch’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}

‘interpreter’: "latex" | "none" | {"tex"}
     ‘interpreter’ is unused.

‘interruptible’: "off" | {"on"}

‘linestyle’: {"-"} | "–" | "-." | ":" | "none"

‘linewidth’: def. ‘0.50000’

‘marker’: "*" | "+" | "." | "<" | ">" | "^" | "d" | "diamond" | "h" | "hexagram" | {"none"} | "o" | "p" | "pentagram" | "s" | "square" | "v" | "x"
     *Note line marker property: XREFlinemarker.

‘markeredgecolor’: {"auto"} | "flat" | "none"
     *Note line markeredgecolor property: XREFlinemarkeredgecolor.

‘markerfacecolor’: "auto" | "flat" | {"none"}
     *Note line markerfacecolor property: XREFlinemarkerfacecolor.

‘markersize’: scalar, def. ‘6’
     *Note line markersize property: XREFlinemarkersize.

‘parent’: graphics handle
     Handle of the parent graphics object.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘specularcolorreflectance’: scalar, def. ‘1’
     Reflectance for specular color.  Value between 0.0 (color of
     underlying face) and 1.0 (color of light source).

‘specularexponent’: scalar, def. ‘10’
     Exponent for the specular reflex.  The lower the value, the more
     the reflex is spread out.

‘specularstrength’: scalar, def. ‘0.90000’
     Strength of the specular reflex.  Value between 0.0 (no specular
     reflex) and 1.0 (full specular reflex).

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "patch"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this patch object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘vertexnormals’: def. ‘[](0x0)’

‘vertexnormalsmode’: {"auto"} | "manual"

‘vertices’: vector | matrix, def. 3-by-2 double

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the patch is not rendered on screen.

‘xdata’: vector | matrix, def. ‘[0; 1; 0]’

‘ydata’: vector | matrix, def. ‘[1; 1; 0]’

‘zdata’: vector | matrix, def. ‘[](0x0)’


File: octave.info,  Node: Surface Properties,  Next: Light Properties,  Prev: Patch Properties,  Up: Graphics Object Properties

15.3.3.8 Surface Properties
...........................

The ‘surface’ properties are:

‘__modified__’: "off" | {"on"}

‘alphadata’: scalar | matrix, def. ‘1’
     Transparency is not yet implemented for surface objects.
     ‘alphadata’ is unused.

‘alphadatamapping’: "direct" | "none" | {"scaled"}
     Transparency is not yet implemented for surface objects.
     ‘alphadatamapping’ is unused.

‘ambientstrength’: scalar, def. ‘0.30000’
     Strength of the ambient light.  Value between 0.0 and 1.0

‘backfacelighting’: "lit" | {"reverselit"} | "unlit"
     "lit": The normals are used as is for lighting.  "reverselit": The
     normals are always oriented towards the point of view.  "unlit":
     Faces with normals pointing away from the point of view are unlit.

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’

‘cdata’: matrix, def. 3-by-3 double

‘cdatamapping’: "direct" | {"scaled"}

‘cdatasource’: def. ""

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the surface is clipped in its parent axes
     limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after surface has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (0, "defaultsurfacecreatefcn", 'disp ("surface
     created!")')’.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before surface is deleted.

‘diffusestrength’: scalar, def. ‘0.60000’
     Strength of the diffuse reflex.  Value between 0.0 (no diffuse
     reflex) and 1.0 (full diffuse reflex).

‘displayname’: def. ""
     Text for the legend entry corresponding to this surface.

‘edgealpha’: scalar, def. ‘1’
     Transparency is not yet implemented for surface objects.
     ‘edgealpha’ is unused.

‘edgecolor’: def. ‘[0 0 0]’

‘edgelighting’: "flat" | "gouraud" | {"none"} | "phong"
     When set to a value other than "none", the edges of the object are
     drawn with light and shadow effects.  Supported values are "none"
     (no lighting effects), "flat" (facetted look) and "gouraud" (linear
     interpolation of the lighting effects between the vertices).
     "phong" is deprecated and has the same effect as "gouraud".

‘facealpha’: scalar | matrix, def. ‘1’
     Transparency is not yet implemented for surface objects.
     ‘facealpha’ is unused.

‘facecolor’: {"flat"} | "interp" | "none" | "texturemap"

‘facelighting’: {"flat"} | "gouraud" | "none" | "phong"
     When set to a value other than "none", the faces of the object are
     drawn with light and shadow effects.  Supported values are "none"
     (no lighting effects), "flat" (facetted look) and "gouraud" (linear
     interpolation of the lighting effects between the vertices).
     "phong" is deprecated and has the same effect as "gouraud".

‘facenormals’: def. ‘[](0x0)’

‘facenormalsmode’: {"auto"} | "manual"

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the surface’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}

‘interpreter’: "latex" | "none" | {"tex"}

‘interruptible’: "off" | {"on"}

‘linestyle’: {"-"} | "–" | "-." | ":" | "none"
     *Note Line Styles::.

‘linewidth’: def. ‘0.50000’
     *Note line linewidth property: XREFlinelinewidth.

‘marker’: "*" | "+" | "." | "<" | ">" | "^" | "d" | "diamond" | "h" | "hexagram" | {"none"} | "o" | "p" | "pentagram" | "s" | "square" | "v" | "x"
     *Note Marker Styles::.

‘markeredgecolor’: {"auto"} | "flat" | "none"
     *Note line markeredgecolor property: XREFlinemarkeredgecolor.

‘markerfacecolor’: "auto" | "flat" | {"none"}
     *Note line markerfacecolor property: XREFlinemarkerfacecolor.

‘markersize’: scalar, def. ‘6’
     *Note line markersize property: XREFlinemarkersize.

‘meshstyle’: {"both"} | "column" | "row"

‘parent’: graphics handle
     Handle of the parent graphics object.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘specularcolorreflectance’: scalar, def. ‘1’
     Reflectance for specular color.  Value between 0.0 (color of
     underlying face) and 1.0 (color of light source).

‘specularexponent’: scalar, def. ‘10’
     Exponent for the specular reflex.  The lower the value, the more
     the reflex is spread out.

‘specularstrength’: scalar, def. ‘0.90000’
     Strength of the specular reflex.  Value between 0.0 (no specular
     reflex) and 1.0 (full specular reflex).

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "surface"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this surface object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘vertexnormals’: def. 3-by-3-by-3 double

‘vertexnormalsmode’: {"auto"} | "manual"

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the surface is not rendered on screen.

‘xdata’: matrix, def. ‘[1 2 3]’

‘xdatasource’: def. ""

‘ydata’: matrix, def. ‘[1; 2; 3]’

‘ydatasource’: def. ""

‘zdata’: matrix, def. 3-by-3 double

‘zdatasource’: def. ""


File: octave.info,  Node: Light Properties,  Next: Uimenu Properties,  Prev: Surface Properties,  Up: Graphics Object Properties

15.3.3.9 Light Properties
.........................

The ‘light’ properties are:

‘__modified__’: "off" | {"on"}

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     ‘children’ is unused.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the light is clipped in its parent axes
     limits.

‘color’: colorspec, def. ‘[1 1 1]’
     Color of the light source.  *Note colorspec: Colors.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after light has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (0, "defaultlightcreatefcn", 'disp ("light
     created!")')’.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before light is deleted.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the light’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}

‘interruptible’: "off" | {"on"}

‘parent’: graphics handle
     Handle of the parent graphics object.

‘position’: def. ‘[1 0 1]’
     Position of the light source.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘style’: {"infinite"} | "local"
     This string defines whether the light emanates from a light source
     at infinite distance ("infinite") or from a local point source
     ("local").

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "light"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this light object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the light is not rendered on screen.


File: octave.info,  Node: Uimenu Properties,  Next: Uibuttongroup Properties,  Prev: Light Properties,  Up: Graphics Object Properties

15.3.3.10 Uimenu Properties
...........................

The ‘uimenu’ properties are:

‘__modified__’: "off" | {"on"}

‘accelerator’: def. ""

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘callback’: def. ‘[](0x0)’

‘checked’: {"off"} | "on"

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uimenu’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uimenu is clipped in its parent axes
     limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uimenu has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (0, "defaultuimenucreatefcn", 'disp ("uimenu
     created!")')’.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uimenu is deleted.

‘enable’: "off" | {"on"}

‘foregroundcolor’: def. ‘[0 0 0]’

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uimenu’s handle is not visible
     in its parent’s "children" property.

‘hittest’: "off" | {"on"}

‘interruptible’: "off" | {"on"}

‘label’: def. ""

‘parent’: graphics handle
     Handle of the parent graphics object.

‘position’: def. ‘0’

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘separator’: {"off"} | "on"

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uimenu"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uimenu object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uimenu is not rendered on screen.


File: octave.info,  Node: Uibuttongroup Properties,  Next: Uicontextmenu Properties,  Prev: Uimenu Properties,  Up: Graphics Object Properties

15.3.3.11 Uibuttongroup Properties
..................................

The ‘uibuttongroup’ properties are:

‘__modified__’: "off" | {"on"}

‘backgroundcolor’: def. ‘[1 1 1]’

‘beingdeleted’: {"off"} | "on"

‘bordertype’: "beveledin" | "beveledout" | {"etchedin"} | "etchedout" | "line" | "none"

‘borderwidth’: def. ‘1’

‘busyaction’: "cancel" | {"queue"}

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uibuttongroup’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uibuttongroup is clipped in its parent
     axes limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uibuttongroup has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (0, "defaultuibuttongroupcreatefcn", 'disp
     ("uibuttongroup created!")')’.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uibuttongroup is
     deleted.

‘fontangle’: "italic" | {"normal"} | "oblique"

‘fontname’: def. "*"

‘fontsize’: def. ‘10’

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}

‘fontweight’: "bold" | "demi" | "light" | {"normal"}

‘foregroundcolor’: def. ‘[0 0 0]’

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uibuttongroup’s handle is not
     visible in its parent’s "children" property.

‘highlightcolor’: def. ‘[1 1 1]’

‘hittest’: "off" | {"on"}

‘interruptible’: "off" | {"on"}

‘parent’: graphics handle
     Handle of the parent graphics object.

‘position’: def. ‘[0 0 1 1]’

‘resizefcn’: def. ‘[](0x0)’

‘selected’: {"off"} | "on"

‘selectedobject’: def. ‘[](0x0)’

‘selectionchangedfcn’: def. ‘[](0x0)’

‘selectionhighlight’: "off" | {"on"}

‘shadowcolor’: def. ‘[0 0 0]’

‘sizechangedfcn’: def. ‘[](0x0)’

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘title’: def. ""

‘titleposition’: "centerbottom" | "centertop" | "leftbottom" | {"lefttop"} | "rightbottom" | "righttop"

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always
     "uibuttongroup"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uibuttongroup object.

‘units’: "centimeters" | "characters" | "inches" | {"normalized"} | "pixels" | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uibuttongroup is not rendered on screen.


File: octave.info,  Node: Uicontextmenu Properties,  Next: Uipanel Properties,  Prev: Uibuttongroup Properties,  Up: Graphics Object Properties

15.3.3.12 Uicontextmenu Properties
..................................

The ‘uicontextmenu’ properties are:

‘__modified__’: "off" | {"on"}

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘callback’: def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uicontextmenu’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uicontextmenu is clipped in its parent
     axes limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uicontextmenu has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (0, "defaultuicontextmenucreatefcn", 'disp
     ("uicontextmenu created!")')’.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uicontextmenu is
     deleted.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uicontextmenu’s handle is not
     visible in its parent’s "children" property.

‘hittest’: "off" | {"on"}

‘interruptible’: "off" | {"on"}

‘parent’: graphics handle
     Handle of the parent graphics object.

‘position’: def. ‘[0 0]’

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always
     "uicontextmenu"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uicontextmenu object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uicontextmenu is not rendered on screen.


File: octave.info,  Node: Uipanel Properties,  Next: Uicontrol Properties,  Prev: Uicontextmenu Properties,  Up: Graphics Object Properties

15.3.3.13 Uipanel Properties
............................

The ‘uipanel’ properties are:

‘__modified__’: "off" | {"on"}

‘backgroundcolor’: def. ‘[1 1 1]’

‘beingdeleted’: {"off"} | "on"

‘bordertype’: "beveledin" | "beveledout" | {"etchedin"} | "etchedout" | "line" | "none"

‘borderwidth’: def. ‘1’

‘busyaction’: "cancel" | {"queue"}

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uipanel’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uipanel is clipped in its parent axes
     limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uipanel has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (0, "defaultuipanelcreatefcn", 'disp ("uipanel
     created!")')’.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uipanel is deleted.

‘fontangle’: "italic" | {"normal"} | "oblique"

‘fontname’: def. "*"

‘fontsize’: def. ‘10’

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}

‘fontweight’: "bold" | "demi" | "light" | {"normal"}

‘foregroundcolor’: def. ‘[0 0 0]’

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uipanel’s handle is not visible
     in its parent’s "children" property.

‘highlightcolor’: def. ‘[1 1 1]’

‘hittest’: "off" | {"on"}

‘interruptible’: "off" | {"on"}

‘parent’: graphics handle
     Handle of the parent graphics object.

‘position’: def. ‘[0 0 1 1]’

‘resizefcn’: def. ‘[](0x0)’

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘shadowcolor’: def. ‘[0 0 0]’

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘title’: def. ""

‘titleposition’: "centerbottom" | "centertop" | "leftbottom" | {"lefttop"} | "rightbottom" | "righttop"

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uipanel"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uipanel object.

‘units’: "centimeters" | "characters" | "inches" | {"normalized"} | "pixels" | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uipanel is not rendered on screen.


File: octave.info,  Node: Uicontrol Properties,  Next: Uitoolbar Properties,  Prev: Uipanel Properties,  Up: Graphics Object Properties

15.3.3.14 Uicontrol Properties
..............................

The ‘uicontrol’ properties are:

‘__modified__’: "off" | {"on"}

‘backgroundcolor’: def. ‘[1 1 1]’

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’

‘callback’: def. ‘[](0x0)’

‘cdata’: def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uicontrol’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uicontrol is clipped in its parent axes
     limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uicontrol has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (0, "defaultuicontrolcreatefcn", 'disp ("uicontrol
     created!")')’.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uicontrol is deleted.

‘enable’: "inactive" | "off" | {"on"}

‘extent’ (read-only): def. ‘[0 0 0 0]’

‘fontangle’: "italic" | {"normal"} | "oblique"

‘fontname’: def. "*"

‘fontsize’: def. ‘10’

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}

‘fontweight’: "bold" | "demi" | "light" | {"normal"}

‘foregroundcolor’: def. ‘[0 0 0]’

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uicontrol’s handle is not
     visible in its parent’s "children" property.

‘hittest’: "off" | {"on"}

‘horizontalalignment’: {"center"} | "left" | "right"

‘interruptible’: "off" | {"on"}

‘keypressfcn’: def. ‘[](0x0)’

‘listboxtop’: def. ‘1’

‘max’: def. ‘1’

‘min’: def. ‘0’

‘parent’: graphics handle
     Handle of the parent graphics object.

‘position’: def. ‘[0 0 80 30]’

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘sliderstep’: def. ‘[0.010000 0.100000]’

‘string’: def. ""

‘style’: "checkbox" | "edit" | "frame" | "listbox" | "popupmenu" | {"pushbutton"} | "radiobutton" | "slider" | "text" | "togglebutton"

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘tooltipstring’: def. ""

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uicontrol"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uicontrol object.

‘units’: "centimeters" | "characters" | "inches" | "normalized" | {"pixels"} | "points"

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘value’: def. ‘1’

‘verticalalignment’: "bottom" | {"middle"} | "top"

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uicontrol is not rendered on screen.


File: octave.info,  Node: Uitoolbar Properties,  Next: Uipushtool Properties,  Prev: Uicontrol Properties,  Up: Graphics Object Properties

15.3.3.15 Uitoolbar Properties
..............................

The ‘uitoolbar’ properties are:

‘__modified__’: "off" | {"on"}

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uitoolbar’s children.

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uitoolbar is clipped in its parent axes
     limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uitoolbar has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (0, "defaultuitoolbarcreatefcn", 'disp ("uitoolbar
     created!")')’.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uitoolbar is deleted.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uitoolbar’s handle is not
     visible in its parent’s "children" property.

‘hittest’: "off" | {"on"}

‘interruptible’: "off" | {"on"}

‘parent’: graphics handle
     Handle of the parent graphics object.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uitoolbar"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uitoolbar object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uitoolbar is not rendered on screen.


File: octave.info,  Node: Uipushtool Properties,  Next: Uitoggletool Properties,  Prev: Uitoolbar Properties,  Up: Graphics Object Properties

15.3.3.16 Uipushtool Properties
...............................

The ‘uipushtool’ properties are:

‘__modified__’: "off" | {"on"}

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘cdata’: def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uipushtool’s children.

‘clickedcallback’: def. ‘[](0x0)’

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uipushtool is clipped in its parent axes
     limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uipushtool has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (0, "defaultuipushtoolcreatefcn", 'disp ("uipushtool
     created!")')’.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uipushtool is
     deleted.

‘enable’: "off" | {"on"}

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uipushtool’s handle is not
     visible in its parent’s "children" property.

‘hittest’: "off" | {"on"}

‘interruptible’: "off" | {"on"}

‘parent’: graphics handle
     Handle of the parent graphics object.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘separator’: {"off"} | "on"

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘tooltipstring’: def. ""

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uipushtool"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uipushtool object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uipushtool is not rendered on screen.


File: octave.info,  Node: Uitoggletool Properties,  Prev: Uipushtool Properties,  Up: Graphics Object Properties

15.3.3.17 Uitoggletool Properties
.................................

The ‘uitoggletool’ properties are:

‘__modified__’: "off" | {"on"}

‘beingdeleted’: {"off"} | "on"

‘busyaction’: "cancel" | {"queue"}

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘cdata’: def. ‘[](0x0)’

‘children’ (read-only): vector of graphics handles, def. ‘[](0x1)’
     Graphics handles of the uitoggletool’s children.

‘clickedcallback’: def. ‘[](0x0)’

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uitoggletool is clipped in its parent
     axes limits.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uitoggletool has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (0, "defaultuitoggletoolcreatefcn", 'disp ("uitoggletool
     created!")')’.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uitoggletool is
     deleted.

‘enable’: "off" | {"on"}

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uitoggletool’s handle is not
     visible in its parent’s "children" property.

‘hittest’: "off" | {"on"}

‘interruptible’: "off" | {"on"}

‘offcallback’: def. ‘[](0x0)’

‘oncallback’: def. ‘[](0x0)’

‘parent’: graphics handle
     Handle of the parent graphics object.

‘selected’: {"off"} | "on"

‘selectionhighlight’: "off" | {"on"}

‘separator’: {"off"} | "on"

‘state’: {"off"} | "on"

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘tooltipstring’: def. ""

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uitoggletool"

‘uicontextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uitoggletool object.

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uitoggletool is not rendered on screen.


File: octave.info,  Node: Searching Properties,  Next: Managing Default Properties,  Prev: Graphics Object Properties,  Up: Graphics Data Structures

15.3.4 Searching Properties
---------------------------

 -- : H = findobj ()
 -- : H = findobj (PROP_NAME, PROP_VALUE, ...)
 -- : H = findobj (PROP_NAME, PROP_VALUE, "-LOGICAL_OP", PROP_NAME,
          PROP_VALUE)
 -- : H = findobj ("-property", PROP_NAME)
 -- : H = findobj ("-regexp", PROP_NAME, PATTERN)
 -- : H = findobj (HLIST, ...)
 -- : H = findobj (HLIST, "flat", ...)
 -- : H = findobj (HLIST, "-depth", D, ...)
     Find graphics object with specified property values.

     The simplest form is

          findobj (PROP_NAME, PROP_VALUE)

     which returns the handles of all objects which have a property
     named PROP_NAME that has the value PROP_VALUE.  If multiple
     property/value pairs are specified then only objects meeting all of
     the conditions are returned.

     The search can be limited to a particular set of objects and their
     descendants, by passing a handle or set of handles HLIST as the
     first argument.

     The depth of the object hierarchy to search can be limited with the
     "-depth" argument.  An example of searching only three generations
     of children is:

          findobj (HLIST, "-depth", 3, PROP_NAME, PROP_VALUE)

     Specifying a depth D of 0, limits the search to the set of objects
     passed in HLIST.  A depth D of 0 is equivalent to the "flat"
     argument.

     A specified logical operator may be applied to the pairs of
     PROP_NAME and PROP_VALUE.  The supported logical operators are:
     "-and", "-or", "-xor", "-not".

     Objects may also be matched by comparing a regular expression to
     the property values, where property values that match ‘regexp
     (PROP_VALUE, PATTERN)’ are returned.

     Finally, objects may be matched by property name only by using the
     "-property" option.

     Implementation Note: The search only includes objects with visible
     handles (HandleVisibility = "on").  *Note findall: XREFfindall, to
     search for all objects including hidden ones.

     See also: *note findall: XREFfindall, *note allchild: XREFallchild,
     *note get: XREFget, *note set: XREFset.

 -- : H = findall ()
 -- : H = findall (PROP_NAME, PROP_VALUE, ...)
 -- : H = findall (PROP_NAME, PROP_VALUE, "-LOGICAL_OP", PROP_NAME,
          PROP_VALUE)
 -- : H = findall ("-property", PROP_NAME)
 -- : H = findall ("-regexp", PROP_NAME, PATTERN)
 -- : H = findall (HLIST, ...)
 -- : H = findall (HLIST, "flat", ...)
 -- : H = findall (HLIST, "-depth", D, ...)
     Find graphics object, including hidden ones, with specified
     property values.

     The return value H is a list of handles to the found graphic
     objects.

     ‘findall’ performs the same search as ‘findobj’, but it includes
     hidden objects (HandleVisibility = "off").  For full documentation,
     *note findobj: XREFfindobj.

     See also: *note findobj: XREFfindobj, *note allchild: XREFallchild,
     *note get: XREFget, *note set: XREFset.


File: octave.info,  Node: Managing Default Properties,  Prev: Searching Properties,  Up: Graphics Data Structures

15.3.5 Managing Default Properties
----------------------------------

Object properties have two classes of default values, “factory defaults”
(the initial values) and “user-defined defaults”, which may override the
factory defaults.

   Although default values may be set for any object, they are set in
parent objects and apply to child objects, of the specified object type.
For example, setting the default ‘color’ property of ‘line’ objects to
"green", for the ‘root’ object, will result in all ‘line’ objects
inheriting the ‘color’ "green" as the default value.

     set (0, "defaultlinecolor", "green");

sets the default line color for all objects.  The rule for constructing
the property name to set a default value is

     default + OBJECT-TYPE + PROPERTY-NAME

   This rule can lead to some strange looking names, for example
‘defaultlinelinewidth"’ specifies the default ‘linewidth’ property for
‘line’ objects.

   The example above used the root figure object, 0, so the default
property value will apply to all line objects.  However, default values
are hierarchical, so defaults set in a figure objects override those set
in the root figure object.  Likewise, defaults set in axes objects
override those set in figure or root figure objects.  For example,

     subplot (2, 1, 1);
     set (0, "defaultlinecolor", "red");
     set (1, "defaultlinecolor", "green");
     set (gca (), "defaultlinecolor", "blue");
     line (1:10, rand (1, 10));
     subplot (2, 1, 2);
     line (1:10, rand (1, 10));
     figure (2)
     line (1:10, rand (1, 10));

produces two figures.  The line in first subplot window of the first
figure is blue because it inherits its color from its parent axes
object.  The line in the second subplot window of the first figure is
green because it inherits its color from its parent figure object.  The
line in the second figure window is red because it inherits its color
from the global root figure parent object.

   To remove a user-defined default setting, set the default property to
the value "remove".  For example,

     set (gca (), "defaultlinecolor", "remove");

removes the user-defined default line color setting from the current
axes object.  To quickly remove all user-defined defaults use the
‘reset’ function.

 -- : reset (H)
     Reset the properties of the graphic object H to their default
     values.

     For figures, the properties "position", "units", "windowstyle", and
     "paperunits" are not affected.  For axes, the properties "position"
     and "units" are not affected.

     The input H may also be a vector of graphic handles in which case
     each individual object will be reset.

     See also: *note cla: XREFcla, *note clf: XREFclf, *note newplot:
     XREFnewplot.

   Getting the "default" property of an object returns a list of
user-defined defaults set for the object.  For example,

     get (gca (), "default");

returns a list of user-defined default values for the current axes
object.

   Factory default values are stored in the root figure object.  The
command

     get (0, "factory");

returns a list of factory defaults.


File: octave.info,  Node: Advanced Plotting,  Prev: Graphics Data Structures,  Up: Plotting

15.4 Advanced Plotting
======================

* Menu:

* Colors::
* Line Styles::
* Marker Styles::
* Callbacks::
* Application-defined Data::
* Object Groups::
* Graphics Toolkits::


File: octave.info,  Node: Colors,  Next: Line Styles,  Up: Advanced Plotting

15.4.1 Colors
-------------

Colors may be specified as RGB triplets with values ranging from zero to
one, or by name.  Recognized color names include "blue", "black",
"cyan", "green", "magenta", "red", "white", and "yellow".


File: octave.info,  Node: Line Styles,  Next: Marker Styles,  Prev: Colors,  Up: Advanced Plotting

15.4.2 Line Styles
------------------

Line styles are specified by the following properties:

‘linestyle’
     May be one of

     "-"
          Solid line.  [default]

     "--"
          Dashed line.

     ":"
          Dotted line.

     "-."
          A dash-dot line.

     "none"
          No line.  Points will still be marked using the current Marker
          Style.

‘linewidth’
     A number specifying the width of the line.  The default is 1.  A
     value of 2 is twice as wide as the default, etc.


File: octave.info,  Node: Marker Styles,  Next: Callbacks,  Prev: Line Styles,  Up: Advanced Plotting

15.4.3 Marker Styles
--------------------

Marker styles are specified by the following properties:

‘marker’
     A character indicating a plot marker to be place at each data
     point, or "none", meaning no markers should be displayed.

‘markeredgecolor’
     The color of the edge around the marker, or "auto", meaning that
     the edge color is the same as the face color.  *Note Colors::.

‘markerfacecolor’
     The color of the marker, or "none" to indicate that the marker
     should not be filled.  *Note Colors::.

‘markersize’
     A number specifying the size of the marker.  The default is 1.  A
     value of 2 is twice as large as the default, etc.

   The ‘colstyle’ function will parse a ‘plot’-style specification and
will return the color, line, and marker values that would result.

 -- : [STYLE, COLOR, MARKER, MSG] = colstyle (LINESPEC)
     Parse LINESPEC and return the line style, color, and markers given.

     In the case of an error, the string MSG will return the text of the
     error.


File: octave.info,  Node: Callbacks,  Next: Application-defined Data,  Prev: Marker Styles,  Up: Advanced Plotting

15.4.4 Callbacks
----------------

Callback functions can be associated with graphics objects and triggered
after certain events occur.  The basic structure of all callback
function is

     function mycallback (src, data)
     ...
     endfunction

where ‘src’ gives a handle to the source of the callback, and ‘code’
gives some event specific data.  This can then be associated with an
object either at the objects creation or later with the ‘set’ function.
For example,

     plot (x, "DeleteFcn", @(s, e) disp ("Window Deleted"))

where at the moment that the plot is deleted, the message "Window
Deleted" will be displayed.

   Additional user arguments can be passed to callback functions, and
will be passed after the 2 default arguments.  For example:

     plot (x, "DeleteFcn", {@mycallback, "1"})
     ...
     function mycallback (src, data, a1)
       fprintf ("Closing plot %d\n", a1);
     endfunction

   The basic callback functions that are available for all graphics
objects are

   • CreateFcn This is the callback that is called at the moment of the
     objects creation.  It is not called if the object is altered in any
     way, and so it only makes sense to define this callback in the
     function call that defines the object.  Callbacks that are added to
     ‘CreateFcn’ later with the ‘set’ function will never be executed.

   • DeleteFcn This is the callback that is called at the moment an
     object is deleted.

   • ButtonDownFcn This is the callback that is called if a mouse button
     is pressed while the pointer is over this object.  Note, that the
     gnuplot interface does not respect this callback.

   The object and figure that the event occurred in that resulted in the
callback being called can be found with the ‘gcbo’ and ‘gcbf’ functions.

 -- : H = gcbo ()
 -- : [H, FIG] = gcbo ()
     Return a handle to the object whose callback is currently
     executing.

     If no callback is executing, this function returns the empty
     matrix.  This handle is obtained from the root object property
     "CallbackObject".

     When called with a second output argument, return the handle of the
     figure containing the object whose callback is currently executing.
     If no callback is executing the second output is also set to the
     empty matrix.

     See also: *note gcbf: XREFgcbf, *note gco: XREFgco, *note gca:
     XREFgca, *note gcf: XREFgcf, *note get: XREFget, *note set:
     XREFset.

 -- : FIG = gcbf ()
     Return a handle to the figure containing the object whose callback
     is currently executing.

     If no callback is executing, this function returns the empty
     matrix.  The handle returned by this function is the same as the
     second output argument of ‘gcbo’.

     See also: *note gcbo: XREFgcbo, *note gcf: XREFgcf, *note gco:
     XREFgco, *note gca: XREFgca, *note get: XREFget, *note set:
     XREFset.

   Callbacks can equally be added to properties with the ‘addlistener’
function described below.


File: octave.info,  Node: Application-defined Data,  Next: Object Groups,  Prev: Callbacks,  Up: Advanced Plotting

15.4.5 Application-defined Data
-------------------------------

Octave has a provision for attaching application-defined data to a
graphics handle.  The data can be anything which is meaningful to the
application, and will be completely ignored by Octave.

 -- : setappdata (H, NAME, VALUE)
 -- : setappdata (H, NAME1, VALUE1, NAME2, VALUE3, ...)
     Set the application data NAME to VALUE for the graphics object with
     handle H.

     H may also be a vector of graphics handles.  If the application
     data with the specified NAME does not exist, it is created.
     Multiple NAME/VALUE pairs can be specified at a time.

     See also: *note getappdata: XREFgetappdata, *note isappdata:
     XREFisappdata, *note rmappdata: XREFrmappdata, *note guidata:
     XREFguidata, *note get: XREFget, *note set: XREFset, *note getpref:
     XREFgetpref, *note setpref: XREFsetpref.

 -- : VALUE = getappdata (H, NAME)
 -- : APPDATA = getappdata (H)
     Return the VALUE of the application data NAME for the graphics
     object with handle H.

     H may also be a vector of graphics handles.  If no second argument
     NAME is given then ‘getappdata’ returns a structure, APPDATA, whose
     fields correspond to the appdata properties.

     See also: *note setappdata: XREFsetappdata, *note isappdata:
     XREFisappdata, *note rmappdata: XREFrmappdata, *note guidata:
     XREFguidata, *note get: XREFget, *note set: XREFset, *note getpref:
     XREFgetpref, *note setpref: XREFsetpref.

 -- : rmappdata (H, NAME)
 -- : rmappdata (H, NAME1, NAME2, ...)
     Delete the application data NAME from the graphics object with
     handle H.

     H may also be a vector of graphics handles.  Multiple application
     data names may be supplied to delete several properties at once.

     See also: *note setappdata: XREFsetappdata, *note getappdata:
     XREFgetappdata, *note isappdata: XREFisappdata.

 -- : VALID = isappdata (H, NAME)
     Return true if the named application data, NAME, exists for the
     graphics object with handle H.

     H may also be a vector of graphics handles.

     See also: *note getappdata: XREFgetappdata, *note setappdata:
     XREFsetappdata, *note rmappdata: XREFrmappdata, *note guidata:
     XREFguidata, *note get: XREFget, *note set: XREFset, *note getpref:
     XREFgetpref, *note setpref: XREFsetpref.


File: octave.info,  Node: Object Groups,  Next: Graphics Toolkits,  Prev: Application-defined Data,  Up: Advanced Plotting

15.4.6 Object Groups
--------------------

A number of Octave high level plot functions return groups of other
graphics objects or they return graphics objects that have their
properties linked in such a way that changes to one of the properties
results in changes in the others.  A graphic object that groups other
objects is an ‘hggroup’

 -- : hggroup ()
 -- : hggroup (HAX)
 -- : hggroup (..., PROPERTY, VALUE, ...)
 -- : H = hggroup (...)
     Create handle graphics group object with axes parent HAX.

     If no parent is specified, the group is created in the current
     axes.

     Multiple property/value pairs may be specified for the hggroup, but
     they must appear in pairs.

     The optional return value H is a graphics handle to the created
     hggroup object.

     Programming Note: An hggroup is a way to group base graphics
     objects such as line objects or patch objects into a single unit
     which can react appropriately.  For example, the individual lines
     of a contour plot are collected into a single hggroup so that they
     can be made visible/invisible with a single command, ‘set
     (hg_handle, "visible", "off")’.

     See also: *note addproperty: XREFaddproperty, *note addlistener:
     XREFaddlistener.

   For example a simple use of a ‘hggroup’ might be

     x = 0:0.1:10;
     hg = hggroup ();
     plot (x, sin (x), "color", [1, 0, 0], "parent", hg);
     hold on
     plot (x, cos (x), "color", [0, 1, 0], "parent", hg);
     set (hg, "visible", "off");

which groups the two plots into a single object and controls their
visibility directly.  The default properties of an ‘hggroup’ are the
same as the set of common properties for the other graphics objects.
Additional properties can be added with the ‘addproperty’ function.

 -- : addproperty (NAME, H, TYPE)
 -- : addproperty (NAME, H, TYPE, ARG, ...)
     Create a new property named NAME in graphics object H.

     TYPE determines the type of the property to create.  ARGS usually
     contains the default value of the property, but additional
     arguments might be given, depending on the type of the property.

     The supported property types are:

     ‘string’
          A string property.  ARG contains the default string value.

     ‘any’
          An un-typed property.  This kind of property can hold any
          octave value.  ARGS contains the default value.

     ‘radio’
          A string property with a limited set of accepted values.  The
          first argument must be a string with all accepted values
          separated by a vertical bar (’|’).  The default value can be
          marked by enclosing it with a ’{’ ’}’ pair.  The default value
          may also be given as an optional second string argument.

     ‘boolean’
          A boolean property.  This property type is equivalent to a
          radio property with "on|off" as accepted values.  ARG contains
          the default property value.

     ‘double’
          A scalar double property.  ARG contains the default value.

     ‘handle’
          A handle property.  This kind of property holds the handle of
          a graphics object.  ARG contains the default handle value.
          When no default value is given, the property is initialized to
          the empty matrix.

     ‘data’
          A data (matrix) property.  ARG contains the default data
          value.  When no default value is given, the data is
          initialized to the empty matrix.

     ‘color’
          A color property.  ARG contains the default color value.  When
          no default color is given, the property is set to black.  An
          optional second string argument may be given to specify an
          additional set of accepted string values (like a radio
          property).

     TYPE may also be the concatenation of a core object type and a
     valid property name for that object type.  The property created
     then has the same characteristics as the referenced property (type,
     possible values, hidden state...).  This allows one to clone an
     existing property into the graphics object H.

     Examples:

          addproperty ("my_property", gcf, "string", "a string value");
          addproperty ("my_radio", gcf, "radio", "val_1|val_2|{val_3}");
          addproperty ("my_style", gcf, "linelinestyle", "--");

     See also: *note addlistener: XREFaddlistener, *note hggroup:
     XREFhggroup.

   Once a property in added to an ‘hggroup’, it is not linked to any
other property of either the children of the group, or any other
graphics object.  Add so to control the way in which this newly added
property is used, the ‘addlistener’ function is used to define a
callback function that is executed when the property is altered.

 -- : addlistener (H, PROP, FCN)
     Register FCN as listener for the property PROP of the graphics
     object H.

     Property listeners are executed (in order of registration) when the
     property is set.  The new value is already available when the
     listeners are executed.

     PROP must be a string naming a valid property in H.

     FCN can be a function handle, a string or a cell array whose first
     element is a function handle.  If FCN is a function handle, the
     corresponding function should accept at least 2 arguments, that
     will be set to the object handle and the empty matrix respectively.
     If FCN is a string, it must be any valid octave expression.  If FCN
     is a cell array, the first element must be a function handle with
     the same signature as described above.  The next elements of the
     cell array are passed as additional arguments to the function.

     Example:

          function my_listener (h, dummy, p1)
            fprintf ("my_listener called with p1=%s\n", p1);
          endfunction

          addlistener (gcf, "position", {@my_listener, "my string"})

     See also: *note addproperty: XREFaddproperty, *note hggroup:
     XREFhggroup.

 -- : dellistener (H, PROP, FCN)
     Remove the registration of FCN as a listener for the property PROP
     of the graphics object H.

     The function FCN must be the same variable (not just the same
     value), as was passed to the original call to ‘addlistener’.

     If FCN is not defined then all listener functions of PROP are
     removed.

     Example:

          function my_listener (h, dummy, p1)
            fprintf ("my_listener called with p1=%s\n", p1);
          endfunction

          c = {@my_listener, "my string"};
          addlistener (gcf, "position", c);
          dellistener (gcf, "position", c);

   An example of the use of these two functions might be

     x = 0:0.1:10;
     hg = hggroup ();
     h = plot (x, sin (x), "color", [1, 0, 0], "parent", hg);
     addproperty ("linestyle", hg, "linelinestyle", get (h, "linestyle"));
     addlistener (hg, "linestyle", @update_props);
     hold on
     plot (x, cos (x), "color", [0, 1, 0], "parent", hg);

     function update_props (h, d)
       set (get (h, "children"), "linestyle", get (h, "linestyle"));
     endfunction

that adds a ‘linestyle’ property to the ‘hggroup’ and propagating any
changes its value to the children of the group.  The ‘linkprop’ function
can be used to simplify the above to be

     x = 0:0.1:10;
     hg = hggroup ();
     h1 = plot (x, sin (x), "color", [1, 0, 0], "parent", hg);
     addproperty ("linestyle", hg, "linelinestyle", get (h, "linestyle"));
     hold on
     h2 = plot (x, cos (x), "color", [0, 1, 0], "parent", hg);
     hlink = linkprop ([hg, h1, h2], "color");

 -- : HLINK = linkprop (H, "PROP")
 -- : HLINK = linkprop (H, {"PROP1", "PROP2", ...})
     Link graphic object properties, such that a change in one is
     propagated to the others.

     The input H is a vector of graphic handles to link.

     PROP may be a string when linking a single property, or a cell
     array of strings for multiple properties.  During the linking
     process all properties in PROP will initially be set to the values
     that exist on the first object in the list H.

     The function returns HLINK which is a special object describing the
     link.  As long as the reference HLINK exists the link between
     graphic objects will be active.  This means that HLINK must be
     preserved in a workspace variable, a global variable, or otherwise
     stored using a function such as ‘setappdata’, ‘guidata’.  To unlink
     properties, execute ‘clear HLINK’.

     An example of the use of ‘linkprop’ is

          x = 0:0.1:10;
          subplot (1,2,1);
          h1 = plot (x, sin (x));
          subplot (1,2,2);
          h2 = plot (x, cos (x));
          hlink = linkprop ([h1, h2], {"color","linestyle"});
          set (h1, "color", "green");
          set (h2, "linestyle", "--");

     See also: *note linkaxes: XREFlinkaxes.

 -- : linkaxes (HAX)
 -- : linkaxes (HAX, OPTSTR)
     Link the axis limits of 2-D plots such that a change in one is
     propagated to the others.

     The axes handles to be linked are passed as the first argument HAX.

     The optional second argument is a string which defines which axis
     limits will be linked.  The possible values for OPTSTR are:

     "x"
          Link x-axes

     "y"
          Link y-axes

     "xy" (default)
          Link both axes

     "off"
          Turn off linking

     If unspecified the default is to link both X and Y axes.

     When linking, the limits from the first axes in HAX are applied to
     the other axes in the list.  Subsequent changes to any one of the
     axes will be propagated to the others.

     See also: *note linkprop: XREFlinkprop, *note addproperty:
     XREFaddproperty.

   These capabilities are used in a number of basic graphics objects.
The ‘hggroup’ objects created by the functions of Octave contain one or
more graphics object and are used to:

   • group together multiple graphics objects,

   • create linked properties between different graphics objects, and

   • to hide the nominal user data, from the actual data of the objects.

For example the ‘stem’ function creates a stem series where each
‘hggroup’ of the stem series contains two line objects representing the
body and head of the stem.  The ‘ydata’ property of the ‘hggroup’ of the
stem series represents the head of the stem, whereas the body of the
stem is between the baseline and this value.  For example

     h = stem (1:4)
     get (h, "xdata")
     ⇒ [  1   2   3   4]'
     get (get (h, "children")(1), "xdata")
     ⇒ [  1   1 NaN   2   2 NaN   3   3 NaN   4   4 NaN]'

shows the difference between the ‘xdata’ of the ‘hggroup’ of a stem
series object and the underlying line.

   The basic properties of such group objects is that they consist of
one or more linked ‘hggroup’, and that changes in certain properties of
these groups are propagated to other members of the group.  Whereas,
certain properties of the members of the group only apply to the current
member.

   In addition the members of the group can also be linked to other
graphics objects through callback functions.  For example the baseline
of the ‘bar’ or ‘stem’ functions is a line object, whose length and
position are automatically adjusted, based on changes to the
corresponding hggroup elements.

* Menu:

* Data Sources in Object Groups::
* Area Series::
* Bar Series::
* Contour Groups::
* Error Bar Series::
* Line Series::
* Quiver Group::
* Scatter Group::
* Stair Group::
* Stem Series::
* Surface Group::


File: octave.info,  Node: Data Sources in Object Groups,  Next: Area Series,  Up: Object Groups

15.4.6.1 Data Sources in Object Groups
......................................

All of the group objects contain data source parameters.  There are
string parameters that contain an expression that is evaluated to update
the relevant data property of the group when the ‘refreshdata’ function
is called.

 -- : refreshdata ()
 -- : refreshdata (H)
 -- : refreshdata (H, WORKSPACE)
     Evaluate any ‘datasource’ properties of the current figure and
     update the plot if the corresponding data has changed.

     If the first argument H is a list of graphic handles, then operate
     on these objects rather than the current figure returned by ‘gcf’.

     The optional second argument WORKSPACE can take the following
     values:

     "base"
          Evaluate the datasource properties in the base workspace.
          (default).

     "caller"
          Evaluate the datasource properties in the workspace of the
          function that called ‘refreshdata’.

     An example of the use of ‘refreshdata’ is:

          x = 0:0.1:10;
          y = sin (x);
          plot (x, y, "ydatasource", "y");
          for i = 1 : 100
            pause (0.1);
            y = sin (x + 0.1*i);
            refreshdata ();
          endfor


File: octave.info,  Node: Area Series,  Next: Bar Series,  Prev: Data Sources in Object Groups,  Up: Object Groups

15.4.6.2 Area Series
....................

Area series objects are created by the ‘area’ function.  Each of the
‘hggroup’ elements contains a single patch object.  The properties of
the area series are

‘basevalue’
     The value where the base of the area plot is drawn.

‘linewidth’
‘linestyle’
     The line width and style of the edge of the patch objects making up
     the areas.  *Note Line Styles::.

‘edgecolor’
‘facecolor’
     The line and fill color of the patch objects making up the areas.
     *Note Colors::.

‘xdata’
‘ydata’
     The x and y coordinates of the original columns of the data passed
     to ‘area’ prior to the cumulative summation used in the ‘area’
     function.

‘xdatasource’
‘ydatasource’
     Data source variables.


File: octave.info,  Node: Bar Series,  Next: Contour Groups,  Prev: Area Series,  Up: Object Groups

15.4.6.3 Bar Series
...................

Bar series objects are created by the ‘bar’ or ‘barh’ functions.  Each
‘hggroup’ element contains a single patch object.  The properties of the
bar series are

‘showbaseline’
‘baseline’
‘basevalue’
     The property ‘showbaseline’ flags whether the baseline of the bar
     series is displayed (default is "on").  The handle of the graphics
     object representing the baseline is given by the ‘baseline’
     property and the y-value of the baseline by the ‘basevalue’
     property.

     Changes to any of these properties are propagated to the other
     members of the bar series and to the baseline itself.  Equally,
     changes in the properties of the base line itself are propagated to
     the members of the corresponding bar series.

‘barwidth’
‘barlayout’
‘horizontal’
     The property ‘barwidth’ is the width of the bar corresponding to
     the WIDTH variable passed to ‘bar’ or BARH.  Whether the bar series
     is "grouped" or "stacked" is determined by the ‘barlayout’ property
     and whether the bars are horizontal or vertical by the ‘horizontal’
     property.

     Changes to any of these property are propagated to the other
     members of the bar series.

‘linewidth’
‘linestyle’
     The line width and style of the edge of the patch objects making up
     the bars.  *Note Line Styles::.

‘edgecolor’
‘facecolor’
     The line and fill color of the patch objects making up the bars.
     *Note Colors::.

‘xdata’
     The nominal x positions of the bars.  Changes in this property and
     propagated to the other members of the bar series.

‘ydata’
     The y value of the bars in the ‘hggroup’.

‘xdatasource’
‘ydatasource’
     Data source variables.


File: octave.info,  Node: Contour Groups,  Next: Error Bar Series,  Prev: Bar Series,  Up: Object Groups

15.4.6.4 Contour Groups
.......................

Contour group objects are created by the ‘contour’, ‘contourf’ and
‘contour3’ functions.  The are equally one of the handles returned by
the ‘surfc’ and ‘meshc’ functions.  The properties of the contour group
are

‘contourmatrix’
     A read only property that contains the data return by ‘contourc’
     used to create the contours of the plot.

‘fill’
     A radio property that can have the values "on" or "off" that flags
     whether the contours to plot are to be filled.

‘zlevelmode’
‘zlevel’
     The radio property ‘zlevelmode’ can have the values "none", "auto",
     or "manual".  When its value is "none" there is no z component to
     the plotted contours.  When its value is "auto" the z value of the
     plotted contours is at the same value as the contour itself.  If
     the value is "manual", then the z value at which to plot the
     contour is determined by the ‘zlevel’ property.

‘levellistmode’
‘levellist’
‘levelstepmode’
‘levelstep’
     If ‘levellistmode’ is "manual", then the levels at which to plot
     the contours is determined by ‘levellist’.  If ‘levellistmode’ is
     set to "auto", then the distance between contours is determined by
     ‘levelstep’.  If both ‘levellistmode’ and ‘levelstepmode’ are set
     to "auto", then there are assumed to be 10 equal spaced contours.

‘textlistmode’
‘textlist’
‘textstepmode’
‘textstep’
     If ‘textlistmode’ is "manual", then the labeled contours is
     determined by ‘textlist’.  If ‘textlistmode’ is set to "auto", then
     the distance between labeled contours is determined by ‘textstep’.
     If both ‘textlistmode’ and ‘textstepmode’ are set to "auto", then
     there are assumed to be 10 equal spaced labeled contours.

‘showtext’
     Flag whether the contour labels are shown or not.

‘labelspacing’
     The distance between labels on a single contour in points.

‘linewidth’

‘linestyle’

‘linecolor’
     The properties of the contour lines.  The properties ‘linewidth’
     and ‘linestyle’ are similar to the corresponding properties for
     lines.  The property ‘linecolor’ is a color property (*note
     Colors::), that can also have the values of "none" or "auto".  If
     ‘linecolor’ is "none", then no contour line is drawn.  If
     ‘linecolor’ is "auto" then the line color is determined by the
     colormap.

‘xdata’
‘ydata’
‘zdata’
     The original x, y, and z data of the contour lines.

‘xdatasource’
‘ydatasource’
‘zdatasource’
     Data source variables.


File: octave.info,  Node: Error Bar Series,  Next: Line Series,  Prev: Contour Groups,  Up: Object Groups

15.4.6.5 Error Bar Series
.........................

Error bar series are created by the ‘errorbar’ function.  Each ‘hggroup’
element contains two line objects representing the data and the
errorbars separately.  The properties of the error bar series are

‘color’
     The RGB color or color name of the line objects of the error bars.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects of the error bars.
     *Note Line Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers on the error bars.  *Note
     Colors::.

‘xdata’
‘ydata’
‘ldata’
‘udata’
‘xldata’
‘xudata’
     The original x, y, l, u, xl, xu data of the error bars.

‘xdatasource’
‘ydatasource’
‘ldatasource’
‘udatasource’
‘xldatasource’
‘xudatasource’
     Data source variables.


File: octave.info,  Node: Line Series,  Next: Quiver Group,  Prev: Error Bar Series,  Up: Object Groups

15.4.6.6 Line Series
....................

Line series objects are created by the ‘plot’ and ‘plot3’ functions and
are of the type ‘line’.  The properties of the line series with the
ability to add data sources.

‘color’
     The RGB color or color name of the line objects.  *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects.  *Note Line Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers.  *Note Colors::.

‘xdata’
‘ydata’
‘zdata’
     The original x, y and z data.

‘xdatasource’
‘ydatasource’
‘zdatasource’
     Data source variables.


File: octave.info,  Node: Quiver Group,  Next: Scatter Group,  Prev: Line Series,  Up: Object Groups

15.4.6.7 Quiver Group
.....................

Quiver series objects are created by the ‘quiver’ or ‘quiver3’
functions.  Each ‘hggroup’ element of the series contains three line
objects as children representing the body and head of the arrow,
together with a marker as the point of origin of the arrows.  The
properties of the quiver series are

‘autoscale’
‘autoscalefactor’
     Flag whether the length of the arrows is scaled or defined directly
     from the U, V and W data.  If the arrow length is flagged as being
     scaled by the ‘autoscale’ property, then the length of the
     autoscaled arrow is controlled by the ‘autoscalefactor’.

‘maxheadsize’
     This property controls the size of the head of the arrows in the
     quiver series.  The default value is 0.2.

‘showarrowhead’
     Flag whether the arrow heads are displayed in the quiver plot.

‘color’
     The RGB color or color name of the line objects of the quiver.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects of the quiver.  *Note
     Line Styles::.

‘marker’
‘markerfacecolor’
‘markersize’
     The line and fill color of the marker objects at the original of
     the arrows.  *Note Colors::.

‘xdata’
‘ydata’
‘zdata’
     The origins of the values of the vector field.

‘udata’
‘vdata’
‘wdata’
     The values of the vector field to plot.

‘xdatasource’
‘ydatasource’
‘zdatasource’
‘udatasource’
‘vdatasource’
‘wdatasource’
     Data source variables.


File: octave.info,  Node: Scatter Group,  Next: Stair Group,  Prev: Quiver Group,  Up: Object Groups

15.4.6.8 Scatter Group
......................

Scatter series objects are created by the ‘scatter’ or ‘scatter3’
functions.  A single hggroup element contains as many children as there
are points in the scatter plot, with each child representing one of the
points.  The properties of the stem series are

‘linewidth’
     The line width of the line objects of the points.  *Note Line
     Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
     The line and fill color of the markers of the points.  *Note
     Colors::.

‘xdata’
‘ydata’
‘zdata’
     The original x, y and z data of the stems.

‘cdata’
     The color data for the points of the plot.  Each point can have a
     separate color, or a unique color can be specified.

‘sizedata’
     The size data for the points of the plot.  Each point can its own
     size or a unique size can be specified.

‘xdatasource’
‘ydatasource’
‘zdatasource’
‘cdatasource’
‘sizedatasource’
     Data source variables.


File: octave.info,  Node: Stair Group,  Next: Stem Series,  Prev: Scatter Group,  Up: Object Groups

15.4.6.9 Stair Group
....................

Stair series objects are created by the ‘stair’ function.  Each
‘hggroup’ element of the series contains a single line object as a child
representing the stair.  The properties of the stair series are

‘color’
     The RGB color or color name of the line objects of the stairs.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects of the stairs.  *Note
     Line Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers on the stairs.  *Note
     Colors::.

‘xdata’
‘ydata’
     The original x and y data of the stairs.

‘xdatasource’
‘ydatasource’
     Data source variables.


File: octave.info,  Node: Stem Series,  Next: Surface Group,  Prev: Stair Group,  Up: Object Groups

15.4.6.10 Stem Series
.....................

Stem series objects are created by the ‘stem’ or ‘stem3’ functions.
Each ‘hggroup’ element contains a single line object as a child
representing the stems.  The properties of the stem series are

‘showbaseline’
‘baseline’
‘basevalue’
     The property ‘showbaseline’ flags whether the baseline of the stem
     series is displayed (default is "on").  The handle of the graphics
     object representing the baseline is given by the ‘baseline’
     property and the y-value (or z-value for ‘stem3’) of the baseline
     by the ‘basevalue’ property.

     Changes to any of these property are propagated to the other
     members of the stem series and to the baseline itself.  Equally
     changes in the properties of the base line itself are propagated to
     the members of the corresponding stem series.

‘color’
     The RGB color or color name of the line objects of the stems.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects of the stems.  *Note
     Line Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers on the stems.  *Note
     Colors::.

‘xdata’
‘ydata’
‘zdata’
     The original x, y and z data of the stems.

‘xdatasource’
‘ydatasource’
‘zdatasource’
     Data source variables.


File: octave.info,  Node: Surface Group,  Prev: Stem Series,  Up: Object Groups

15.4.6.11 Surface Group
.......................

Surface group objects are created by the ‘surf’ or ‘mesh’ functions, but
are equally one of the handles returned by the ‘surfc’ or ‘meshc’
functions.  The surface group is of the type ‘surface’.

   The properties of the surface group are

‘edgecolor’

‘facecolor’
     The RGB color or color name of the edges or faces of the surface.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the lines on the surface.  *Note Line
     Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers on the surface.  *Note
     Colors::.

‘xdata’
‘ydata’
‘zdata’
‘cdata’
     The original x, y, z and c data.

‘xdatasource’
‘ydatasource’
‘zdatasource’
‘cdatasource’
     Data source variables.


File: octave.info,  Node: Graphics Toolkits,  Prev: Object Groups,  Up: Advanced Plotting

15.4.7 Graphics Toolkits
------------------------

 -- : NAME = graphics_toolkit ()
 -- : NAME = graphics_toolkit (HLIST)
 -- : graphics_toolkit (NAME)
 -- : graphics_toolkit (HLIST, NAME)
     Query or set the default graphics toolkit which is assigned to new
     figures.

     With no inputs, return the current default graphics toolkit.  If
     the input is a list of figure graphic handles, HLIST, then return
     the name of the graphics toolkit in use for each figure.

     When called with a single input NAME set the default graphics
     toolkit to NAME.  If the toolkit is not already loaded, it is
     initialized by calling the function ‘__init_NAME__’.  If the first
     input is a list of figure handles, HLIST, then the graphics toolkit
     is set to NAME for these figures only.

     See also: *note available_graphics_toolkits:
     XREFavailable_graphics_toolkits.

 -- : available_graphics_toolkits ()
     Return a cell array of registered graphics toolkits.

     See also: *note graphics_toolkit: XREFgraphics_toolkit, *note
     register_graphics_toolkit: XREFregister_graphics_toolkit.

 -- : loaded_graphics_toolkits ()
     Return a cell array of the currently loaded graphics toolkits.

     See also: *note available_graphics_toolkits:
     XREFavailable_graphics_toolkits.

 -- : register_graphics_toolkit (TOOLKIT)
     List TOOLKIT as an available graphics toolkit.

     See also: *note available_graphics_toolkits:
     XREFavailable_graphics_toolkits.

* Menu:

* Customizing Toolkit Behavior::


File: octave.info,  Node: Customizing Toolkit Behavior,  Up: Graphics Toolkits

15.4.7.1 Customizing Toolkit Behavior
.....................................

The specific behavior of the backend toolkit may be modified using the
following utility functions.  Note: Not all functions apply to every
graphics toolkit.

 -- : [PROG, ARGS] = gnuplot_binary ()
 -- : [OLD_PROG, OLD_ARGS] = gnuplot_binary (NEW_PROG, ARG1, ...)
     Query or set the name of the program invoked by the plot command
     when the graphics toolkit is set to "gnuplot".

     Additional arguments to pass to the external plotting program may
     also be given.  The default value is "gnuplot" with no additional
     arguments.  *Note Installation::.

     See also: *note graphics_toolkit: XREFgraphics_toolkit.


File: octave.info,  Node: Matrix Manipulation,  Next: Arithmetic,  Prev: Plotting,  Up: Top

16 Matrix Manipulation
**********************

There are a number of functions available for checking to see if the
elements of a matrix meet some condition, and for rearranging the
elements of a matrix.  For example, Octave can easily tell you if all
the elements of a matrix are finite, or are less than some specified
value.  Octave can also rotate the elements, extract the upper- or
lower-triangular parts, or sort the columns of a matrix.

* Menu:

* Finding Elements and Checking Conditions::
* Rearranging Matrices::
* Special Utility Matrices::
* Famous Matrices::


File: octave.info,  Node: Finding Elements and Checking Conditions,  Next: Rearranging Matrices,  Up: Matrix Manipulation

16.1 Finding Elements and Checking Conditions
=============================================

The functions ‘any’ and ‘all’ are useful for determining whether any or
all of the elements of a matrix satisfy some condition.  The ‘find’
function is also useful in determining which elements of a matrix meet a
specified condition.

 -- : any (X)
 -- : any (X, DIM)
     For a vector argument, return true (logical 1) if any element of
     the vector is nonzero.

     For a matrix argument, return a row vector of logical ones and
     zeros with each element indicating whether any of the elements of
     the corresponding column of the matrix are nonzero.  For example:

          any (eye (2, 4))
           ⇒ [ 1, 1, 0, 0 ]

     If the optional argument DIM is supplied, work along dimension DIM.
     For example:

          any (eye (2, 4), 2)
           ⇒ [ 1; 1 ]

     See also: *note all: XREFall.

 -- : all (X)
 -- : all (X, DIM)
     For a vector argument, return true (logical 1) if all elements of
     the vector are nonzero.

     For a matrix argument, return a row vector of logical ones and
     zeros with each element indicating whether all of the elements of
     the corresponding column of the matrix are nonzero.  For example:

          all ([2, 3; 1, 0])
              ⇒ [ 1, 0 ]

     If the optional argument DIM is supplied, work along dimension DIM.

     See also: *note any: XREFany.

   Since the comparison operators (*note Comparison Ops::) return
matrices of ones and zeros, it is easy to test a matrix for many things,
not just whether the elements are nonzero.  For example,

     all (all (rand (5) < 0.9))
          ⇒ 0

tests a random 5 by 5 matrix to see if all of its elements are less than
0.9.

   Note that in conditional contexts (like the test clause of ‘if’ and
‘while’ statements) Octave treats the test as if you had typed ‘all (all
(condition))’.

 -- : Z = xor (X, Y)
 -- : Z = xor (X1, X2, ...)
     Return the “exclusive or” of X and Y.

     For boolean expressions X and Y, ‘xor (X, Y)’ is true if and only
     if one of X or Y is true.  Otherwise, if X and Y are both true or
     both false, ‘xor’ returns false.

     The truth table for the xor operation is

                                      X  Y    Z
                                      -  -    -
                                      0  0    0
                                      1  0    1
                                      0  1    1
                                      1  1    0

     If more than two arguments are given the xor operation is applied
     cumulatively from left to right:

          (...((x1 XOR x2) XOR x3) XOR ...)

     See also: *note and: XREFand, *note or: XREFor, *note not: XREFnot.

 -- : diff (X)
 -- : diff (X, K)
 -- : diff (X, K, DIM)
     If X is a vector of length n, ‘diff (X)’ is the vector of first
     differences X(2) - X(1), ..., X(n) - X(n-1).

     If X is a matrix, ‘diff (X)’ is the matrix of column differences
     along the first non-singleton dimension.

     The second argument is optional.  If supplied, ‘diff (X, K)’, where
     K is a non-negative integer, returns the K-th differences.  It is
     possible that K is larger than the first non-singleton dimension of
     the matrix.  In this case, ‘diff’ continues to take the differences
     along the next non-singleton dimension.

     The dimension along which to take the difference can be explicitly
     stated with the optional variable DIM.  In this case the K-th order
     differences are calculated along this dimension.  In the case where
     K exceeds ‘size (X, DIM)’ an empty matrix is returned.

     See also: *note sort: XREFsort, *note merge: XREFmerge.

 -- : isinf (X)
     Return a logical array which is true where the elements of X are
     infinite and false where they are not.

     For example:

          isinf ([13, Inf, NA, NaN])
                ⇒ [ 0, 1, 0, 0 ]

     See also: *note isfinite: XREFisfinite, *note isnan: XREFisnan,
     *note isna: XREFisna.

 -- : isnan (X)
     Return a logical array which is true where the elements of X are
     NaN values and false where they are not.

     NA values are also considered NaN values.  For example:

          isnan ([13, Inf, NA, NaN])
                ⇒ [ 0, 0, 1, 1 ]

     See also: *note isna: XREFisna, *note isinf: XREFisinf, *note
     isfinite: XREFisfinite.

 -- : isfinite (X)
     Return a logical array which is true where the elements of X are
     finite values and false where they are not.

     For example:

          isfinite ([13, Inf, NA, NaN])
               ⇒ [ 1, 0, 0, 0 ]

     See also: *note isinf: XREFisinf, *note isnan: XREFisnan, *note
     isna: XREFisna.

 -- : [ERR, YI, ...] = common_size (XI, ...)
     Determine if all input arguments are either scalar or of common
     size.

     If true, ERR is zero, and YI is a matrix of the common size with
     all entries equal to XI if this is a scalar or XI otherwise.  If
     the inputs cannot be brought to a common size, ERR is 1, and YI is
     XI.  For example:

          [err, a, b] = common_size ([1 2; 3 4], 5)
               ⇒ err = 0
               ⇒ a = [ 1, 2; 3, 4 ]
               ⇒ b = [ 5, 5; 5, 5 ]

     This is useful for implementing functions where arguments can
     either be scalars or of common size.

     See also: *note size: XREFsize, *note size_equal: XREFsize_equal,
     *note numel: XREFnumel, *note ndims: XREFndims.

 -- : IDX = find (X)
 -- : IDX = find (X, N)
 -- : IDX = find (X, N, DIRECTION)
 -- : [i, j] = find (...)
 -- : [i, j, v] = find (...)
     Return a vector of indices of nonzero elements of a matrix, as a
     row if X is a row vector or as a column otherwise.

     To obtain a single index for each matrix element, Octave pretends
     that the columns of a matrix form one long vector (like Fortran
     arrays are stored).  For example:

          find (eye (2))
            ⇒ [ 1; 4 ]

     If two inputs are given, N indicates the maximum number of elements
     to find from the beginning of the matrix or vector.

     If three inputs are given, DIRECTION should be one of "first" or
     "last", requesting only the first or last N indices, respectively.
     However, the indices are always returned in ascending order.

     If two outputs are requested, ‘find’ returns the row and column
     indices of nonzero elements of a matrix.  For example:

          [i, j] = find (2 * eye (2))
              ⇒ i = [ 1; 2 ]
              ⇒ j = [ 1; 2 ]

     If three outputs are requested, ‘find’ also returns a vector
     containing the nonzero values.  For example:

          [i, j, v] = find (3 * eye (2))
                 ⇒ i = [ 1; 2 ]
                 ⇒ j = [ 1; 2 ]
                 ⇒ v = [ 3; 3 ]

     Note that this function is particularly useful for sparse matrices,
     as it extracts the nonzero elements as vectors, which can then be
     used to create the original matrix.  For example:

          sz = size (a);
          [i, j, v] = find (a);
          b = sparse (i, j, v, sz(1), sz(2));

     See also: *note nonzeros: XREFnonzeros.

 -- : IDX = lookup (TABLE, Y)
 -- : IDX = lookup (TABLE, Y, OPT)
     Lookup values in a sorted table.

     This function is usually used as a prelude to interpolation.

     If table is increasing and ‘idx = lookup (table, y)’, then
     ‘table(idx(i)) <= y(i) < table(idx(i+1))’ for all ‘y(i)’ within the
     table.  If ‘y(i) < table(1)’ then ‘idx(i)’ is 0.  If ‘y(i) >=
     table(end)’ or ‘isnan (y(i))’ then ‘idx(i)’ is ‘n’.

     If the table is decreasing, then the tests are reversed.  For
     non-strictly monotonic tables, empty intervals are always skipped.
     The result is undefined if TABLE is not monotonic, or if TABLE
     contains a NaN.

     The complexity of the lookup is O(M*log(N)) where N is the size of
     TABLE and M is the size of Y.  In the special case when Y is also
     sorted, the complexity is O(min(M*log(N),M+N)).

     TABLE and Y can also be cell arrays of strings (or Y can be a
     single string).  In this case, string lookup is performed using
     lexicographical comparison.

     If OPTS is specified, it must be a string with letters indicating
     additional options.

     ‘m’
          ‘table(idx(i)) == val(i)’ if ‘val(i)’ occurs in table;
          otherwise, ‘idx(i)’ is zero.

     ‘b’
          ‘idx(i)’ is a logical 1 or 0, indicating whether ‘val(i)’ is
          contained in table or not.

     ‘l’
          For numeric lookups the leftmost subinterval shall be extended
          to infinity (i.e., all indices at least 1)

     ‘r’
          For numeric lookups the rightmost subinterval shall be
          extended to infinity (i.e., all indices at most n-1).

   If you wish to check if a variable exists at all, instead of
properties its elements may have, consult *note Status of Variables::.


File: octave.info,  Node: Rearranging Matrices,  Next: Special Utility Matrices,  Prev: Finding Elements and Checking Conditions,  Up: Matrix Manipulation

16.2 Rearranging Matrices
=========================

 -- : fliplr (X)
     Flip array left to right.

     Return a copy of X with the order of the columns reversed.  In
     other words, X is flipped left-to-right about a vertical axis.  For
     example:

          fliplr ([1, 2; 3, 4])
               ⇒  2  1
                   4  3

     See also: *note flipud: XREFflipud, *note flip: XREFflip, *note
     rot90: XREFrot90, *note rotdim: XREFrotdim.

 -- : flipud (X)
     Flip array upside down.

     Return a copy of X with the order of the rows reversed.  In other
     words, X is flipped upside-down about a horizontal axis.  For
     example:

          flipud ([1, 2; 3, 4])
               ⇒  3  4
                   1  2

     See also: *note fliplr: XREFfliplr, *note flip: XREFflip, *note
     rot90: XREFrot90, *note rotdim: XREFrotdim.

 -- : flip (X)
 -- : flip (X, DIM)
     Flip array across dimension DIM.

     Return a copy of X flipped about the dimension DIM.  DIM defaults
     to the first non-singleton dimension.  For example:

          flip ([1  2  3  4])
                ⇒  4  3  2  1

          flip ([1; 2; 3; 4])
                ⇒  4
                    3
                    2
                    1

          flip ([1 2; 3 4])
                ⇒  3  4
                    1  2

          flip ([1 2; 3 4], 2)
                ⇒  2  1
                    4  3

     See also: *note fliplr: XREFfliplr, *note flipud: XREFflipud, *note
     rot90: XREFrot90, *note rotdim: XREFrotdim, *note permute:
     XREFpermute, *note transpose: XREFtranspose.

 -- : rot90 (A)
 -- : rot90 (A, K)
     Rotate array by 90 degree increments.

     Return a copy of A with the elements rotated counterclockwise in
     90-degree increments.

     The second argument is optional, and specifies how many 90-degree
     rotations are to be applied (the default value is 1).  Negative
     values of K rotate the matrix in a clockwise direction.  For
     example,

          rot90 ([1, 2; 3, 4], -1)
              ⇒  3  1
                  4  2

     rotates the given matrix clockwise by 90 degrees.  The following
     are all equivalent statements:

          rot90 ([1, 2; 3, 4], -1)
          rot90 ([1, 2; 3, 4], 3)
          rot90 ([1, 2; 3, 4], 7)

     The rotation is always performed on the plane of the first two
     dimensions, i.e., rows and columns.  To perform a rotation on any
     other plane, use ‘rotdim’.

     See also: *note rotdim: XREFrotdim, *note fliplr: XREFfliplr, *note
     flipud: XREFflipud, *note flip: XREFflip.

 -- : rotdim (X)
 -- : rotdim (X, N)
 -- : rotdim (X, N, PLANE)
     Return a copy of X with the elements rotated counterclockwise in
     90-degree increments.

     The second argument N is optional, and specifies how many 90-degree
     rotations are to be applied (the default value is 1).  Negative
     values of N rotate the matrix in a clockwise direction.

     The third argument is also optional and defines the plane of the
     rotation.  If present, PLANE is a two element vector containing two
     different valid dimensions of the matrix.  When PLANE is not given
     the first two non-singleton dimensions are used.

     For example,

          rotdim ([1, 2; 3, 4], -1, [1, 2])
               ⇒  3  1
                   4  2

     rotates the given matrix clockwise by 90 degrees.  The following
     are all equivalent statements:

          rotdim ([1, 2; 3, 4], -1, [1, 2])
          rotdim ([1, 2; 3, 4], 3, [1, 2])
          rotdim ([1, 2; 3, 4], 7, [1, 2])

     See also: *note rot90: XREFrot90, *note fliplr: XREFfliplr, *note
     flipud: XREFflipud, *note flip: XREFflip.

 -- : cat (DIM, ARRAY1, ARRAY2, ..., ARRAYN)
     Return the concatenation of N-D array objects, ARRAY1, ARRAY2, ...,
     ARRAYN along dimension DIM.

          A = ones (2, 2);
          B = zeros (2, 2);
          cat (2, A, B)
            ⇒ 1 1 0 0
               1 1 0 0

     Alternatively, we can concatenate A and B along the second
     dimension in the following way:

          [A, B]

     DIM can be larger than the dimensions of the N-D array objects and
     the result will thus have DIM dimensions as the following example
     shows:

          cat (4, ones (2, 2), zeros (2, 2))
            ⇒ ans(:,:,1,1) =

                 1 1
                 1 1

               ans(:,:,1,2) =

                 0 0
                 0 0

     See also: *note horzcat: XREFhorzcat, *note vertcat: XREFvertcat.

 -- : horzcat (ARRAY1, ARRAY2, ..., ARRAYN)
     Return the horizontal concatenation of N-D array objects, ARRAY1,
     ARRAY2, ..., ARRAYN along dimension 2.

     Arrays may also be concatenated horizontally using the syntax for
     creating new matrices.  For example:

          HCAT = [ ARRAY1, ARRAY2, ... ]

     See also: *note cat: XREFcat, *note vertcat: XREFvertcat.

 -- : vertcat (ARRAY1, ARRAY2, ..., ARRAYN)
     Return the vertical concatenation of N-D array objects, ARRAY1,
     ARRAY2, ..., ARRAYN along dimension 1.

     Arrays may also be concatenated vertically using the syntax for
     creating new matrices.  For example:

          VCAT = [ ARRAY1; ARRAY2; ... ]

     See also: *note cat: XREFcat, *note horzcat: XREFhorzcat.

 -- : permute (A, PERM)
     Return the generalized transpose for an N-D array object A.

     The permutation vector PERM must contain the elements ‘1:ndims (A)’
     (in any order, but each element must appear only once).  The Nth
     dimension of A gets remapped to dimension ‘PERM(N)’.  For example:

          X = zeros ([2, 3, 5, 7]);
          size (X)
             ⇒  2   3   5   7

          size (permute (X, [2, 1, 3, 4]))
             ⇒  3   2   5   7

          size (permute (X, [1, 3, 4, 2]))
             ⇒  2   5   7   3

          ## The identity permutation
          size (permute (X, [1, 2, 3, 4]))
             ⇒  2   3   5   7

     See also: *note ipermute: XREFipermute.

 -- : ipermute (A, IPERM)
     The inverse of the ‘permute’ function.

     The expression

          ipermute (permute (A, perm), perm)

     returns the original array A.

     See also: *note permute: XREFpermute.

 -- : reshape (A, M, N, ...)
 -- : reshape (A, [M N ...])
 -- : reshape (A, ..., [], ...)
 -- : reshape (A, SIZE)
     Return a matrix with the specified dimensions (M, N, ...) whose
     elements are taken from the matrix A.

     The elements of the matrix are accessed in column-major order (like
     Fortran arrays are stored).

     The following code demonstrates reshaping a 1x4 row vector into a
     2x2 square matrix.

          reshape ([1, 2, 3, 4], 2, 2)
                ⇒  1  3
                    2  4

     Note that the total number of elements in the original matrix
     (‘prod (size (A))’) must match the total number of elements in the
     new matrix (‘prod ([M N ...])’).

     A single dimension of the return matrix may be left unspecified and
     Octave will determine its size automatically.  An empty matrix ([])
     is used to flag the unspecified dimension.

     See also: *note resize: XREFresize, *note vec: XREFvec, *note
     postpad: XREFpostpad, *note cat: XREFcat, *note squeeze:
     XREFsqueeze.

 -- : resize (X, M)
 -- : resize (X, M, N, ...)
 -- : resize (X, [M N ...])
     Resize X cutting off elements as necessary.

     In the result, element with certain indices is equal to the
     corresponding element of X if the indices are within the bounds of
     X; otherwise, the element is set to zero.

     In other words, the statement

          y = resize (x, dv)

     is equivalent to the following code:

          y = zeros (dv, class (x));
          sz = min (dv, size (x));
          for i = 1:length (sz)
            idx{i} = 1:sz(i);
          endfor
          y(idx{:}) = x(idx{:});

     but is performed more efficiently.

     If only M is supplied, and it is a scalar, the dimension of the
     result is M-by-M.  If M, N, ... are all scalars, then the
     dimensions of the result are M-by-N-by-....  If given a vector as
     input, then the dimensions of the result are given by the elements
     of that vector.

     An object can be resized to more dimensions than it has; in such
     case the missing dimensions are assumed to be 1.  Resizing an
     object to fewer dimensions is not possible.

     See also: *note reshape: XREFreshape, *note postpad: XREFpostpad,
     *note prepad: XREFprepad, *note cat: XREFcat.

 -- : Y = circshift (X, N)
 -- : Y = circshift (X, N, DIM)
     Circularly shift the values of the array X.

     N must be a vector of integers no longer than the number of
     dimensions in X.  The values of N can be either positive or
     negative, which determines the direction in which the values of X
     are shifted.  If an element of N is zero, then the corresponding
     dimension of X will not be shifted.

     If a scalar DIM is given then operate along the specified
     dimension.  In this case N must be a scalar as well.

     Examples:

          x = [1, 2, 3; 4, 5, 6; 7, 8, 9];
          circshift (x, 1)
          ⇒  7, 8, 9
              1, 2, 3
              4, 5, 6
          circshift (x, -2)
          ⇒  7, 8, 9
              1, 2, 3
              4, 5, 6
          circshift (x, [0,1])
          ⇒  3, 1, 2
              6, 4, 5
              9, 7, 8

     See also: *note permute: XREFpermute, *note ipermute: XREFipermute,
     *note shiftdim: XREFshiftdim.

 -- : shift (X, B)
 -- : shift (X, B, DIM)
     If X is a vector, perform a circular shift of length B of the
     elements of X.

     If X is a matrix, do the same for each column of X.

     If the optional DIM argument is given, operate along this
     dimension.

 -- : Y = shiftdim (X, N)
 -- : [Y, NS] = shiftdim (X)
     Shift the dimensions of X by N, where N must be an integer scalar.

     When N is positive, the dimensions of X are shifted to the left,
     with the leading dimensions circulated to the end.  If N is
     negative, then the dimensions of X are shifted to the right, with N
     leading singleton dimensions added.

     Called with a single argument, ‘shiftdim’, removes the leading
     singleton dimensions, returning the number of dimensions removed in
     the second output argument NS.

     For example:

          x = ones (1, 2, 3);
          size (shiftdim (x, -1))
             ⇒ [1, 1, 2, 3]
          size (shiftdim (x, 1))
             ⇒ [2, 3]
          [b, ns] = shiftdim (x)
             ⇒ b = [1, 1, 1; 1, 1, 1]
             ⇒ ns = 1

     See also: *note reshape: XREFreshape, *note permute: XREFpermute,
     *note ipermute: XREFipermute, *note circshift: XREFcircshift, *note
     squeeze: XREFsqueeze.

 -- : [S, I] = sort (X)
 -- : [S, I] = sort (X, DIM)
 -- : [S, I] = sort (X, MODE)
 -- : [S, I] = sort (X, DIM, MODE)
     Return a copy of X with the elements arranged in increasing order.

     For matrices, ‘sort’ orders the elements within columns

     For example:

          sort ([1, 2; 2, 3; 3, 1])
             ⇒  1  1
                 2  2
                 3  3

     If the optional argument DIM is given, then the matrix is sorted
     along the dimension defined by DIM.  The optional argument ‘mode’
     defines the order in which the values will be sorted.  Valid values
     of ‘mode’ are "ascend" or "descend".

     The ‘sort’ function may also be used to produce a matrix containing
     the original row indices of the elements in the sorted matrix.  For
     example:

          [s, i] = sort ([1, 2; 2, 3; 3, 1])
            ⇒ s = 1  1
                   2  2
                   3  3
            ⇒ i = 1  3
                   2  1
                   3  2

     For equal elements, the indices are such that equal elements are
     listed in the order in which they appeared in the original list.

     Sorting of complex entries is done first by magnitude (‘abs (Z)’)
     and for any ties by phase angle (‘angle (z)’).  For example:

          sort ([1+i; 1; 1-i])
              ⇒ 1 + 0i
                 1 - 1i
                 1 + 1i

     NaN values are treated as being greater than any other value and
     are sorted to the end of the list.

     The ‘sort’ function may also be used to sort strings and cell
     arrays of strings, in which case ASCII dictionary order (uppercase
     ’A’ precedes lowercase ’a’) of the strings is used.

     The algorithm used in ‘sort’ is optimized for the sorting of
     partially ordered lists.

     See also: *note sortrows: XREFsortrows, *note issorted:
     XREFissorted.

 -- : [S, I] = sortrows (A)
 -- : [S, I] = sortrows (A, C)
     Sort the rows of the matrix A according to the order of the columns
     specified in C.

     By default (C omitted, or a particular column unspecified in C) an
     ascending sort order is used.  However, if elements of C are
     negative then the corresponding column is sorted in descending
     order.  If the elements of A are strings then a lexicographical
     sort is used.

     Example: sort by column 2 in descending order, then 3 in ascending
     order

          x = [ 7, 1, 4;
                8, 3, 5;
                9, 3, 6 ];
          sortrows (x, [-2, 3])
             ⇒ 8  3  5
                9  3  6
                7  1  4

     See also: *note sort: XREFsort.

 -- : issorted (A)
 -- : issorted (A, MODE)
 -- : issorted (A, "rows", MODE)
     Return true if the array is sorted according to MODE, which may be
     either "ascending", "descending", or "either".

     By default, MODE is "ascending".  NaNs are treated in the same
     manner as ‘sort’.

     If the optional argument "rows" is supplied, check whether the
     array is sorted by rows as output by the function ‘sortrows’ (with
     no options).

     This function does not support sparse matrices.

     See also: *note sort: XREFsort, *note sortrows: XREFsortrows.

 -- : nth_element (X, N)
 -- : nth_element (X, N, DIM)
     Select the n-th smallest element of a vector, using the ordering
     defined by ‘sort’.

     The result is equivalent to ‘sort(X)(N)’.

     N can also be a contiguous range, either ascending ‘l:u’ or
     descending ‘u:-1:l’, in which case a range of elements is returned.

     If X is an array, ‘nth_element’ operates along the dimension
     defined by DIM, or the first non-singleton dimension if DIM is not
     given.

     Programming Note: nth_element encapsulates the C++ standard library
     algorithms nth_element and partial_sort.  On average, the
     complexity of the operation is O(M*log(K)), where
     ‘M = size (X, DIM)’ and ‘K = length (N)’.  This function is
     intended for cases where the ratio K/M is small; otherwise, it may
     be better to use ‘sort’.

     See also: *note sort: XREFsort, *note min: XREFmin, *note max:
     XREFmax.

 -- : tril (A)
 -- : tril (A, K)
 -- : tril (A, K, PACK)
 -- : triu (A)
 -- : triu (A, K)
 -- : triu (A, K, PACK)
     Return a new matrix formed by extracting the lower (‘tril’) or
     upper (‘triu’) triangular part of the matrix A, and setting all
     other elements to zero.

     The second argument is optional, and specifies how many diagonals
     above or below the main diagonal should also be set to zero.

     The default value of K is zero, so that ‘triu’ and ‘tril’ normally
     include the main diagonal as part of the result.

     If the value of K is nonzero integer, the selection of elements
     starts at an offset of K diagonals above or below the main
     diagonal; above for positive K and below for negative K.

     The absolute value of K must not be greater than the number of
     subdiagonals or superdiagonals.

     For example:

          tril (ones (3), -1)
               ⇒  0  0  0
                   1  0  0
                   1  1  0

     and

          tril (ones (3), 1)
               ⇒  1  1  0
                   1  1  1
                   1  1  1

     If the option "pack" is given as third argument, the extracted
     elements are not inserted into a matrix, but rather stacked
     column-wise one above other.

     See also: *note diag: XREFdiag.

 -- : V = vec (X)
 -- : V = vec (X, DIM)
     Return the vector obtained by stacking the columns of the matrix X
     one above the other.

     Without DIM this is equivalent to ‘X(:)’.

     If DIM is supplied, the dimensions of V are set to DIM with all
     elements along the last dimension.  This is equivalent to ‘shiftdim
     (X(:), 1-DIM)’.

     See also: *note vech: XREFvech, *note resize: XREFresize, *note
     cat: XREFcat.

 -- : vech (X)
     Return the vector obtained by eliminating all superdiagonal
     elements of the square matrix X and stacking the result one column
     above the other.

     This has uses in matrix calculus where the underlying matrix is
     symmetric and it would be pointless to keep values above the main
     diagonal.

     See also: *note vec: XREFvec.

 -- : prepad (X, L)
 -- : prepad (X, L, C)
 -- : prepad (X, L, C, DIM)
     Prepend the scalar value C to the vector X until it is of length L.
     If C is not given, a value of 0 is used.

     If ‘length (X) > L’, elements from the beginning of X are removed
     until a vector of length L is obtained.

     If X is a matrix, elements are prepended or removed from each row.

     If the optional argument DIM is given, operate along this
     dimension.

     If DIM is larger than the dimensions of X, the result will have DIM
     dimensions.

     See also: *note postpad: XREFpostpad, *note cat: XREFcat, *note
     resize: XREFresize.

 -- : postpad (X, L)
 -- : postpad (X, L, C)
 -- : postpad (X, L, C, DIM)
     Append the scalar value C to the vector X until it is of length L.
     If C is not given, a value of 0 is used.

     If ‘length (X) > L’, elements from the end of X are removed until a
     vector of length L is obtained.

     If X is a matrix, elements are appended or removed from each row.

     If the optional argument DIM is given, operate along this
     dimension.

     If DIM is larger than the dimensions of X, the result will have DIM
     dimensions.

     See also: *note prepad: XREFprepad, *note cat: XREFcat, *note
     resize: XREFresize.

 -- : M = diag (V)
 -- : M = diag (V, K)
 -- : M = diag (V, M, N)
 -- : V = diag (M)
 -- : V = diag (M, K)
     Return a diagonal matrix with vector V on diagonal K.

     The second argument is optional.  If it is positive, the vector is
     placed on the K-th superdiagonal.  If it is negative, it is placed
     on the -K-th subdiagonal.  The default value of K is 0, and the
     vector is placed on the main diagonal.  For example:

          diag ([1, 2, 3], 1)
             ⇒  0  1  0  0
                 0  0  2  0
                 0  0  0  3
                 0  0  0  0

     The 3-input form returns a diagonal matrix with vector V on the
     main diagonal and the resulting matrix being of size M rows x N
     columns.

     Given a matrix argument, instead of a vector, ‘diag’ extracts the
     K-th diagonal of the matrix.

 -- : blkdiag (A, B, C, ...)
     Build a block diagonal matrix from A, B, C, ...

     All arguments must be numeric and either two-dimensional matrices
     or scalars.  If any argument is of type sparse, the output will
     also be sparse.

     See also: *note diag: XREFdiag, *note horzcat: XREFhorzcat, *note
     vertcat: XREFvertcat, *note sparse: XREFsparse.


File: octave.info,  Node: Special Utility Matrices,  Next: Famous Matrices,  Prev: Rearranging Matrices,  Up: Matrix Manipulation

16.3 Special Utility Matrices
=============================

 -- : eye (N)
 -- : eye (M, N)
 -- : eye ([M N])
 -- : eye (..., CLASS)
     Return an identity matrix.

     If invoked with a single scalar argument N, return a square NxN
     identity matrix.

     If supplied two scalar arguments (M, N), ‘eye’ takes them to be the
     number of rows and columns.  If given a vector with two elements,
     ‘eye’ uses the values of the elements as the number of rows and
     columns, respectively.  For example:

          eye (3)
           ⇒  1  0  0
               0  1  0
               0  0  1

     The following expressions all produce the same result:

          eye (2)
          ≡
          eye (2, 2)
          ≡
          eye (size ([1, 2; 3, 4]))

     The optional argument CLASS, allows ‘eye’ to return an array of the
     specified type, like

          val = zeros (n,m, "uint8")

     Calling ‘eye’ with no arguments is equivalent to calling it with an
     argument of 1.  Any negative dimensions are treated as zero.  These
     odd definitions are for compatibility with MATLAB.

     See also: *note speye: XREFspeye, *note ones: XREFones, *note
     zeros: XREFzeros.

 -- : ones (N)
 -- : ones (M, N)
 -- : ones (M, N, K, ...)
 -- : ones ([M N ...])
 -- : ones (..., CLASS)
     Return a matrix or N-dimensional array whose elements are all 1.

     If invoked with a single scalar integer argument N, return a square
     NxN matrix.

     If invoked with two or more scalar integer arguments, or a vector
     of integer values, return an array with the given dimensions.

     To create a constant matrix whose values are all the same use an
     expression such as

          val_matrix = val * ones (m, n)

     The optional argument CLASS specifies the class of the return array
     and defaults to double.  For example:

          val = ones (m,n, "uint8")

     See also: *note zeros: XREFzeros.

 -- : zeros (N)
 -- : zeros (M, N)
 -- : zeros (M, N, K, ...)
 -- : zeros ([M N ...])
 -- : zeros (..., CLASS)
     Return a matrix or N-dimensional array whose elements are all 0.

     If invoked with a single scalar integer argument, return a square
     NxN matrix.

     If invoked with two or more scalar integer arguments, or a vector
     of integer values, return an array with the given dimensions.

     The optional argument CLASS specifies the class of the return array
     and defaults to double.  For example:

          val = zeros (m,n, "uint8")

     See also: *note ones: XREFones.

 -- : repmat (A, M)
 -- : repmat (A, M, N)
 -- : repmat (A, M, N, P ...)
 -- : repmat (A, [M N])
 -- : repmat (A, [M N P ...])
     Repeat matrix or N-D array.

     Form a block matrix of size M by N, with a copy of matrix A as each
     element.

     If N is not specified, form an M by M block matrix.  For copying
     along more than two dimensions, specify the number of times to copy
     across each dimension M, N, P, ..., in a vector in the second
     argument.

     See also: *note bsxfun: XREFbsxfun, *note kron: XREFkron, *note
     repelems: XREFrepelems.

 -- : repelems (X, R)
     Construct a vector of repeated elements from X.

     R is a 2xN integer matrix specifying which elements to repeat and
     how often to repeat each element.  Entries in the first row,
     R(1,j), select an element to repeat.  The corresponding entry in
     the second row, R(2,j), specifies the repeat count.  If X is a
     matrix then the columns of X are imagined to be stacked on top of
     each other for purposes of the selection index.  A row vector is
     always returned.

     Conceptually the result is calculated as follows:

          y = [];
          for i = 1:columns (R)
            y = [y, X(R(1,i)*ones(1, R(2,i)))];
          endfor

     See also: *note repmat: XREFrepmat, *note cat: XREFcat.

   The functions ‘linspace’ and ‘logspace’ make it very easy to create
vectors with evenly or logarithmically spaced elements.  *Note Ranges::.

 -- : linspace (BASE, LIMIT)
 -- : linspace (BASE, LIMIT, N)
     Return a row vector with N linearly spaced elements between BASE
     and LIMIT.

     If the number of elements is greater than one, then the endpoints
     BASE and LIMIT are always included in the range.  If BASE is
     greater than LIMIT, the elements are stored in decreasing order.
     If the number of points is not specified, a value of 100 is used.

     The ‘linspace’ function returns a row vector when both BASE and
     LIMIT are scalars.  If one, or both, inputs are vectors, then
     ‘linspace’ transforms them to column vectors and returns a matrix
     where each row is an independent sequence between
     ‘BASE(ROW_N), LIMIT(ROW_N)’.

     For compatibility with MATLAB, return the second argument (LIMIT)
     if fewer than two values are requested.

     See also: *note logspace: XREFlogspace.

 -- : logspace (A, B)
 -- : logspace (A, B, N)
 -- : logspace (A, pi, N)
     Return a row vector with N elements logarithmically spaced from
     10^A to 10^B.

     If N is unspecified it defaults to 50.

     If B is equal to pi, the points are between 10^A and pi, _not_ 10^A
     and 10^pi, in order to be compatible with the corresponding MATLAB
     function.

     Also for compatibility with MATLAB, return the second argument B if
     fewer than two values are requested.

     See also: *note linspace: XREFlinspace.

 -- : rand (N)
 -- : rand (M, N, ...)
 -- : rand ([M N ...])
 -- : V = rand ("state")
 -- : rand ("state", V)
 -- : rand ("state", "reset")
 -- : V = rand ("seed")
 -- : rand ("seed", V)
 -- : rand ("seed", "reset")
 -- : rand (..., "single")
 -- : rand (..., "double")
     Return a matrix with random elements uniformly distributed on the
     interval (0, 1).

     The arguments are handled the same as the arguments for ‘eye’.

     You can query the state of the random number generator using the
     form

          v = rand ("state")

     This returns a column vector V of length 625.  Later, you can
     restore the random number generator to the state V using the form

          rand ("state", v)

     You may also initialize the state vector from an arbitrary vector
     of length ≤ 625 for V.  This new state will be a hash based on the
     value of V, not V itself.

     By default, the generator is initialized from ‘/dev/urandom’ if it
     is available, otherwise from CPU time, wall clock time, and the
     current fraction of a second.  Note that this differs from MATLAB,
     which always initializes the state to the same state at startup.
     To obtain behavior comparable to MATLAB, initialize with a
     deterministic state vector in Octave’s startup files (*note Startup
     Files::).

     To compute the pseudo-random sequence, ‘rand’ uses the Mersenne
     Twister with a period of 2^{19937}-1 (See M. Matsumoto and T.
     Nishimura, ‘Mersenne Twister: A 623-dimensionally equidistributed
     uniform pseudorandom number generator’, ACM Trans.  on Modeling and
     Computer Simulation Vol.  8, No.  1, pp.  3–30, January 1998,
     <http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html>).  Do
     *not* use for cryptography without securely hashing several
     returned values together, otherwise the generator state can be
     learned after reading 624 consecutive values.

     Older versions of Octave used a different random number generator.
     The new generator is used by default as it is significantly faster
     than the old generator, and produces random numbers with a
     significantly longer cycle time.  However, in some circumstances it
     might be desirable to obtain the same random sequences as produced
     by the old generators.  To do this the keyword "seed" is used to
     specify that the old generators should be used, as in

          rand ("seed", val)

     which sets the seed of the generator to VAL.  The seed of the
     generator can be queried with

          s = rand ("seed")

     However, it should be noted that querying the seed will not cause
     ‘rand’ to use the old generators, only setting the seed will.  To
     cause ‘rand’ to once again use the new generators, the keyword
     "state" should be used to reset the state of the ‘rand’.

     The state or seed of the generator can be reset to a new random
     value using the "reset" keyword.

     The class of the value returned can be controlled by a trailing
     "double" or "single" argument.  These are the only valid classes.

     See also: *note randn: XREFrandn, *note rande: XREFrande, *note
     randg: XREFrandg, *note randp: XREFrandp.

 -- : randi (IMAX)
 -- : randi (IMAX, N)
 -- : randi (IMAX, M, N, ...)
 -- : randi ([IMIN IMAX], ...)
 -- : randi (..., "CLASS")
     Return random integers in the range 1:IMAX.

     Additional arguments determine the shape of the return matrix.
     When no arguments are specified a single random integer is
     returned.  If one argument N is specified then a square matrix
     (N x N) is returned.  Two or more arguments will return a
     multi-dimensional matrix (M x N x ...).

     The integer range may optionally be described by a two element
     matrix with a lower and upper bound in which case the returned
     integers will be on the interval [IMIN, IMAX].

     The optional argument CLASS will return a matrix of the requested
     type.  The default is "double".

     The following example returns 150 integers in the range 1–10.

          ri = randi (10, 150, 1)

     Implementation Note: ‘randi’ relies internally on ‘rand’ which uses
     class "double" to represent numbers.  This limits the maximum
     integer (IMAX) and range (IMAX - IMIN) to the value returned by the
     ‘flintmax’ function.  For IEEE floating point numbers this value is
     2^{53} - 1.

     See also: *note rand: XREFrand.

 -- : randn (N)
 -- : randn (M, N, ...)
 -- : randn ([M N ...])
 -- : V = randn ("state")
 -- : randn ("state", V)
 -- : randn ("state", "reset")
 -- : V = randn ("seed")
 -- : randn ("seed", V)
 -- : randn ("seed", "reset")
 -- : randn (..., "single")
 -- : randn (..., "double")
     Return a matrix with normally distributed random elements having
     zero mean and variance one.

     The arguments are handled the same as the arguments for ‘rand’.

     By default, ‘randn’ uses the Marsaglia and Tsang “Ziggurat
     technique” to transform from a uniform to a normal distribution.

     The class of the value returned can be controlled by a trailing
     "double" or "single" argument.  These are the only valid classes.

     Reference: G. Marsaglia and W.W. Tsang, ‘Ziggurat Method for
     Generating Random Variables’, J. Statistical Software, vol 5, 2000,
     <http://www.jstatsoft.org/v05/i08/>

     See also: *note rand: XREFrand, *note rande: XREFrande, *note
     randg: XREFrandg, *note randp: XREFrandp.

 -- : rande (N)
 -- : rande (M, N, ...)
 -- : rande ([M N ...])
 -- : V = rande ("state")
 -- : rande ("state", V)
 -- : rande ("state", "reset")
 -- : V = rande ("seed")
 -- : rande ("seed", V)
 -- : rande ("seed", "reset")
 -- : rande (..., "single")
 -- : rande (..., "double")
     Return a matrix with exponentially distributed random elements.

     The arguments are handled the same as the arguments for ‘rand’.

     By default, ‘rande’ uses the Marsaglia and Tsang “Ziggurat
     technique” to transform from a uniform to an exponential
     distribution.

     The class of the value returned can be controlled by a trailing
     "double" or "single" argument.  These are the only valid classes.

     Reference: G. Marsaglia and W.W. Tsang, ‘Ziggurat Method for
     Generating Random Variables’, J. Statistical Software, vol 5, 2000,
     <http://www.jstatsoft.org/v05/i08/>

     See also: *note rand: XREFrand, *note randn: XREFrandn, *note
     randg: XREFrandg, *note randp: XREFrandp.

 -- : randp (L, N)
 -- : randp (L, M, N, ...)
 -- : randp (L, [M N ...])
 -- : V = randp ("state")
 -- : randp ("state", V)
 -- : randp ("state", "reset")
 -- : V = randp ("seed")
 -- : randp ("seed", V)
 -- : randp ("seed", "reset")
 -- : randp (..., "single")
 -- : randp (..., "double")
     Return a matrix with Poisson distributed random elements with mean
     value parameter given by the first argument, L.

     The arguments are handled the same as the arguments for ‘rand’,
     except for the argument L.

     Five different algorithms are used depending on the range of L and
     whether or not L is a scalar or a matrix.

     For scalar L ≤ 12, use direct method.
          W.H. Press, et al., ‘Numerical Recipes in C’, Cambridge
          University Press, 1992.

     For scalar L > 12, use rejection method.[1]
          W.H. Press, et al., ‘Numerical Recipes in C’, Cambridge
          University Press, 1992.

     For matrix L ≤ 10, use inversion method.[2]
          E. Stadlober, et al., WinRand source code, available via FTP.

     For matrix L > 10, use patchwork rejection method.
          E. Stadlober, et al., WinRand source code, available via FTP,
          or H. Zechner, ‘Efficient sampling from continuous and
          discrete unimodal distributions’, Doctoral Dissertation,
          156pp., Technical University Graz, Austria, 1994.

     For L > 1e8, use normal approximation.
          L. Montanet, et al., ‘Review of Particle Properties’, Physical
          Review D 50 p1284, 1994.

     The class of the value returned can be controlled by a trailing
     "double" or "single" argument.  These are the only valid classes.

     See also: *note rand: XREFrand, *note randn: XREFrandn, *note
     rande: XREFrande, *note randg: XREFrandg.

 -- : randg (N)
 -- : randg (M, N, ...)
 -- : randg ([M N ...])
 -- : V = randg ("state")
 -- : randg ("state", V)
 -- : randg ("state", "reset")
 -- : V = randg ("seed")
 -- : randg ("seed", V)
 -- : randg ("seed", "reset")
 -- : randg (..., "single")
 -- : randg (..., "double")
     Return a matrix with ‘gamma (A,1)’ distributed random elements.

     The arguments are handled the same as the arguments for ‘rand’,
     except for the argument A.

     This can be used to generate many distributions:

     ‘gamma (a, b)’ for ‘a > -1’, ‘b > 0’

               r = b * randg (a)

     ‘beta (a, b)’ for ‘a > -1’, ‘b > -1’

               r1 = randg (a, 1)
               r = r1 / (r1 + randg (b, 1))

     ‘Erlang (a, n)’

               r = a * randg (n)

     ‘chisq (df)’ for ‘df > 0’

               r = 2 * randg (df / 2)

     ‘t (df)’ for ‘0 < df < inf’ (use randn if df is infinite)

               r = randn () / sqrt (2 * randg (df / 2) / df)

     ‘F (n1, n2)’ for ‘0 < n1’, ‘0 < n2’

               ## r1 equals 1 if n1 is infinite
               r1 = 2 * randg (n1 / 2) / n1
               ## r2 equals 1 if n2 is infinite
               r2 = 2 * randg (n2 / 2) / n2
               r = r1 / r2

     negative ‘binomial (n, p)’ for ‘n > 0’, ‘0 < p <= 1’

               r = randp ((1 - p) / p * randg (n))

     non-central ‘chisq (df, L)’, for ‘df >= 0’ and ‘L > 0’
          (use chisq if ‘L = 0’)

               r = randp (L / 2)
               r(r > 0) = 2 * randg (r(r > 0))
               r(df > 0) += 2 * randg (df(df > 0)/2)

     ‘Dirichlet (a1, ... ak)’

               r = (randg (a1), ..., randg (ak))
               r = r / sum (r)

     The class of the value returned can be controlled by a trailing
     "double" or "single" argument.  These are the only valid classes.

     See also: *note rand: XREFrand, *note randn: XREFrandn, *note
     rande: XREFrande, *note randp: XREFrandp.

   The generators operate in the new or old style together, it is not
possible to mix the two.  Initializing any generator with "state" or
"seed" causes the others to switch to the same style for future calls.

   The state of each generator is independent and calls to different
generators can be interleaved without affecting the final result.  For
example,

     rand ("state", [11, 22, 33]);
     randn ("state", [44, 55, 66]);
     u = rand (100, 1);
     n = randn (100, 1);

and

     rand ("state", [11, 22, 33]);
     randn ("state", [44, 55, 66]);
     u = zeros (100, 1);
     n = zeros (100, 1);
     for i = 1:100
       u(i) = rand ();
       n(i) = randn ();
     end

produce equivalent results.  When the generators are initialized in the
old style with "seed" only ‘rand’ and ‘randn’ are independent, because
the old ‘rande’, ‘randg’ and ‘randp’ generators make calls to ‘rand’ and
‘randn’.

   The generators are initialized with random states at start-up, so
that the sequences of random numbers are not the same each time you run
Octave.(1)  If you really do need to reproduce a sequence of numbers
exactly, you can set the state or seed to a specific value.

   If invoked without arguments, ‘rand’ and ‘randn’ return a single
element of a random sequence.

   The original ‘rand’ and ‘randn’ functions use Fortran code from
RANLIB, a library of Fortran routines for random number generation,
compiled by Barry W. Brown and James Lovato of the Department of
Biomathematics at The University of Texas, M.D. Anderson Cancer Center,
Houston, TX 77030.

 -- : randperm (N)
 -- : randperm (N, M)
     Return a row vector containing a random permutation of ‘1:N’.

     If M is supplied, return M unique entries, sampled without
     replacement from ‘1:N’.

     The complexity is O(N) in memory and O(M) in time, unless M < N/5,
     in which case O(M) memory is used as well.  The randomization is
     performed using rand().  All permutations are equally likely.

     See also: *note perms: XREFperms.

   ---------- Footnotes ----------

   (1) The old versions of ‘rand’ and ‘randn’ obtain their initial seeds
from the system clock.


File: octave.info,  Node: Famous Matrices,  Prev: Special Utility Matrices,  Up: Matrix Manipulation

16.4 Famous Matrices
====================

The following functions return famous matrix forms.

 -- : gallery (NAME)
 -- : gallery (NAME, ARGS)
     Create interesting matrices for testing.

 -- : C = gallery ("cauchy", X)
 -- : C = gallery ("cauchy", X, Y)
     Create a Cauchy matrix.

 -- : C = gallery ("chebspec", N)
 -- : C = gallery ("chebspec", N, K)
     Create a Chebyshev spectral differentiation matrix.

 -- : C = gallery ("chebvand", P)
 -- : C = gallery ("chebvand", M, P)
     Create a Vandermonde-like matrix for the Chebyshev polynomials.

 -- : A = gallery ("chow", N)
 -- : A = gallery ("chow", N, ALPHA)
 -- : A = gallery ("chow", N, ALPHA, DELTA)
     Create a Chow matrix – a singular Toeplitz lower Hessenberg matrix.

 -- : C = gallery ("circul", V)
     Create a circulant matrix.

 -- : A = gallery ("clement", N)
 -- : A = gallery ("clement", N, K)
     Create a tridiagonal matrix with zero diagonal entries.

 -- : C = gallery ("compar", A)
 -- : C = gallery ("compar", A, K)
     Create a comparison matrix.

 -- : A = gallery ("condex", N)
 -- : A = gallery ("condex", N, K)
 -- : A = gallery ("condex", N, K, THETA)
     Create a ‘counterexample’ matrix to a condition estimator.

 -- : A = gallery ("cycol", [M N])
 -- : A = gallery ("cycol", N)
 -- : A = gallery (..., K)
     Create a matrix whose columns repeat cyclically.

 -- : [C, D, E] = gallery ("dorr", N)
 -- : [C, D, E] = gallery ("dorr", N, THETA)
 -- : A = gallery ("dorr", ...)
     Create a diagonally dominant, ill-conditioned, tridiagonal matrix.

 -- : A = gallery ("dramadah", N)
 -- : A = gallery ("dramadah", N, K)
     Create a (0, 1) matrix whose inverse has large integer entries.

 -- : A = gallery ("fiedler", C)
     Create a symmetric Fiedler matrix.

 -- : A = gallery ("forsythe", N)
 -- : A = gallery ("forsythe", N, ALPHA)
 -- : A = gallery ("forsythe", N, ALPHA, LAMBDA)
     Create a Forsythe matrix (a perturbed Jordan block).

 -- : F = gallery ("frank", N)
 -- : F = gallery ("frank", N, K)
     Create a Frank matrix (ill-conditioned eigenvalues).

 -- : C = gallery ("gcdmat", N)
     Create a greatest common divisor matrix.

     C is an N-by-N matrix whose values correspond to the greatest
     common divisor of its coordinate values, i.e., C(i,j) correspond
     ‘gcd (i, j)’.

 -- : A = gallery ("gearmat", N)
 -- : A = gallery ("gearmat", N, I)
 -- : A = gallery ("gearmat", N, I, J)
     Create a Gear matrix.

 -- : G = gallery ("grcar", N)
 -- : G = gallery ("grcar", N, K)
     Create a Toeplitz matrix with sensitive eigenvalues.

 -- : A = gallery ("hanowa", N)
 -- : A = gallery ("hanowa", N, D)
     Create a matrix whose eigenvalues lie on a vertical line in the
     complex plane.

 -- : V = gallery ("house", X)
 -- : [V, BETA] = gallery ("house", X)
     Create a householder matrix.

 -- : A = gallery ("integerdata", IMAX, [M N ...], J)
 -- : A = gallery ("integerdata", IMAX, M, N, ..., J)
 -- : A = gallery ("integerdata", [IMIN, IMAX], [M N ...], J)
 -- : A = gallery ("integerdata", [IMIN, IMAX], M, N, ..., J)
 -- : A = gallery ("integerdata", ..., "CLASS")
     Create a matrix with random integers in the range [1, IMAX].  If
     IMIN is given then the integers are in the range [IMIN, IMAX].

     The second input is a matrix of dimensions describing the size of
     the output.  The dimensions can also be input as comma-separated
     arguments.

     The input J is an integer index in the range [0, 2^32-1].  The
     values of the output matrix are always exactly the same
     (reproducibility) for a given size input and J index.

     The final optional argument determines the class of the resulting
     matrix.  Possible values for CLASS: "uint8", "uint16", "uint32",
     "int8", "int16", int32", "single", "double".  The default is
     "double".

 -- : A = gallery ("invhess", X)
 -- : A = gallery ("invhess", X, Y)
     Create the inverse of an upper Hessenberg matrix.

 -- : A = gallery ("invol", N)
     Create an involutory matrix.

 -- : A = gallery ("ipjfact", N)
 -- : A = gallery ("ipjfact", N, K)
     Create a Hankel matrix with factorial elements.

 -- : A = gallery ("jordbloc", N)
 -- : A = gallery ("jordbloc", N, LAMBDA)
     Create a Jordan block.

 -- : U = gallery ("kahan", N)
 -- : U = gallery ("kahan", N, THETA)
 -- : U = gallery ("kahan", N, THETA, PERT)
     Create a Kahan matrix (upper trapezoidal).

 -- : A = gallery ("kms", N)
 -- : A = gallery ("kms", N, RHO)
     Create a Kac-Murdock-Szego Toeplitz matrix.

 -- : B = gallery ("krylov", A)
 -- : B = gallery ("krylov", A, X)
 -- : B = gallery ("krylov", A, X, J)
     Create a Krylov matrix.

 -- : A = gallery ("lauchli", N)
 -- : A = gallery ("lauchli", N, MU)
     Create a Lauchli matrix (rectangular).

 -- : A = gallery ("lehmer", N)
     Create a Lehmer matrix (symmetric positive definite).

 -- : T = gallery ("lesp", N)
     Create a tridiagonal matrix with real, sensitive eigenvalues.

 -- : A = gallery ("lotkin", N)
     Create a Lotkin matrix.

 -- : A = gallery ("minij", N)
     Create a symmetric positive definite matrix MIN(i,j).

 -- : A = gallery ("moler", N)
 -- : A = gallery ("moler", N, ALPHA)
     Create a Moler matrix (symmetric positive definite).

 -- : [A, T] = gallery ("neumann", N)
     Create a singular matrix from the discrete Neumann problem
     (sparse).

 -- : A = gallery ("normaldata", [M N ...], J)
 -- : A = gallery ("normaldata", M, N, ..., J)
 -- : A = gallery ("normaldata", ..., "CLASS")
     Create a matrix with random samples from the standard normal
     distribution (mean = 0, std = 1).

     The first input is a matrix of dimensions describing the size of
     the output.  The dimensions can also be input as comma-separated
     arguments.

     The input J is an integer index in the range [0, 2^32-1].  The
     values of the output matrix are always exactly the same
     (reproducibility) for a given size input and J index.

     The final optional argument determines the class of the resulting
     matrix.  Possible values for CLASS: "single", "double".  The
     default is "double".

 -- : Q = gallery ("orthog", N)
 -- : Q = gallery ("orthog", N, K)
     Create orthogonal and nearly orthogonal matrices.

 -- : A = gallery ("parter", N)
     Create a Parter matrix (a Toeplitz matrix with singular values near
     pi).

 -- : P = gallery ("pei", N)
 -- : P = gallery ("pei", N, ALPHA)
     Create a Pei matrix.

 -- : A = gallery ("Poisson", N)
     Create a block tridiagonal matrix from Poisson’s equation (sparse).

 -- : A = gallery ("prolate", N)
 -- : A = gallery ("prolate", N, W)
     Create a prolate matrix (symmetric, ill-conditioned Toeplitz
     matrix).

 -- : H = gallery ("randhess", X)
     Create a random, orthogonal upper Hessenberg matrix.

 -- : A = gallery ("rando", N)
 -- : A = gallery ("rando", N, K)
     Create a random matrix with elements -1, 0 or 1.

 -- : A = gallery ("randsvd", N)
 -- : A = gallery ("randsvd", N, KAPPA)
 -- : A = gallery ("randsvd", N, KAPPA, MODE)
 -- : A = gallery ("randsvd", N, KAPPA, MODE, KL)
 -- : A = gallery ("randsvd", N, KAPPA, MODE, KL, KU)
     Create a random matrix with pre-assigned singular values.

 -- : A = gallery ("redheff", N)
     Create a zero and ones matrix of Redheffer associated with the
     Riemann hypothesis.

 -- : A = gallery ("riemann", N)
     Create a matrix associated with the Riemann hypothesis.

 -- : A = gallery ("ris", N)
     Create a symmetric Hankel matrix.

 -- : A = gallery ("smoke", N)
 -- : A = gallery ("smoke", N, K)
     Create a complex matrix, with a ‘smoke ring’ pseudospectrum.

 -- : T = gallery ("toeppd", N)
 -- : T = gallery ("toeppd", N, M)
 -- : T = gallery ("toeppd", N, M, W)
 -- : T = gallery ("toeppd", N, M, W, THETA)
     Create a symmetric positive definite Toeplitz matrix.

 -- : P = gallery ("toeppen", N)
 -- : P = gallery ("toeppen", N, A)
 -- : P = gallery ("toeppen", N, A, B)
 -- : P = gallery ("toeppen", N, A, B, C)
 -- : P = gallery ("toeppen", N, A, B, C, D)
 -- : P = gallery ("toeppen", N, A, B, C, D, E)
     Create a pentadiagonal Toeplitz matrix (sparse).

 -- : A = gallery ("tridiag", X, Y, Z)
 -- : A = gallery ("tridiag", N)
 -- : A = gallery ("tridiag", N, C, D, E)
     Create a tridiagonal matrix (sparse).

 -- : T = gallery ("triw", N)
 -- : T = gallery ("triw", N, ALPHA)
 -- : T = gallery ("triw", N, ALPHA, K)
     Create an upper triangular matrix discussed by Kahan, Golub, and
     Wilkinson.

 -- : A = gallery ("uniformdata", [M N ...], J)
 -- : A = gallery ("uniformdata", M, N, ..., J)
 -- : A = gallery ("uniformdata", ..., "CLASS")
     Create a matrix with random samples from the standard uniform
     distribution (range [0,1]).

     The first input is a matrix of dimensions describing the size of
     the output.  The dimensions can also be input as comma-separated
     arguments.

     The input J is an integer index in the range [0, 2^32-1].  The
     values of the output matrix are always exactly the same
     (reproducibility) for a given size input and J index.

     The final optional argument determines the class of the resulting
     matrix.  Possible values for CLASS: "single", "double".  The
     default is "double".

 -- : A = gallery ("wathen", NX, NY)
 -- : A = gallery ("wathen", NX, NY, K)
     Create the Wathen matrix.

 -- : [A, B] = gallery ("wilk", N)
     Create various specific matrices devised/discussed by Wilkinson.

 -- : hadamard (N)
     Construct a Hadamard matrix (Hn) of size N-by-N.

     The size N must be of the form 2^k * p in which p is one of 1, 12,
     20 or 28.  The returned matrix is normalized, meaning
     ‘Hn(:,1) == 1’ and ‘Hn(1,:) == 1’.

     Some of the properties of Hadamard matrices are:

        • ‘kron (Hm, Hn)’ is a Hadamard matrix of size M-by-N.

        • ‘Hn * Hn' = N * eye (N)’.

        • The rows of Hn are orthogonal.

        • ‘det (A) <= abs (det (Hn))’ for all A with
          ‘abs (A(i, j)) <= 1’.

        • Multiplying any row or column by -1 and the matrix will remain
          a Hadamard matrix.

     See also: *note compan: XREFcompan, *note hankel: XREFhankel, *note
     toeplitz: XREFtoeplitz.

 -- : hankel (C)
 -- : hankel (C, R)
     Return the Hankel matrix constructed from the first column C, and
     (optionally) the last row R.

     If the last element of C is not the same as the first element of R,
     the last element of C is used.  If the second argument is omitted,
     it is assumed to be a vector of zeros with the same size as C.

     A Hankel matrix formed from an m-vector C, and an n-vector R, has
     the elements

          H(i,j) = c(i+j-1),  i+j-1 <= m;
          H(i,j) = r(i+j-m),  otherwise

     See also: *note hadamard: XREFhadamard, *note toeplitz:
     XREFtoeplitz.

 -- : hilb (N)
     Return the Hilbert matrix of order N.

     The i,j element of a Hilbert matrix is defined as

          H(i, j) = 1 / (i + j - 1)

     Hilbert matrices are close to being singular which make them
     difficult to invert with numerical routines.  Comparing the
     condition number of a random matrix 5x5 matrix with that of a
     Hilbert matrix of order 5 reveals just how difficult the problem
     is.

          cond (rand (5))
             ⇒ 14.392
          cond (hilb (5))
             ⇒ 4.7661e+05

     See also: *note invhilb: XREFinvhilb.

 -- : invhilb (N)
     Return the inverse of the Hilbert matrix of order N.

     This can be computed exactly using


                     (i+j)         /n+i-1\  /n+j-1\   /i+j-2\ 2
          A(i,j) = -1      (i+j-1)(       )(       ) (       )
                                   \ n-j /  \ n-i /   \ i-2 /

                 = p(i) p(j) / (i+j-1)


     where

                   k  /k+n-1\   /n\
          p(k) = -1  (       ) (   )
                      \ k-1 /   \k/

     The validity of this formula can easily be checked by expanding the
     binomial coefficients in both formulas as factorials.  It can be
     derived more directly via the theory of Cauchy matrices.  See J. W.
     Demmel, ‘Applied Numerical Linear Algebra’, p.  92.

     Compare this with the numerical calculation of ‘inverse (hilb
     (n))’, which suffers from the ill-conditioning of the Hilbert
     matrix, and the finite precision of your computer’s floating point
     arithmetic.

     See also: *note hilb: XREFhilb.

 -- : magic (N)

     Create an N-by-N magic square.

     A magic square is an arrangement of the integers ‘1:n^2’ such that
     the row sums, column sums, and diagonal sums are all equal to the
     same value.

     Note: N must be a scalar greater than or equal to 3.  If you supply
     N less than 3, magic returns either a nonmagic square, or else the
     degenerate magic squares 1 and [].

 -- : pascal (N)
 -- : pascal (N, T)
     Return the Pascal matrix of order N if ‘T = 0’.

     The default value of T is 0.

     When ‘T = 1’, return the pseudo-lower triangular Cholesky factor of
     the Pascal matrix (The sign of some columns may be negative).  This
     matrix is its own inverse, that is ‘pascal (N, 1) ^ 2 == eye (N)’.

     If ‘T = -1’, return the true Cholesky factor with strictly positive
     values on the diagonal.

     If ‘T = 2’, return a transposed and permuted version of ‘pascal (N,
     1)’, which is the cube root of the identity matrix.  That is,
     ‘pascal (N, 2) ^ 3 == eye (N)’.

     See also: *note chol: XREFchol.

 -- : rosser ()
     Return the Rosser matrix.

     This is a difficult test case used to evaluate eigenvalue
     algorithms.

     See also: *note wilkinson: XREFwilkinson, *note eig: XREFeig.

 -- : toeplitz (C)
 -- : toeplitz (C, R)
     Return the Toeplitz matrix constructed from the first column C, and
     (optionally) the first row R.

     If the first element of R is not the same as the first element of
     C, the first element of C is used.  If the second argument is
     omitted, the first row is taken to be the same as the first column.

     A square Toeplitz matrix has the form:

          c(0)  r(1)   r(2)  ...  r(n)
          c(1)  c(0)   r(1)  ... r(n-1)
          c(2)  c(1)   c(0)  ... r(n-2)
           .     .      .   .      .
           .     .      .     .    .
           .     .      .       .  .
          c(n) c(n-1) c(n-2) ...  c(0)

     See also: *note hankel: XREFhankel.

 -- : vander (C)
 -- : vander (C, N)
     Return the Vandermonde matrix whose next to last column is C.

     If N is specified, it determines the number of columns; otherwise,
     N is taken to be equal to the length of C.

     A Vandermonde matrix has the form:

          c(1)^(n-1) ... c(1)^2  c(1)  1
          c(2)^(n-1) ... c(2)^2  c(2)  1
              .     .      .      .    .
              .       .    .      .    .
              .         .  .      .    .
          c(n)^(n-1) ... c(n)^2  c(n)  1

     See also: *note polyfit: XREFpolyfit.

 -- : wilkinson (N)
     Return the Wilkinson matrix of order N.

     Wilkinson matrices are symmetric and tridiagonal with pairs of
     nearly, but not exactly, equal eigenvalues.  They are useful in
     testing the behavior and performance of eigenvalue solvers.

     See also: *note rosser: XREFrosser, *note eig: XREFeig.


File: octave.info,  Node: Arithmetic,  Next: Linear Algebra,  Prev: Matrix Manipulation,  Up: Top

17 Arithmetic
*************

Unless otherwise noted, all of the functions described in this chapter
will work for real and complex scalar, vector, or matrix arguments.
Functions described as “mapping functions” apply the given operation
individually to each element when given a matrix argument.  For example:

     sin ([1, 2; 3, 4])
          ⇒  0.84147   0.90930
              0.14112  -0.75680

* Menu:

* Exponents and Logarithms::
* Complex Arithmetic::
* Trigonometry::
* Sums and Products::
* Utility Functions::
* Special Functions::
* Rational Approximations::
* Coordinate Transformations::
* Mathematical Constants::


File: octave.info,  Node: Exponents and Logarithms,  Next: Complex Arithmetic,  Up: Arithmetic

17.1 Exponents and Logarithms
=============================

 -- : exp (X)
     Compute ‘e^x’ for each element of X.

     To compute the matrix exponential, see *note Linear Algebra::.

     See also: *note log: XREFlog.

 -- : expm1 (X)
     Compute ‘exp (X) - 1’ accurately in the neighborhood of zero.

     See also: *note exp: XREFexp.

 -- : log (X)
     Compute the natural logarithm, ‘ln (X)’, for each element of X.

     To compute the matrix logarithm, see *note Linear Algebra::.

     See also: *note exp: XREFexp, *note log1p: XREFlog1p, *note log2:
     XREFlog2, *note log10: XREFlog10, *note logspace: XREFlogspace.

 -- : reallog (X)
     Return the real-valued natural logarithm of each element of X.

     If any element results in a complex return value ‘reallog’ aborts
     and issues an error.

     See also: *note log: XREFlog, *note realpow: XREFrealpow, *note
     realsqrt: XREFrealsqrt.

 -- : log1p (X)
     Compute ‘log (1 + X)’ accurately in the neighborhood of zero.

     See also: *note log: XREFlog, *note exp: XREFexp, *note expm1:
     XREFexpm1.

 -- : log10 (X)
     Compute the base-10 logarithm of each element of X.

     See also: *note log: XREFlog, *note log2: XREFlog2, *note logspace:
     XREFlogspace, *note exp: XREFexp.

 -- : log2 (X)
 -- : [F, E] = log2 (X)
     Compute the base-2 logarithm of each element of X.

     If called with two output arguments, split X into binary mantissa
     and exponent so that ‘1/2 <= abs(f) < 1’ and E is an integer.  If
     ‘x = 0’, ‘f = e = 0’.

     See also: *note pow2: XREFpow2, *note log: XREFlog, *note log10:
     XREFlog10, *note exp: XREFexp.

 -- : pow2 (X)
 -- : pow2 (F, E)
     With one input argument, compute 2 .^ x for each element of X.

     With two input arguments, return f .* (2 .^ e).

     See also: *note log2: XREFlog2, *note nextpow2: XREFnextpow2, *note
     power: XREFpower.

 -- : nextpow2 (X)
     Compute the exponent for the smallest power of two larger than the
     input.

     For each element in the input array X, return the first integer N
     such that 2^n ≥ abs (x).

     See also: *note pow2: XREFpow2, *note log2: XREFlog2.

 -- : realpow (X, Y)
     Compute the real-valued, element-by-element power operator.

     This is equivalent to ‘X .^ Y’, except that ‘realpow’ reports an
     error if any return value is complex.

     See also: *note power: XREFpower, *note reallog: XREFreallog, *note
     realsqrt: XREFrealsqrt.

 -- : sqrt (X)
     Compute the square root of each element of X.

     If X is negative, a complex result is returned.

     To compute the matrix square root, see *note Linear Algebra::.

     See also: *note realsqrt: XREFrealsqrt, *note nthroot: XREFnthroot.

 -- : realsqrt (X)
     Return the real-valued square root of each element of X.

     If any element results in a complex return value ‘realsqrt’ aborts
     and issues an error.

     See also: *note sqrt: XREFsqrt, *note realpow: XREFrealpow, *note
     reallog: XREFreallog.

 -- : cbrt (X)
     Compute the real cube root of each element of X.

     Unlike ‘X^(1/3)’, the result will be negative if X is negative.

     See also: *note nthroot: XREFnthroot.

 -- : nthroot (X, N)

     Compute the real (non-complex) N-th root of X.

     X must have all real entries and N must be a scalar.  If N is an
     even integer and X has negative entries then ‘nthroot’ aborts and
     issues an error.

     Example:

          nthroot (-1, 3)
          ⇒ -1
          (-1) ^ (1 / 3)
          ⇒ 0.50000 - 0.86603i

     See also: *note realsqrt: XREFrealsqrt, *note sqrt: XREFsqrt, *note
     cbrt: XREFcbrt.


File: octave.info,  Node: Complex Arithmetic,  Next: Trigonometry,  Prev: Exponents and Logarithms,  Up: Arithmetic

17.2 Complex Arithmetic
=======================

In the descriptions of the following functions, Z is the complex number
X + IY, where I is defined as ‘sqrt (-1)’.

 -- : abs (Z)
     Compute the magnitude of Z.

     The magnitude is defined as |Z| = ‘sqrt (x^2 + y^2)’.

     For example:

          abs (3 + 4i)
               ⇒ 5

     See also: *note arg: XREFarg.

 -- : arg (Z)
 -- : angle (Z)
     Compute the argument, i.e., angle of Z.

     This is defined as, THETA = ‘atan2 (Y, X)’, in radians.

     For example:

          arg (3 + 4i)
               ⇒ 0.92730

     See also: *note abs: XREFabs.

 -- : conj (Z)
     Return the complex conjugate of Z.

     The complex conjugate is defined as ‘conj (Z)’ = X - IY.

     See also: *note real: XREFreal, *note imag: XREFimag.

 -- : cplxpair (Z)
 -- : cplxpair (Z, TOL)
 -- : cplxpair (Z, TOL, DIM)
     Sort the numbers Z into complex conjugate pairs ordered by
     increasing real part.

     The negative imaginary complex numbers are placed first within each
     pair.  All real numbers (those with ‘abs (imag (Z) / Z) < TOL’) are
     placed after the complex pairs.

     TOL is a weighting factor which determines the tolerance of
     matching.  The default value is 100 and the resulting tolerance for
     a given complex pair is ‘100 * eps (abs (Z(i)))’.

     By default the complex pairs are sorted along the first
     non-singleton dimension of Z.  If DIM is specified, then the
     complex pairs are sorted along this dimension.

     Signal an error if some complex numbers could not be paired.
     Signal an error if all complex numbers are not exact conjugates (to
     within TOL).  Note that there is no defined order for pairs with
     identical real parts but differing imaginary parts.

          cplxpair (exp (2i*pi*[0:4]'/5)) == exp (2i*pi*[3; 2; 4; 1; 0]/5)

 -- : imag (Z)
     Return the imaginary part of Z as a real number.

     See also: *note real: XREFreal, *note conj: XREFconj.

 -- : real (Z)
     Return the real part of Z.

     See also: *note imag: XREFimag, *note conj: XREFconj.


File: octave.info,  Node: Trigonometry,  Next: Sums and Products,  Prev: Complex Arithmetic,  Up: Arithmetic

17.3 Trigonometry
=================

Octave provides the following trigonometric functions where angles are
specified in radians.  To convert from degrees to radians multiply by
‘pi/180’ or use the ‘deg2rad’ function.  For example, ‘sin (30 *
pi/180)’ returns the sine of 30 degrees.  As an alternative, Octave
provides a number of trigonometric functions which work directly on an
argument specified in degrees.  These functions are named after the base
trigonometric function with a ‘d’ suffix.  As an example, ‘sin’ expects
an angle in radians while ‘sind’ expects an angle in degrees.

   Octave uses the C library trigonometric functions.  It is expected
that these functions are defined by the ISO/IEC 9899 Standard.  This
Standard is available at:
<http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf>.  Section
F.9.1 deals with the trigonometric functions.  The behavior of most of
the functions is relatively straightforward.  However, there are some
exceptions to the standard behavior.  Many of the exceptions involve the
behavior for -0.  The most complex case is atan2.  Octave exactly
implements the behavior given in the Standard.  Including ‘atan2(+- 0,
0)’ returns ‘+- pi’.

   It should be noted that MATLAB uses different definitions which
apparently do not distinguish -0.

 -- : RAD = deg2rad (DEG)

     Convert degrees to radians.

     The input DEG must be a scalar, vector, or N-dimensional array of
     double or single floating point values.  DEG may be complex in
     which case the real and imaginary components are converted
     separately.

     The output RAD is the same size and shape as DEG with degrees
     converted to radians using the conversion constant ‘pi/180’.

     Example:

          deg2rad ([0, 90, 180, 270, 360])
            ⇒  0.00000   1.57080   3.14159   4.71239   6.28319

     See also: *note rad2deg: XREFrad2deg.

 -- : DEG = rad2deg (RAD)

     Convert radians to degrees.

     The input RAD must be a scalar, vector, or N-dimensional array of
     double or single floating point values.  RAD may be complex in
     which case the real and imaginary components are converted
     separately.

     The output DEG is the same size and shape as RAD with radians
     converted to degrees using the conversion constant ‘180/pi’.

     Example:

          rad2deg ([0, pi/2, pi, 3/2*pi, 2*pi])
            ⇒  0    90   180   270   360

     See also: *note deg2rad: XREFdeg2rad.

 -- : sin (X)
     Compute the sine for each element of X in radians.

     See also: *note asin: XREFasin, *note sind: XREFsind, *note sinh:
     XREFsinh.

 -- : cos (X)
     Compute the cosine for each element of X in radians.

     See also: *note acos: XREFacos, *note cosd: XREFcosd, *note cosh:
     XREFcosh.

 -- : tan (Z)
     Compute the tangent for each element of X in radians.

     See also: *note atan: XREFatan, *note tand: XREFtand, *note tanh:
     XREFtanh.

 -- : sec (X)
     Compute the secant for each element of X in radians.

     See also: *note asec: XREFasec, *note secd: XREFsecd, *note sech:
     XREFsech.

 -- : csc (X)
     Compute the cosecant for each element of X in radians.

     See also: *note acsc: XREFacsc, *note cscd: XREFcscd, *note csch:
     XREFcsch.

 -- : cot (X)
     Compute the cotangent for each element of X in radians.

     See also: *note acot: XREFacot, *note cotd: XREFcotd, *note coth:
     XREFcoth.

 -- : asin (X)
     Compute the inverse sine in radians for each element of X.

     See also: *note sin: XREFsin, *note asind: XREFasind.

 -- : acos (X)
     Compute the inverse cosine in radians for each element of X.

     See also: *note cos: XREFcos, *note acosd: XREFacosd.

 -- : atan (X)
     Compute the inverse tangent in radians for each element of X.

     See also: *note tan: XREFtan, *note atand: XREFatand.

 -- : asec (X)
     Compute the inverse secant in radians for each element of X.

     See also: *note sec: XREFsec, *note asecd: XREFasecd.

 -- : acsc (X)
     Compute the inverse cosecant in radians for each element of X.

     See also: *note csc: XREFcsc, *note acscd: XREFacscd.

 -- : acot (X)
     Compute the inverse cotangent in radians for each element of X.

     See also: *note cot: XREFcot, *note acotd: XREFacotd.

 -- : sinh (X)
     Compute the hyperbolic sine for each element of X.

     See also: *note asinh: XREFasinh, *note cosh: XREFcosh, *note tanh:
     XREFtanh.

 -- : cosh (X)
     Compute the hyperbolic cosine for each element of X.

     See also: *note acosh: XREFacosh, *note sinh: XREFsinh, *note tanh:
     XREFtanh.

 -- : tanh (X)
     Compute hyperbolic tangent for each element of X.

     See also: *note atanh: XREFatanh, *note sinh: XREFsinh, *note cosh:
     XREFcosh.

 -- : sech (X)
     Compute the hyperbolic secant of each element of X.

     See also: *note asech: XREFasech.

 -- : csch (X)
     Compute the hyperbolic cosecant of each element of X.

     See also: *note acsch: XREFacsch.

 -- : coth (X)
     Compute the hyperbolic cotangent of each element of X.

     See also: *note acoth: XREFacoth.

 -- : asinh (X)
     Compute the inverse hyperbolic sine for each element of X.

     See also: *note sinh: XREFsinh.

 -- : acosh (X)
     Compute the inverse hyperbolic cosine for each element of X.

     See also: *note cosh: XREFcosh.

 -- : atanh (X)
     Compute the inverse hyperbolic tangent for each element of X.

     See also: *note tanh: XREFtanh.

 -- : asech (X)
     Compute the inverse hyperbolic secant of each element of X.

     See also: *note sech: XREFsech.

 -- : acsch (X)
     Compute the inverse hyperbolic cosecant of each element of X.

     See also: *note csch: XREFcsch.

 -- : acoth (X)
     Compute the inverse hyperbolic cotangent of each element of X.

     See also: *note coth: XREFcoth.

 -- : atan2 (Y, X)
     Compute atan (Y / X) for corresponding elements of Y and X.

     Y and X must match in size and orientation.  The signs of elements
     of Y and X are used to determine the quadrants of each resulting
     value.

     This function is equivalent to ‘arg (complex (X, Y))’.

     See also: *note tan: XREFtan, *note tand: XREFtand, *note tanh:
     XREFtanh, *note atanh: XREFatanh.

   Octave provides the following trigonometric functions where angles
are specified in degrees.  These functions produce true zeros at the
appropriate intervals rather than the small round-off error that occurs
when using radians.  For example:

     cosd (90)
          ⇒ 0
     cos (pi/2)
          ⇒ 6.1230e-17

 -- : sind (X)
     Compute the sine for each element of X in degrees.

     Returns zero for elements where ‘X/180’ is an integer.

     See also: *note asind: XREFasind, *note sin: XREFsin.

 -- : cosd (X)
     Compute the cosine for each element of X in degrees.

     Returns zero for elements where ‘(X-90)/180’ is an integer.

     See also: *note acosd: XREFacosd, *note cos: XREFcos.

 -- : tand (X)
     Compute the tangent for each element of X in degrees.

     Returns zero for elements where ‘X/180’ is an integer and ‘Inf’ for
     elements where ‘(X-90)/180’ is an integer.

     See also: *note atand: XREFatand, *note tan: XREFtan.

 -- : secd (X)
     Compute the secant for each element of X in degrees.

     See also: *note asecd: XREFasecd, *note sec: XREFsec.

 -- : cscd (X)
     Compute the cosecant for each element of X in degrees.

     See also: *note acscd: XREFacscd, *note csc: XREFcsc.

 -- : cotd (X)
     Compute the cotangent for each element of X in degrees.

     See also: *note acotd: XREFacotd, *note cot: XREFcot.

 -- : asind (X)
     Compute the inverse sine in degrees for each element of X.

     See also: *note sind: XREFsind, *note asin: XREFasin.

 -- : acosd (X)
     Compute the inverse cosine in degrees for each element of X.

     See also: *note cosd: XREFcosd, *note acos: XREFacos.

 -- : atand (X)
     Compute the inverse tangent in degrees for each element of X.

     See also: *note tand: XREFtand, *note atan: XREFatan.

 -- : atan2d (Y, X)
     Compute atan2 (Y / X) in degrees for corresponding elements from Y
     and X.

     See also: *note tand: XREFtand, *note atan2: XREFatan2.

 -- : asecd (X)
     Compute the inverse secant in degrees for each element of X.

     See also: *note secd: XREFsecd, *note asec: XREFasec.

 -- : acscd (X)
     Compute the inverse cosecant in degrees for each element of X.

     See also: *note cscd: XREFcscd, *note acsc: XREFacsc.

 -- : acotd (X)
     Compute the inverse cotangent in degrees for each element of X.

     See also: *note cotd: XREFcotd, *note acot: XREFacot.


File: octave.info,  Node: Sums and Products,  Next: Utility Functions,  Prev: Trigonometry,  Up: Arithmetic

17.4 Sums and Products
======================

 -- : sum (X)
 -- : sum (X, DIM)
 -- : sum (..., "native")
 -- : sum (..., "double")
 -- : sum (..., "extra")
     Sum of elements along dimension DIM.

     If DIM is omitted, it defaults to the first non-singleton
     dimension.

     The optional "type" input determines the class of the variable used
     for calculations.  If the argument "native" is given, then the
     operation is performed in the same type as the original argument,
     rather than the default double type.

     For example:

          sum ([true, true])
             ⇒ 2
          sum ([true, true], "native")
             ⇒ true

     On the contrary, if "double" is given, the sum is performed in
     double precision even for single precision inputs.

     For double precision inputs, the "extra" option will use a more
     accurate algorithm than straightforward summation.  For single
     precision inputs, "extra" is the same as "double".  Otherwise,
     "extra" has no effect.

     See also: *note cumsum: XREFcumsum, *note sumsq: XREFsumsq, *note
     prod: XREFprod.

 -- : prod (X)
 -- : prod (X, DIM)
 -- : prod (..., "native")
 -- : prod (..., "double")
     Product of elements along dimension DIM.

     If DIM is omitted, it defaults to the first non-singleton
     dimension.

     The optional "type" input determines the class of the variable used
     for calculations.  If the argument "native" is given, then the
     operation is performed in the same type as the original argument,
     rather than the default double type.

     For example:

          prod ([true, true])
             ⇒ 1
          prod ([true, true], "native")
             ⇒ true

     On the contrary, if "double" is given, the operation is performed
     in double precision even for single precision inputs.

     See also: *note cumprod: XREFcumprod, *note sum: XREFsum.

 -- : cumsum (X)
 -- : cumsum (X, DIM)
 -- : cumsum (..., "native")
 -- : cumsum (..., "double")
 -- : cumsum (..., "extra")
     Cumulative sum of elements along dimension DIM.

     If DIM is omitted, it defaults to the first non-singleton
     dimension.  For example:

          cumsum ([1, 2; 3, 4; 5, 6])
             ⇒  1   2
                 4   6
                 9  12

     See ‘sum’ for an explanation of the optional parameters "native",
     "double", and "extra".

     See also: *note sum: XREFsum, *note cumprod: XREFcumprod.

 -- : cumprod (X)
 -- : cumprod (X, DIM)
     Cumulative product of elements along dimension DIM.

     If DIM is omitted, it defaults to the first non-singleton
     dimension.  For example:

          cumprod ([1, 2; 3, 4; 5, 6])
             ⇒  1   2
                 3   8
                15  48

     See also: *note prod: XREFprod, *note cumsum: XREFcumsum.

 -- : sumsq (X)
 -- : sumsq (X, DIM)
     Sum of squares of elements along dimension DIM.

     If DIM is omitted, it defaults to the first non-singleton
     dimension.

     This function is conceptually equivalent to computing

          sum (x .* conj (x), dim)

     but it uses less memory and avoids calling ‘conj’ if X is real.

     See also: *note sum: XREFsum, *note prod: XREFprod.


File: octave.info,  Node: Utility Functions,  Next: Special Functions,  Prev: Sums and Products,  Up: Arithmetic

17.5 Utility Functions
======================

 -- : ceil (X)
     Return the smallest integer not less than X.

     This is equivalent to rounding towards positive infinity.

     If X is complex, return ‘ceil (real (X)) + ceil (imag (X)) * I’.

          ceil ([-2.7, 2.7])
              ⇒ -2    3

     See also: *note floor: XREFfloor, *note round: XREFround, *note
     fix: XREFfix.

 -- : fix (X)
     Truncate fractional portion of X and return the integer portion.

     This is equivalent to rounding towards zero.  If X is complex,
     return ‘fix (real (X)) + fix (imag (X)) * I’.

          fix ([-2.7, 2.7])
             ⇒ -2    2

     See also: *note ceil: XREFceil, *note floor: XREFfloor, *note
     round: XREFround.

 -- : floor (X)
     Return the largest integer not greater than X.

     This is equivalent to rounding towards negative infinity.  If X is
     complex, return ‘floor (real (X)) + floor (imag (X)) * I’.

          floor ([-2.7, 2.7])
               ⇒ -3    2

     See also: *note ceil: XREFceil, *note round: XREFround, *note fix:
     XREFfix.

 -- : round (X)
     Return the integer nearest to X.

     If X is complex, return ‘round (real (X)) + round (imag (X)) * I’.
     If there are two nearest integers, return the one further away from
     zero.

          round ([-2.7, 2.7])
               ⇒ -3    3

     See also: *note ceil: XREFceil, *note floor: XREFfloor, *note fix:
     XREFfix, *note roundb: XREFroundb.

 -- : roundb (X)
     Return the integer nearest to X.  If there are two nearest
     integers, return the even one (banker’s rounding).

     If X is complex, return ‘roundb (real (X)) + roundb (imag (X)) *
     I’.

     See also: *note round: XREFround.

 -- : max (X)
 -- : max (X, [], DIM)
 -- : [W, IW] = max (X)
 -- : max (X, Y)
     Find maximum values in the array X.

     For a vector argument, return the maximum value.  For a matrix
     argument, return a row vector with the maximum value of each
     column.  For a multi-dimensional array, ‘max’ operates along the
     first non-singleton dimension.

     If the optional third argument DIM is present then operate along
     this dimension.  In this case the second argument is ignored and
     should be set to the empty matrix.

     For two matrices (or a matrix and a scalar), return the pairwise
     maximum.

     Thus,

          max (max (X))

     returns the largest element of the 2-D matrix X, and

          max (2:5, pi)
              ⇒  3.1416  3.1416  4.0000  5.0000

     compares each element of the range ‘2:5’ with ‘pi’, and returns a
     row vector of the maximum values.

     For complex arguments, the magnitude of the elements are used for
     comparison.  If the magnitudes are identical, then the results are
     ordered by phase angle in the range (-pi, pi].  Hence,

          max ([-1 i 1 -i])
              ⇒ -1

     because all entries have magnitude 1, but -1 has the largest phase
     angle with value pi.

     If called with one input and two output arguments, ‘max’ also
     returns the first index of the maximum value(s).  Thus,

          [x, ix] = max ([1, 3, 5, 2, 5])
              ⇒  x = 5
                  ix = 3

     See also: *note min: XREFmin, *note cummax: XREFcummax, *note
     cummin: XREFcummin.

 -- : min (X)
 -- : min (X, [], DIM)
 -- : [W, IW] = min (X)
 -- : min (X, Y)
     Find minimum values in the array X.

     For a vector argument, return the minimum value.  For a matrix
     argument, return a row vector with the minimum value of each
     column.  For a multi-dimensional array, ‘min’ operates along the
     first non-singleton dimension.

     If the optional third argument DIM is present then operate along
     this dimension.  In this case the second argument is ignored and
     should be set to the empty matrix.

     For two matrices (or a matrix and a scalar), return the pairwise
     minimum.

     Thus,

          min (min (X))

     returns the smallest element of the 2-D matrix X, and

          min (2:5, pi)
              ⇒  2.0000  3.0000  3.1416  3.1416

     compares each element of the range ‘2:5’ with ‘pi’, and returns a
     row vector of the minimum values.

     For complex arguments, the magnitude of the elements are used for
     comparison.  If the magnitudes are identical, then the results are
     ordered by phase angle in the range (-pi, pi].  Hence,

          min ([-1 i 1 -i])
              ⇒ -i

     because all entries have magnitude 1, but -i has the smallest phase
     angle with value -pi/2.

     If called with one input and two output arguments, ‘min’ also
     returns the first index of the minimum value(s).  Thus,

          [x, ix] = min ([1, 3, 0, 2, 0])
              ⇒  x = 0
                  ix = 3

     See also: *note max: XREFmax, *note cummin: XREFcummin, *note
     cummax: XREFcummax.

 -- : cummax (X)
 -- : cummax (X, DIM)
 -- : [W, IW] = cummax (...)
     Return the cumulative maximum values along dimension DIM.

     If DIM is unspecified it defaults to column-wise operation.  For
     example:

          cummax ([1 3 2 6 4 5])
             ⇒  1  3  3  6  6  6

     If called with two output arguments the index of the maximum value
     is also returned.

          [w, iw] = cummax ([1 3 2 6 4 5])
          ⇒
          w =  1  3  3  6  6  6
          iw = 1  2  2  4  4  4

     See also: *note cummin: XREFcummin, *note max: XREFmax, *note min:
     XREFmin.

 -- : cummin (X)
 -- : cummin (X, DIM)
 -- : [W, IW] = cummin (X)
     Return the cumulative minimum values along dimension DIM.

     If DIM is unspecified it defaults to column-wise operation.  For
     example:

          cummin ([5 4 6 2 3 1])
             ⇒  5  4  4  2  2  1

     If called with two output arguments the index of the minimum value
     is also returned.

          [w, iw] = cummin ([5 4 6 2 3 1])
          ⇒
          w =  5  4  4  2  2  1
          iw = 1  2  2  4  4  6

     See also: *note cummax: XREFcummax, *note min: XREFmin, *note max:
     XREFmax.

 -- : hypot (X, Y)
 -- : hypot (X, Y, Z, ...)
     Compute the element-by-element square root of the sum of the
     squares of X and Y.

     This is equivalent to ‘sqrt (X.^2 + Y.^2)’, but is calculated in a
     manner that avoids overflows for large values of X or Y.

     ‘hypot’ can also be called with more than 2 arguments; in this
     case, the arguments are accumulated from left to right:

          hypot (hypot (X, Y), Z)
          hypot (hypot (hypot (X, Y), Z), W), etc.

 -- : DX = gradient (M)
 -- : [DX, DY, DZ, ...] = gradient (M)
 -- : [...] = gradient (M, S)
 -- : [...] = gradient (M, X, Y, Z, ...)
 -- : [...] = gradient (F, X0)
 -- : [...] = gradient (F, X0, S)
 -- : [...] = gradient (F, X0, X, Y, ...)

     Calculate the gradient of sampled data or a function.

     If M is a vector, calculate the one-dimensional gradient of M.  If
     M is a matrix the gradient is calculated for each dimension.

     ‘[DX, DY] = gradient (M)’ calculates the one-dimensional gradient
     for X and Y direction if M is a matrix.  Additional return
     arguments can be use for multi-dimensional matrices.

     A constant spacing between two points can be provided by the S
     parameter.  If S is a scalar, it is assumed to be the spacing for
     all dimensions.  Otherwise, separate values of the spacing can be
     supplied by the X, ... arguments.  Scalar values specify an
     equidistant spacing.  Vector values for the X, ... arguments
     specify the coordinate for that dimension.  The length must match
     their respective dimension of M.

     At boundary points a linear extrapolation is applied.  Interior
     points are calculated with the first approximation of the numerical
     gradient

          y'(i) = 1/(x(i+1)-x(i-1)) * (y(i-1)-y(i+1)).

     If the first argument F is a function handle, the gradient of the
     function at the points in X0 is approximated using central
     difference.  For example, ‘gradient (@cos, 0)’ approximates the
     gradient of the cosine function in the point x0 = 0.  As with
     sampled data, the spacing values between the points from which the
     gradient is estimated can be set via the S or DX, DY, ...
     arguments.  By default a spacing of 1 is used.

     See also: *note diff: XREFdiff, *note del2: XREFdel2.

 -- : dot (X, Y, DIM)
     Compute the dot product of two vectors.

     If X and Y are matrices, calculate the dot products along the first
     non-singleton dimension.

     If the optional argument DIM is given, calculate the dot products
     along this dimension.

     This is equivalent to ‘sum (conj (X) .* Y, DIM)’, but avoids
     forming a temporary array and is faster.  When X and Y are column
     vectors, the result is equivalent to ‘X' * Y’.

     See also: *note cross: XREFcross, *note divergence: XREFdivergence.

 -- : cross (X, Y)
 -- : cross (X, Y, DIM)
     Compute the vector cross product of two 3-dimensional vectors X and
     Y.

     If X and Y are matrices, the cross product is applied along the
     first dimension with three elements.

     The optional argument DIM forces the cross product to be calculated
     along the specified dimension.

     Example Code:

          cross ([1,1,0], [0,1,1])
               ⇒ [ 1; -1; 1 ]

     See also: *note dot: XREFdot, *note curl: XREFcurl, *note
     divergence: XREFdivergence.

 -- : DIV = divergence (X, Y, Z, FX, FY, FZ)
 -- : DIV = divergence (FX, FY, FZ)
 -- : DIV = divergence (X, Y, FX, FY)
 -- : DIV = divergence (FX, FY)
     Calculate divergence of a vector field given by the arrays FX, FY,
     and FZ or FX, FY respectively.

                            d               d               d
          div F(x,y,z)  =   -- F(x,y,z)  +  -- F(x,y,z)  +  -- F(x,y,z)
                            dx              dy              dz

     The coordinates of the vector field can be given by the arguments
     X, Y, Z or X, Y respectively.

     See also: *note curl: XREFcurl, *note gradient: XREFgradient, *note
     del2: XREFdel2, *note dot: XREFdot.

 -- : [CX, CY, CZ, V] = curl (X, Y, Z, FX, FY, FZ)
 -- : [CZ, V] = curl (X, Y, FX, FY)
 -- : [...] = curl (FX, FY, FZ)
 -- : [...] = curl (FX, FY)
 -- : V = curl (...)
     Calculate curl of vector field given by the arrays FX, FY, and FZ
     or FX, FY respectively.

                            / d         d       d         d       d         d     \
          curl F(x,y,z)  =  | -- Fz  -  -- Fy,  -- Fx  -  -- Fz,  -- Fy  -  -- Fx |
                            \ dy        dz      dz        dx      dx        dy    /

     The coordinates of the vector field can be given by the arguments
     X, Y, Z or X, Y respectively.  V calculates the scalar component of
     the angular velocity vector in direction of the z-axis for
     two-dimensional input.  For three-dimensional input the scalar
     rotation is calculated at each grid point in direction of the
     vector field at that point.

     See also: *note divergence: XREFdivergence, *note gradient:
     XREFgradient, *note del2: XREFdel2, *note cross: XREFcross.

 -- : D = del2 (M)
 -- : D = del2 (M, H)
 -- : D = del2 (M, DX, DY, ...)

     Calculate the discrete Laplace operator.

     For a 2-dimensional matrix M this is defined as

                1    / d^2            d^2         \
          D  = --- * | ---  M(x,y) +  ---  M(x,y) |
                4    \ dx^2           dy^2        /

     For N-dimensional arrays the sum in parentheses is expanded to
     include second derivatives over the additional higher dimensions.

     The spacing between evaluation points may be defined by H, which is
     a scalar defining the equidistant spacing in all dimensions.
     Alternatively, the spacing in each dimension may be defined
     separately by DX, DY, etc.  A scalar spacing argument defines
     equidistant spacing, whereas a vector argument can be used to
     specify variable spacing.  The length of the spacing vectors must
     match the respective dimension of M.  The default spacing value is
     1.

     At least 3 data points are needed for each dimension.  Boundary
     points are calculated from the linear extrapolation of interior
     points.

     See also: *note gradient: XREFgradient, *note diff: XREFdiff.

 -- : factorial (N)
     Return the factorial of N where N is a real non-negative integer.

     If N is a scalar, this is equivalent to ‘prod (1:N)’.  For vector
     or matrix arguments, return the factorial of each element in the
     array.

     For non-integers see the generalized factorial function ‘gamma’.
     Note that the factorial function grows large quite quickly, and
     even with double precision values overflow will occur if N > 171.
     For such cases consider ‘gammaln’.

     See also: *note prod: XREFprod, *note gamma: XREFgamma, *note
     gammaln: XREFgammaln.

 -- : PF = factor (Q)
 -- : [PF, N] = factor (Q)
     Return the prime factorization of Q.

     The prime factorization is defined as ‘prod (PF) == Q’ where every
     element of PF is a prime number.  If ‘Q == 1’, return 1.

     With two output arguments, return the unique prime factors PF and
     their multiplicities.  That is, ‘prod (PF .^ N) == Q’.

     Implementation Note: The input Q must be less than ‘flintmax’
     (9.0072e+15) in order to factor correctly.

     See also: *note gcd: XREFgcd, *note lcm: XREFlcm, *note isprime:
     XREFisprime, *note primes: XREFprimes.

 -- : G = gcd (A1, A2, ...)
 -- : [G, V1, ...] = gcd (A1, A2, ...)
     Compute the greatest common divisor of A1, A2, ....

     If more than one argument is given then all arguments must be the
     same size or scalar.  In this case the greatest common divisor is
     calculated for each element individually.  All elements must be
     ordinary or Gaussian (complex) integers.  Note that for Gaussian
     integers, the gcd is only unique up to a phase factor
     (multiplication by 1, -1, i, or -i), so an arbitrary greatest
     common divisor among the four possible is returned.

     Optional return arguments V1, ..., contain integer vectors such
     that,

          G = V1 .* A1 + V2 .* A2 + ...

     Example code:

          gcd ([15, 9], [20, 18])
             ⇒  5  9

     See also: *note lcm: XREFlcm, *note factor: XREFfactor, *note
     isprime: XREFisprime.

 -- : lcm (X, Y)
 -- : lcm (X, Y, ...)
     Compute the least common multiple of X and Y, or of the list of all
     arguments.

     All elements must be numeric and of the same size or scalar.

     See also: *note factor: XREFfactor, *note gcd: XREFgcd, *note
     isprime: XREFisprime.

 -- : chop (X, NDIGITS, BASE)
     Truncate elements of X to a length of NDIGITS such that the
     resulting numbers are exactly divisible by BASE.

     If BASE is not specified it defaults to 10.

          chop (-pi, 5, 10)
             ⇒ -3.14200000000000
          chop (-pi, 5, 5)
             ⇒ -3.14150000000000

 -- : rem (X, Y)
     Return the remainder of the division ‘X / Y’.

     The remainder is computed using the expression

          x - y .* fix (x ./ y)

     An error message is printed if the dimensions of the arguments do
     not agree, or if either argument is complex.

     Programming Notes: Floating point numbers within a few eps of an
     integer will be rounded to an integer before computation for
     compatibility with MATLAB.

     By convention,

          rem (X, 0) = NaN  if X is a floating point variable
          rem (X, 0) = 0    if X is an integer variable
          rem (X, Y)        returns a value with the signbit from X

     For the opposite conventions see the ‘mod’ function.  In general,
     ‘rem’ is best when computing the remainder after division of two
     _positive_ numbers.  For negative numbers, or when the values are
     periodic, ‘mod’ is a better choice.

     See also: *note mod: XREFmod.

 -- : mod (X, Y)
     Compute the modulo of X and Y.

     Conceptually this is given by

          x - y .* floor (x ./ y)

     and is written such that the correct modulus is returned for
     integer types.  This function handles negative values correctly.
     That is, ‘mod (-1, 3)’ is 2, not -1, as ‘rem (-1, 3)’ returns.

     An error results if the dimensions of the arguments do not agree,
     or if either of the arguments is complex.

     Programming Notes: Floating point numbers within a few eps of an
     integer will be rounded to an integer before computation for
     compatibility with MATLAB.

     By convention,

          mod (X, 0) = X
          mod (X, Y)      returns a value with the signbit from Y

     For the opposite conventions see the ‘rem’ function.  In general,
     ‘mod’ is a better choice than ‘rem’ when any of the inputs are
     negative numbers or when the values are periodic.

     See also: *note rem: XREFrem.

 -- : primes (N)
     Return all primes up to N.

     The output data class (double, single, uint32, etc.)  is the same
     as the input class of N.  The algorithm used is the Sieve of
     Eratosthenes.

     Notes: If you need a specific number of primes you can use the fact
     that the distance from one prime to the next is, on average,
     proportional to the logarithm of the prime.  Integrating, one finds
     that there are about k primes less than k*log (5*k).

     See also ‘list_primes’ if you need a specific number N of primes.

     See also: *note list_primes: XREFlist_primes, *note isprime:
     XREFisprime.

 -- : list_primes ()
 -- : list_primes (N)
     List the first N primes.

     If N is unspecified, the first 25 primes are listed.

     See also: *note primes: XREFprimes, *note isprime: XREFisprime.

 -- : sign (X)
     Compute the “signum” function.

     This is defined as

                     -1, x < 0;
          sign (x) =  0, x = 0;
                      1, x > 0.

     For complex arguments, ‘sign’ returns ‘x ./ abs (X)’.

     Note that ‘sign (-0.0)’ is 0.  Although IEEE 754 floating point
     allows zero to be signed, 0.0 and -0.0 compare equal.  If you must
     test whether zero is signed, use the ‘signbit’ function.

     See also: *note signbit: XREFsignbit.

 -- : signbit (X)
     Return logical true if the value of X has its sign bit set and
     false otherwise.

     This behavior is consistent with the other logical functions.  See
     *note Logical Values::.  The behavior differs from the C language
     function which returns nonzero if the sign bit is set.

     This is not the same as ‘x < 0.0’, because IEEE 754 floating point
     allows zero to be signed.  The comparison ‘-0.0 < 0.0’ is false,
     but ‘signbit (-0.0)’ will return a nonzero value.

     See also: *note sign: XREFsign.


File: octave.info,  Node: Special Functions,  Next: Rational Approximations,  Prev: Utility Functions,  Up: Arithmetic

17.6 Special Functions
======================

 -- : [A, IERR] = airy (K, Z, OPT)
     Compute Airy functions of the first and second kind, and their
     derivatives.

           K   Function   Scale factor (if "opt" is supplied)
          ---  --------   ---------------------------------------
           0   Ai (Z)     exp ((2/3) * Z * sqrt (Z))
           1   dAi(Z)/dZ  exp ((2/3) * Z * sqrt (Z))
           2   Bi (Z)     exp (-abs (real ((2/3) * Z * sqrt (Z))))
           3   dBi(Z)/dZ  exp (-abs (real ((2/3) * Z * sqrt (Z))))

     The function call ‘airy (Z)’ is equivalent to ‘airy (0, Z)’.

     The result is the same size as Z.

     If requested, IERR contains the following status information and is
     the same size as the result.

       0. Normal return.

       1. Input error, return ‘NaN’.

       2. Overflow, return ‘Inf’.

       3. Loss of significance by argument reduction results in less
          than half of machine accuracy.

       4. Complete loss of significance by argument reduction, return
          ‘NaN’.

       5. Error—no computation, algorithm termination condition not met,
          return ‘NaN’.

 -- : [J, IERR] = besselj (ALPHA, X, OPT)
 -- : [Y, IERR] = bessely (ALPHA, X, OPT)
 -- : [I, IERR] = besseli (ALPHA, X, OPT)
 -- : [K, IERR] = besselk (ALPHA, X, OPT)
 -- : [H, IERR] = besselh (ALPHA, K, X, OPT)
     Compute Bessel or Hankel functions of various kinds:

     ‘besselj’
          Bessel functions of the first kind.  If the argument OPT is 1
          or true, the result is multiplied by ‘exp (-abs (imag (X)))’.

     ‘bessely’
          Bessel functions of the second kind.  If the argument OPT is 1
          or true, the result is multiplied by ‘exp (-abs (imag (X)))’.

     ‘besseli’

          Modified Bessel functions of the first kind.  If the argument
          OPT is 1 or true, the result is multiplied by ‘exp (-abs (real
          (X)))’.

     ‘besselk’

          Modified Bessel functions of the second kind.  If the argument
          OPT is 1 or true, the result is multiplied by ‘exp (X)’.

     ‘besselh’
          Compute Hankel functions of the first (K = 1) or second (K =
          2) kind.  If the argument OPT is 1 or true, the result is
          multiplied by ‘exp (-I*X)’ for K = 1 or ‘exp (I*X)’ for K = 2.

     If ALPHA is a scalar, the result is the same size as X.  If X is a
     scalar, the result is the same size as ALPHA.  If ALPHA is a row
     vector and X is a column vector, the result is a matrix with
     ‘length (X)’ rows and ‘length (ALPHA)’ columns.  Otherwise, ALPHA
     and X must conform and the result will be the same size.

     The value of ALPHA must be real.  The value of X may be complex.

     If requested, IERR contains the following status information and is
     the same size as the result.

       0. Normal return.

       1. Input error, return ‘NaN’.

       2. Overflow, return ‘Inf’.

       3. Loss of significance by argument reduction results in less
          than half of machine accuracy.

       4. Complete loss of significance by argument reduction, return
          ‘NaN’.

       5. Error—no computation, algorithm termination condition not met,
          return ‘NaN’.

 -- : beta (A, B)
     Compute the Beta function for real inputs A and B.

     The Beta function definition is

          beta (a, b) = gamma (a) * gamma (b) / gamma (a + b).

     The Beta function can grow quite large and it is often more useful
     to work with the logarithm of the output rather than the function
     directly.  *Note betaln: XREFbetaln, for computing the logarithm of
     the Beta function in an efficient manner.

     See also: *note betaln: XREFbetaln, *note betainc: XREFbetainc,
     *note betaincinv: XREFbetaincinv.

 -- : betainc (X, A, B)
     Compute the regularized incomplete Beta function.

     The regularized incomplete Beta function is defined by

                                             x
                                    1       /
          betainc (x, a, b) = -----------   | t^(a-1) (1-t)^(b-1) dt.
                              beta (a, b)   /
                                         t=0

     If X has more than one component, both A and B must be scalars.  If
     X is a scalar, A and B must be of compatible dimensions.

     See also: *note betaincinv: XREFbetaincinv, *note beta: XREFbeta,
     *note betaln: XREFbetaln.

 -- : betaincinv (Y, A, B)
     Compute the inverse of the incomplete Beta function.

     The inverse is the value X such that

          Y == betainc (X, A, B)

     See also: *note betainc: XREFbetainc, *note beta: XREFbeta, *note
     betaln: XREFbetaln.

 -- : betaln (A, B)
     Compute the natural logarithm of the Beta function for real inputs
     A and B.

     ‘betaln’ is defined as

          betaln (a, b) = log (beta (a, b))

     and is calculated in a way to reduce the occurrence of underflow.

     The Beta function can grow quite large and it is often more useful
     to work with the logarithm of the output rather than the function
     directly.

     See also: *note beta: XREFbeta, *note betainc: XREFbetainc, *note
     betaincinv: XREFbetaincinv, *note gammaln: XREFgammaln.

 -- : bincoeff (N, K)
     Return the binomial coefficient of N and K, defined as

           /   \
           | n |    n (n-1) (n-2) ... (n-k+1)
           |   |  = -------------------------
           | k |               k!
           \   /

     For example:

          bincoeff (5, 2)
             ⇒ 10

     In most cases, the ‘nchoosek’ function is faster for small scalar
     integer arguments.  It also warns about loss of precision for big
     arguments.

     See also: *note nchoosek: XREFnchoosek.

 -- : commutation_matrix (M, N)
     Return the commutation matrix K(m,n) which is the unique M*N by M*N
     matrix such that K(m,n) * vec(A) = vec(A') for all m by n matrices
     A.

     If only one argument M is given, K(m,m) is returned.

     See Magnus and Neudecker (1988), ‘Matrix Differential Calculus with
     Applications in Statistics and Econometrics.’

 -- : duplication_matrix (N)
     Return the duplication matrix Dn which is the unique n^2 by
     n*(n+1)/2 matrix such that Dn vech (A) = vec (A) for all symmetric
     n by n matrices A.

     See Magnus and Neudecker (1988), ‘Matrix Differential Calculus with
     Applications in Statistics and Econometrics.’

 -- : dawson (Z)
     Compute the Dawson (scaled imaginary error) function.

     The Dawson function is defined as

          (sqrt (pi) / 2) * exp (-z^2) * erfi (z)

     See also: *note erfc: XREFerfc, *note erf: XREFerf, *note erfcx:
     XREFerfcx, *note erfi: XREFerfi, *note erfinv: XREFerfinv, *note
     erfcinv: XREFerfcinv.

 -- : [SN, CN, DN, ERR] = ellipj (U, M)
 -- : [SN, CN, DN, ERR] = ellipj (U, M, TOL)
     Compute the Jacobi elliptic functions SN, CN, and DN of complex
     argument U and real parameter M.

     If M is a scalar, the results are the same size as U.  If U is a
     scalar, the results are the same size as M.  If U is a column
     vector and M is a row vector, the results are matrices with ‘length
     (U)’ rows and ‘length (M)’ columns.  Otherwise, U and M must
     conform in size and the results will be the same size as the
     inputs.

     The value of U may be complex.  The value of M must be 0 ≤ M ≤ 1.

     The optional input TOL is currently ignored (MATLAB uses this to
     allow faster, less accurate approximation).

     If requested, ERR contains the following status information and is
     the same size as the result.

       0. Normal return.

       1. Error—no computation, algorithm termination condition not met,
          return ‘NaN’.

     Reference: Milton Abramowitz and Irene A Stegun, ‘Handbook of
     Mathematical Functions’, Chapter 16 (Sections 16.4, 16.13, and
     16.15), Dover, 1965.

     See also: *note ellipke: XREFellipke.

 -- : K = ellipke (M)
 -- : K = ellipke (M, TOL)
 -- : [K, E] = ellipke (...)
     Compute complete elliptic integrals of the first K(M) and second
     E(M) kind.

     M must be a scalar or real array with -Inf ≤ M ≤ 1.

     The optional input TOL controls the stopping tolerance of the
     algorithm and defaults to ‘eps (class (M))’.  The tolerance can be
     increased to compute a faster, less accurate approximation.

     When called with one output only elliptic integrals of the first
     kind are returned.

     Mathematical Note:

     Elliptic integrals of the first kind are defined as

                   1
                  /               dt
          K (m) = | ------------------------------
                  / sqrt ((1 - t^2)*(1 - m*t^2))
                 0

     Elliptic integrals of the second kind are defined as

                   1
                  /  sqrt (1 - m*t^2)
          E (m) = |  ------------------ dt
                  /  sqrt (1 - t^2)
                 0

     Reference: Milton Abramowitz and Irene A. Stegun, ‘Handbook of
     Mathematical Functions’, Chapter 17, Dover, 1965.

     See also: *note ellipj: XREFellipj.

 -- : erf (Z)
     Compute the error function.

     The error function is defined as

                                  z
                        2        /
          erf (z) = --------- *  | e^(-t^2) dt
                    sqrt (pi)    /
                              t=0

     See also: *note erfc: XREFerfc, *note erfcx: XREFerfcx, *note erfi:
     XREFerfi, *note dawson: XREFdawson, *note erfinv: XREFerfinv, *note
     erfcinv: XREFerfcinv.

 -- : erfc (Z)
     Compute the complementary error function.

     The complementary error function is defined as ‘1 - erf (Z)’.

     See also: *note erfcinv: XREFerfcinv, *note erfcx: XREFerfcx, *note
     erfi: XREFerfi, *note dawson: XREFdawson, *note erf: XREFerf, *note
     erfinv: XREFerfinv.

 -- : erfcx (Z)
     Compute the scaled complementary error function.

     The scaled complementary error function is defined as

          exp (z^2) * erfc (z)

     See also: *note erfc: XREFerfc, *note erf: XREFerf, *note erfi:
     XREFerfi, *note dawson: XREFdawson, *note erfinv: XREFerfinv, *note
     erfcinv: XREFerfcinv.

 -- : erfi (Z)
     Compute the imaginary error function.

     The imaginary error function is defined as

          -i * erf (i*z)

     See also: *note erfc: XREFerfc, *note erf: XREFerf, *note erfcx:
     XREFerfcx, *note dawson: XREFdawson, *note erfinv: XREFerfinv,
     *note erfcinv: XREFerfcinv.

 -- : erfinv (X)
     Compute the inverse error function.

     The inverse error function is defined such that

          erf (Y) == X

     See also: *note erf: XREFerf, *note erfc: XREFerfc, *note erfcx:
     XREFerfcx, *note erfi: XREFerfi, *note dawson: XREFdawson, *note
     erfcinv: XREFerfcinv.

 -- : erfcinv (X)
     Compute the inverse complementary error function.

     The inverse complementary error function is defined such that

          erfc (Y) == X

     See also: *note erfc: XREFerfc, *note erf: XREFerf, *note erfcx:
     XREFerfcx, *note erfi: XREFerfi, *note dawson: XREFdawson, *note
     erfinv: XREFerfinv.

 -- : expint (X)
     Compute the exponential integral:

                     infinity
                    /
          E_1 (x) = | exp (-t)/t dt
                    /
                   x

     Note: For compatibility, this functions uses the MATLAB definition
     of the exponential integral.  Most other sources refer to this
     particular value as E_1 (x), and the exponential integral as

                      infinity
                     /
          Ei (x) = - | exp (-t)/t dt
                     /
                   -x

     The two definitions are related, for positive real values of X, by
     ‘E_1 (-x) = -Ei (x) - i*pi’.

 -- : gamma (Z)
     Compute the Gamma function.

     The Gamma function is defined as

                       infinity
                      /
          gamma (z) = | t^(z-1) exp (-t) dt.
                      /
                   t=0

     Programming Note: The gamma function can grow quite large even for
     small input values.  In many cases it may be preferable to use the
     natural logarithm of the gamma function (‘gammaln’) in calculations
     to minimize loss of precision.  The final result is then ‘exp
     (RESULT_USING_GAMMALN).’

     See also: *note gammainc: XREFgammainc, *note gammaln: XREFgammaln,
     *note factorial: XREFfactorial.

 -- : gammainc (X, A)
 -- : gammainc (X, A, "lower")
 -- : gammainc (X, A, "upper")
     Compute the normalized incomplete gamma function.

     This is defined as

                                          x
                                 1       /
          gammainc (x, a) = ---------    | exp (-t) t^(a-1) dt
                            gamma (a)    /
                                      t=0

     with the limiting value of 1 as X approaches infinity.  The
     standard notation is P(a,x), e.g., Abramowitz and Stegun (6.5.1).

     If A is scalar, then ‘gammainc (X, A)’ is returned for each element
     of X and vice versa.

     If neither X nor A is scalar, the sizes of X and A must agree, and
     ‘gammainc’ is applied element-by-element.

     By default the incomplete gamma function integrated from 0 to X is
     computed.  If "upper" is given then the complementary function
     integrated from X to infinity is calculated.  It should be noted
     that

          gammainc (X, A) ≡ 1 - gammainc (X, A, "upper")

     See also: *note gamma: XREFgamma, *note gammaln: XREFgammaln.

 -- : L = legendre (N, X)
 -- : L = legendre (N, X, NORMALIZATION)
     Compute the Legendre function of degree N and order M = 0 ... N.

     The value N must be a real non-negative integer.

     X is a vector with real-valued elements in the range [-1, 1].

     The optional argument NORMALIZATION may be one of "unnorm", "sch",
     or "norm".  The default if no normalization is given is "unnorm".

     When the optional argument NORMALIZATION is "unnorm", compute the
     Legendre function of degree N and order M and return all values for
     M = 0 ... N.  The return value has one dimension more than X.

     The Legendre Function of degree N and order M:

           m         m      2  m/2   d^m
          P(x) = (-1) * (1-x  )    * ----  P(x)
           n                         dx^m   n

     with Legendre polynomial of degree N:

                    1    d^n   2    n
          P(x) = ------ [----(x - 1) ]
           n     2^n n!  dx^n

     ‘legendre (3, [-1.0, -0.9, -0.8])’ returns the matrix:

           x  |   -1.0   |   -0.9   |   -0.8
          ------------------------------------
          m=0 | -1.00000 | -0.47250 | -0.08000
          m=1 |  0.00000 | -1.99420 | -1.98000
          m=2 |  0.00000 | -2.56500 | -4.32000
          m=3 |  0.00000 | -1.24229 | -3.24000

     When the optional argument ‘normalization’ is "sch", compute the
     Schmidt semi-normalized associated Legendre function.  The Schmidt
     semi-normalized associated Legendre function is related to the
     unnormalized Legendre functions by the following:

     For Legendre functions of degree N and order 0:

            0      0
          SP(x) = P(x)
            n      n

     For Legendre functions of degree n and order m:

            m      m         m    2(n-m)! 0.5
          SP(x) = P(x) * (-1)  * [-------]
            n      n              (n+m)!

     When the optional argument NORMALIZATION is "norm", compute the
     fully normalized associated Legendre function.  The fully
     normalized associated Legendre function is related to the
     unnormalized Legendre functions by the following:

     For Legendre functions of degree N and order M

            m      m         m    (n+0.5)(n-m)! 0.5
          NP(x) = P(x) * (-1)  * [-------------]
            n      n                  (n+m)!

 -- : gammaln (X)
 -- : lgamma (X)
     Return the natural logarithm of the gamma function of X.

     See also: *note gamma: XREFgamma, *note gammainc: XREFgammainc.

 -- : psi (Z)
 -- : psi (K, Z)
     Compute the psi (polygamma) function.

     The polygamma functions are the Kth derivative of the logarithm of
     the gamma function.  If unspecified, K defaults to zero.  A value
     of zero computes the digamma function, a value of 1, the trigamma
     function, and so on.

     The digamma function is defined:

          psi (z) = d (log (gamma (z))) / dx

     When computing the digamma function (when K equals zero), Z can
     have any value real or complex value.  However, for polygamma
     functions (K higher than 0), Z must be real and non-negative.

     See also: *note gamma: XREFgamma, *note gammainc: XREFgammainc,
     *note gammaln: XREFgammaln.


File: octave.info,  Node: Rational Approximations,  Next: Coordinate Transformations,  Prev: Special Functions,  Up: Arithmetic

17.7 Rational Approximations
============================

 -- : S = rat (X, TOL)
 -- : [N, D] = rat (X, TOL)

     Find a rational approximation to X within the tolerance defined by
     TOL using a continued fraction expansion.

     For example:

          rat (pi) = 3 + 1/(7 + 1/16) = 355/113
          rat (e) = 3 + 1/(-4 + 1/(2 + 1/(5 + 1/(-2 + 1/(-7)))))
                  = 1457/536

     When called with two output arguments return the numerator and
     denominator separately as two matrices.

     See also: *note rats: XREFrats.

 -- : rats (X, LEN)
     Convert X into a rational approximation represented as a string.

     The string can be converted back into a matrix as follows:

          r = rats (hilb (4));
          x = str2num (r)

     The optional second argument defines the maximum length of the
     string representing the elements of X.  By default LEN is 9.

     If the length of the smallest possible rational approximation
     exceeds LEN, an asterisk (*) padded with spaces will be returned
     instead.

     See also: *note format: XREFformat, *note rat: XREFrat.


File: octave.info,  Node: Coordinate Transformations,  Next: Mathematical Constants,  Prev: Rational Approximations,  Up: Arithmetic

17.8 Coordinate Transformations
===============================

 -- : [THETA, R] = cart2pol (X, Y)
 -- : [THETA, R, Z] = cart2pol (X, Y, Z)
 -- : [THETA, R] = cart2pol (C)
 -- : [THETA, R, Z] = cart2pol (C)
 -- : P = cart2pol (...)

     Transform Cartesian coordinates to polar or cylindrical
     coordinates.

     The inputs X, Y (, and Z) must be the same shape, or scalar.  If
     called with a single matrix argument then each row of C represents
     the Cartesian coordinate (X, Y (, Z)).

     THETA describes the angle relative to the positive x-axis.

     R is the distance to the z-axis (0, 0, z).

     If only a single return argument is requested then return a matrix
     P where each row represents one polar/(cylindrical) coordinate
     (THETA, PHI (, Z)).

     See also: *note pol2cart: XREFpol2cart, *note cart2sph:
     XREFcart2sph, *note sph2cart: XREFsph2cart.

 -- : [X, Y] = pol2cart (THETA, R)
 -- : [X, Y, Z] = pol2cart (THETA, R, Z)
 -- : [X, Y] = pol2cart (P)
 -- : [X, Y, Z] = pol2cart (P)
 -- : C = pol2cart (...)
     Transform polar or cylindrical coordinates to Cartesian
     coordinates.

     The inputs THETA, R, (and Z) must be the same shape, or scalar.  If
     called with a single matrix argument then each row of P represents
     the polar/(cylindrical) coordinate (THETA, R (, Z)).

     THETA describes the angle relative to the positive x-axis.

     R is the distance to the z-axis (0, 0, z).

     If only a single return argument is requested then return a matrix
     C where each row represents one Cartesian coordinate (X, Y (, Z)).

     See also: *note cart2pol: XREFcart2pol, *note sph2cart:
     XREFsph2cart, *note cart2sph: XREFcart2sph.

 -- : [THETA, PHI, R] = cart2sph (X, Y, Z)
 -- : [THETA, PHI, R] = cart2sph (C)
 -- : S = cart2sph (...)
     Transform Cartesian coordinates to spherical coordinates.

     The inputs X, Y, and Z must be the same shape, or scalar.  If
     called with a single matrix argument then each row of C represents
     the Cartesian coordinate (X, Y, Z).

     THETA describes the angle relative to the positive x-axis.

     PHI is the angle relative to the xy-plane.

     R is the distance to the origin (0, 0, 0).

     If only a single return argument is requested then return a matrix
     S where each row represents one spherical coordinate (THETA, PHI,
     R).

     See also: *note sph2cart: XREFsph2cart, *note cart2pol:
     XREFcart2pol, *note pol2cart: XREFpol2cart.

 -- : [X, Y, Z] = sph2cart (THETA, PHI, R)
 -- : [X, Y, Z] = sph2cart (S)
 -- : C = sph2cart (...)
     Transform spherical coordinates to Cartesian coordinates.

     The inputs THETA, PHI, and R must be the same shape, or scalar.  If
     called with a single matrix argument then each row of S represents
     the spherical coordinate (THETA, PHI, R).

     THETA describes the angle relative to the positive x-axis.

     PHI is the angle relative to the xy-plane.

     R is the distance to the origin (0, 0, 0).

     If only a single return argument is requested then return a matrix
     C where each row represents one Cartesian coordinate (X, Y, Z).

     See also: *note cart2sph: XREFcart2sph, *note pol2cart:
     XREFpol2cart, *note cart2pol: XREFcart2pol.


File: octave.info,  Node: Mathematical Constants,  Prev: Coordinate Transformations,  Up: Arithmetic

17.9 Mathematical Constants
===========================

 -- : e
 -- : e (N)
 -- : e (N, M)
 -- : e (N, M, K, ...)
 -- : e (..., CLASS)
     Return a scalar, matrix, or N-dimensional array whose elements are
     all equal to the base of natural logarithms.

     The constant ‘e’ satisfies the equation ‘log’ (e) = 1.

     When called with no arguments, return a scalar with the value e.

     When called with a single argument, return a square matrix with the
     dimension specified.

     When called with more than one scalar argument the first two
     arguments are taken as the number of rows and columns and any
     further arguments specify additional matrix dimensions.

     The optional argument CLASS specifies the return type and may be
     either "double" or "single".

     See also: *note log: XREFlog, *note exp: XREFexp, *note pi: XREFpi,
     *note I: XREFI.

 -- : pi
 -- : pi (N)
 -- : pi (N, M)
 -- : pi (N, M, K, ...)
 -- : pi (..., CLASS)
     Return a scalar, matrix, or N-dimensional array whose elements are
     all equal to the ratio of the circumference of a circle to its
     diameter.

     Internally, ‘pi’ is computed as ‘4.0 * atan (1.0)’.

     When called with no arguments, return a scalar with the value of
     pi.

     When called with a single argument, return a square matrix with the
     dimension specified.

     When called with more than one scalar argument the first two
     arguments are taken as the number of rows and columns and any
     further arguments specify additional matrix dimensions.

     The optional argument CLASS specifies the return type and may be
     either "double" or "single".

     See also: *note e: XREFe, *note I: XREFI.

 -- : I
 -- : I (N)
 -- : I (N, M)
 -- : I (N, M, K, ...)
 -- : I (..., CLASS)
     Return a scalar, matrix, or N-dimensional array whose elements are
     all equal to the pure imaginary unit, defined as ‘sqrt (-1)’.

     I, and its equivalents i, j, and J, are functions so any of the
     names may be reused for other purposes (such as i for a counter
     variable).

     When called with no arguments, return a scalar with the value i.

     When called with a single argument, return a square matrix with the
     dimension specified.

     When called with more than one scalar argument the first two
     arguments are taken as the number of rows and columns and any
     further arguments specify additional matrix dimensions.

     The optional argument CLASS specifies the return type and may be
     either "double" or "single".

     See also: *note e: XREFe, *note pi: XREFpi, *note log: XREFlog,
     *note exp: XREFexp.

 -- : Inf
 -- : Inf (N)
 -- : Inf (N, M)
 -- : Inf (N, M, K, ...)
 -- : Inf (..., CLASS)
     Return a scalar, matrix or N-dimensional array whose elements are
     all equal to the IEEE representation for positive infinity.

     Infinity is produced when results are too large to be represented
     using the IEEE floating point format for numbers.  Two common
     examples which produce infinity are division by zero and overflow.

          [ 1/0 e^800 ]
          ⇒ Inf   Inf

     When called with no arguments, return a scalar with the value
     ‘Inf’.

     When called with a single argument, return a square matrix with the
     dimension specified.

     When called with more than one scalar argument the first two
     arguments are taken as the number of rows and columns and any
     further arguments specify additional matrix dimensions.

     The optional argument CLASS specifies the return type and may be
     either "double" or "single".

     See also: *note isinf: XREFisinf, *note NaN: XREFNaN.

 -- : NaN
 -- : NaN (N)
 -- : NaN (N, M)
 -- : NaN (N, M, K, ...)
 -- : NaN (..., CLASS)
     Return a scalar, matrix, or N-dimensional array whose elements are
     all equal to the IEEE symbol NaN (Not a Number).

     NaN is the result of operations which do not produce a well defined
     numerical result.  Common operations which produce a NaN are
     arithmetic with infinity (Inf - Inf), zero divided by zero (0/0),
     and any operation involving another NaN value (5 + NaN).

     Note that NaN always compares not equal to NaN (NaN != NaN). This
     behavior is specified by the IEEE standard for floating point
     arithmetic.  To find NaN values, use the ‘isnan’ function.

     When called with no arguments, return a scalar with the value
     ‘NaN’.

     When called with a single argument, return a square matrix with the
     dimension specified.

     When called with more than one scalar argument the first two
     arguments are taken as the number of rows and columns and any
     further arguments specify additional matrix dimensions.

     The optional argument CLASS specifies the return type and may be
     either "double" or "single".

     See also: *note isnan: XREFisnan, *note Inf: XREFInf.

 -- : eps
 -- : eps (X)
 -- : eps (N, M)
 -- : eps (N, M, K, ...)
 -- : eps (..., CLASS)
     Return a scalar, matrix or N-dimensional array whose elements are
     all eps, the machine precision.

     More precisely, ‘eps’ is the relative spacing between any two
     adjacent numbers in the machine’s floating point system.  This
     number is obviously system dependent.  On machines that support
     IEEE floating point arithmetic, ‘eps’ is approximately 2.2204e-16
     for double precision and 1.1921e-07 for single precision.

     When called with no arguments, return a scalar with the value ‘eps
     (1.0)’.

     Given a single argument X, return the distance between X and the
     next largest value.

     When called with more than one argument the first two arguments are
     taken as the number of rows and columns and any further arguments
     specify additional matrix dimensions.  The optional argument CLASS
     specifies the return type and may be either "double" or "single".

     See also: *note realmax: XREFrealmax, *note realmin: XREFrealmin,
     *note intmax: XREFintmax, *note flintmax: XREFflintmax.

 -- : realmax
 -- : realmax (N)
 -- : realmax (N, M)
 -- : realmax (N, M, K, ...)
 -- : realmax (..., CLASS)
     Return a scalar, matrix, or N-dimensional array whose elements are
     all equal to the largest floating point number that is
     representable.

     The actual value is system dependent.  On machines that support
     IEEE floating point arithmetic, ‘realmax’ is approximately
     1.7977e+308 for double precision and 3.4028e+38 for single
     precision.

     When called with no arguments, return a scalar with the value
     ‘realmax ("double")’.

     When called with a single argument, return a square matrix with the
     dimension specified.

     When called with more than one scalar argument the first two
     arguments are taken as the number of rows and columns and any
     further arguments specify additional matrix dimensions.

     The optional argument CLASS specifies the return type and may be
     either "double" or "single".

     See also: *note realmin: XREFrealmin, *note intmax: XREFintmax,
     *note flintmax: XREFflintmax, *note eps: XREFeps.

 -- : realmin
 -- : realmin (N)
 -- : realmin (N, M)
 -- : realmin (N, M, K, ...)
 -- : realmin (..., CLASS)
     Return a scalar, matrix, or N-dimensional array whose elements are
     all equal to the smallest normalized floating point number that is
     representable.

     The actual value is system dependent.  On machines that support
     IEEE floating point arithmetic, ‘realmin’ is approximately
     2.2251e-308 for double precision and 1.1755e-38 for single
     precision.

     When called with no arguments, return a scalar with the value
     ‘realmin ("double")’.

     When called with a single argument, return a square matrix with the
     dimension specified.

     When called with more than one scalar argument the first two
     arguments are taken as the number of rows and columns and any
     further arguments specify additional matrix dimensions.

     The optional argument CLASS specifies the return type and may be
     either "double" or "single".

     See also: *note realmax: XREFrealmax, *note intmin: XREFintmin,
     *note eps: XREFeps.


File: octave.info,  Node: Linear Algebra,  Next: Vectorization and Faster Code Execution,  Prev: Arithmetic,  Up: Top

18 Linear Algebra
*****************

This chapter documents the linear algebra functions provided in Octave.
Reference material for many of these functions may be found in Golub and
Van Loan, ‘Matrix Computations, 2nd Ed.’, Johns Hopkins, 1989, and in
the ‘LAPACK Users’ Guide’, SIAM, 1992.  The ‘LAPACK Users’ Guide’ is
available at: ‘http://www.netlib.org/lapack/lug/’

   A common text for engineering courses is G. Strang, ‘Linear Algebra
and Its Applications, 4th Edition’.  It has become a widespread
reference for linear algebra.  An alternative is P. Lax ‘Linear Algebra
and Its Applications’, and also is a good choice.  It claims to be
suitable for high school students with substantial mathematical
interests as well as first-year undergraduates.

* Menu:

* Techniques Used for Linear Algebra::
* Basic Matrix Functions::
* Matrix Factorizations::
* Functions of a Matrix::
* Specialized Solvers::


File: octave.info,  Node: Techniques Used for Linear Algebra,  Next: Basic Matrix Functions,  Up: Linear Algebra

18.1 Techniques Used for Linear Algebra
=======================================

Octave includes a polymorphic solver that selects an appropriate matrix
factorization depending on the properties of the matrix itself.
Generally, the cost of determining the matrix type is small relative to
the cost of factorizing the matrix itself.  In any case the matrix type
is cached once it is calculated so that it is not re-determined each
time it is used in a linear equation.

   The selection tree for how the linear equation is solved or a matrix
inverse is formed is given by:

  1. If the matrix is upper or lower triangular sparse use a forward or
     backward substitution using the LAPACK xTRTRS function, and goto 4.

  2. If the matrix is square, Hermitian with a real positive diagonal,
     attempt Cholesky factorization using the LAPACK xPOTRF function.

  3. If the Cholesky factorization failed or the matrix is not Hermitian
     with a real positive diagonal, and the matrix is square, factorize
     using the LAPACK xGETRF function.

  4. If the matrix is not square, or any of the previous solvers flags a
     singular or near singular matrix, find a least squares solution
     using the LAPACK xGELSD function.

   The user can force the type of the matrix with the ‘matrix_type’
function.  This overcomes the cost of discovering the type of the
matrix.  However, it should be noted that identifying the type of the
matrix incorrectly will lead to unpredictable results, and so
‘matrix_type’ should be used with care.

   It should be noted that the test for whether a matrix is a candidate
for Cholesky factorization, performed above, and by the ‘matrix_type’
function, does not make certain that the matrix is Hermitian.  However,
the attempt to factorize the matrix will quickly detect a non-Hermitian
matrix.


File: octave.info,  Node: Basic Matrix Functions,  Next: Matrix Factorizations,  Prev: Techniques Used for Linear Algebra,  Up: Linear Algebra

18.2 Basic Matrix Functions
===========================

 -- : AA = balance (A)
 -- : AA = balance (A, OPT)
 -- : [DD, AA] = balance (A, OPT)
 -- : [D, P, AA] = balance (A, OPT)
 -- : [CC, DD, AA, BB] = balance (A, B, OPT)

     Balance the matrix A to reduce numerical errors in future
     calculations.

     Compute ‘AA = DD \ A * DD’ in which AA is a matrix whose row and
     column norms are roughly equal in magnitude, and ‘DD = P * D’, in
     which P is a permutation matrix and D is a diagonal matrix of
     powers of two.  This allows the equilibration to be computed
     without round-off.  Results of eigenvalue calculation are typically
     improved by balancing first.

     If two output values are requested, ‘balance’ returns the diagonal
     D and the permutation P separately as vectors.  In this case, ‘DD =
     eye(n)(:,P) * diag (D)’, where n is the matrix size.

     If four output values are requested, compute ‘AA = CC*A*DD’ and ‘BB
     = CC*B*DD’, in which AA and BB have nonzero elements of
     approximately the same magnitude and CC and DD are permuted
     diagonal matrices as in DD for the algebraic eigenvalue problem.

     The eigenvalue balancing option OPT may be one of:

     "noperm", "S"
          Scale only; do not permute.

     "noscal", "P"
          Permute only; do not scale.

     Algebraic eigenvalue balancing uses standard LAPACK routines.

     Generalized eigenvalue problem balancing uses Ward’s algorithm
     (SIAM Journal on Scientific and Statistical Computing, 1981).

 -- : BW = bandwidth (A, TYPE)
 -- : [LOWER, UPPER] = bandwidth (A)
     Compute the bandwidth of A.

     The TYPE argument is the string "lower" for the lower bandwidth and
     "upper" for the upper bandwidth.  If no TYPE is specified return
     both the lower and upper bandwidth of A.

     The lower/upper bandwidth of a matrix is the number of
     subdiagonals/superdiagonals with nonzero entries.

     See also: *note isbanded: XREFisbanded, *note isdiag: XREFisdiag,
     *note istril: XREFistril, *note istriu: XREFistriu.

 -- : cond (A)
 -- : cond (A, P)
     Compute the P-norm condition number of a matrix with respect to
     inversion.

     ‘cond (A)’ is defined as ‘norm (A, P) * norm (inv (A), P)’.

     By default, ‘P = 2’ is used which implies a (relatively slow)
     singular value decomposition.  Other possible selections are ‘P =
     1, Inf, "fro"’ which are generally faster.  See ‘norm’ for a full
     discussion of possible P values.

     The condition number of a matrix quantifies the sensitivity of the
     matrix inversion operation when small changes are made to matrix
     elements.  Ideally the condition number will be close to 1.  When
     the number is large this indicates small changes (such as underflow
     or round-off error) will produce large changes in the resulting
     output.  In such cases the solution results from numerical
     computing are not likely to be accurate.

     See also: *note condest: XREFcondest, *note rcond: XREFrcond, *note
     condeig: XREFcondeig, *note norm: XREFnorm, *note svd: XREFsvd.

 -- : C = condeig (A)
 -- : [V, LAMBDA, C] = condeig (A)
     Compute condition numbers of a matrix with respect to eigenvalues.

     The condition numbers are the reciprocals of the cosines of the
     angles between the left and right eigenvectors; Large values
     indicate that the matrix has multiple distinct eigenvalues.

     The input A must be a square numeric matrix.

     The outputs are:

        • C is a vector of condition numbers for the eigenvalues of A.

        • V is the matrix of right eigenvectors of A.  The result is
          equivalent to calling ‘[V, LAMBDA] = eig (A)’.

        • LAMBDA is the diagonal matrix of eigenvalues of A.  The result
          is equivalent to calling ‘[V, LAMBDA] = eig (A)’.

     Example

          a = [1, 2; 3, 4];
          c = condeig (a)
          ⇒ [1.0150; 1.0150]

     See also: *note eig: XREFeig, *note cond: XREFcond, *note balance:
     XREFbalance.

 -- : det (A)
 -- : [D, RCOND] = det (A)
     Compute the determinant of A.

     Return an estimate of the reciprocal condition number if requested.

     Programming Notes: Routines from LAPACK are used for full matrices
     and code from UMFPACK is used for sparse matrices.

     The determinant should not be used to check a matrix for
     singularity.  For that, use any of the condition number functions:
     ‘cond’, ‘condest’, ‘rcond’.

     See also: *note cond: XREFcond, *note condest: XREFcondest, *note
     rcond: XREFrcond.

 -- : LAMBDA = eig (A)
 -- : LAMBDA = eig (A, B)
 -- : [V, LAMBDA] = eig (A)
 -- : [V, LAMBDA] = eig (A, B)
 -- : [V, LAMBDA, W] = eig (A)
 -- : [V, LAMBDA, W] = eig (A, B)
 -- : [...] = eig (A, BALANCEOPTION)
 -- : [...] = eig (A, B, ALGORITHM)
 -- : [...] = eig (..., EIGVALOPTION)
     Compute the right eigenvalues(V) and optionally the
     eigenvectors(lambda) and the left eigenvalues(W) of a matrix or a
     pair of matrices.

     The flag BALANCEOPTION can be one of:

     "balance"
          Preliminary balancing is on.  (default)

     "nobalance"
          Disables preliminary balancing.

     The flag EIGVALOPTION can be one of:

     "matrix"
          Return the eigenvalues in a diagonal matrix.  (default if 2 or
          3 outputs are specified)

     "vector"
          Return the eigenvalues in a column vector.  (default if 1
          output is specified, e.g.  LAMBDA = eig (A))

     The flag ALGORITHM can be one of:

     "chol"
          Uses the Cholesky factorization of B. (default if A is
          symmetric (Hermitian) and B is symmetric (Hermitian) positive
          definite)

     "qz"
          Uses the QZ algorithm.  (When A or B are not symmetric always
          the QZ algorithm will be used)

                            no flag           chol              qz
     -----------------------------------------------------------------------------
     both are symmetric     "chol"            "chol"            "qz"
     at least one is not    "qz"              "qz"              "qz"
     symmetric

     The eigenvalues returned by ‘eig’ are not ordered.

     See also: *note eigs: XREFeigs, *note svd: XREFsvd.

 -- : G = givens (X, Y)
 -- : [C, S] = givens (X, Y)
     Compute the Givens rotation matrix G.

     The Givens matrix is a 2 by 2 orthogonal matrix

     ‘G = [C S; -S' C]’

     such that

     ‘G [X; Y] = [*; 0]’

     with X and Y scalars.

     If two output arguments are requested, return the factors C and S
     rather than the Givens rotation matrix.

     For example:

          givens (1, 1)
             ⇒   0.70711   0.70711
                 -0.70711   0.70711

     See also: *note planerot: XREFplanerot.

 -- : S = gsvd (A, B)
 -- : [U, V, X, C, S, R] = gsvd (A, B)
     Compute the generalized singular value decomposition of (A, B):

          u' * a * x = [I 0; 0 c] * [0 r]
          v' * b * x = [0 s; 0 0] * [0 r]
          c * c + s * s = eye (columns (a))
          I and 0 are padding matrices of suitable size
          r is upper triangular

     The function ‘gsvd’ normally returns the vector of generalized
     singular values diag (r) ./ diag (s).  If asked for five return
     values, it computes U, V, and X. With a sixth output argument, it
     also returns r, The common upper triangular right term.  Other
     authors, like S. Van Huffel, define this transformation as the
     simultaneous diagonalization of the input matrices, this can be
     achieved by multiplying x by the inverse of [I 0; 0 r].

     For example,

          gsvd (hilb (3), [1 2 3; 3 2 1])

          ⇒
            0.1055705
            0.0031759

     and

          [u, v, c, s, x, r] = gsvd (hilb (3), [1 2 3; 3 2 1])
          ⇒

          u =

            -0.965609   0.240893   0.097825
            -0.241402  -0.690927  -0.681429
            -0.096561  -0.681609   0.725317

          v =

            -0.41974   0.90765
            -0.90765  -0.41974

          x =

             0.408248   0.902199   0.139179
            -0.816497   0.429063  -0.386314
             0.408248  -0.044073  -0.911806

          c =

             0.10499   0.00000
             0.00000   0.00318

          s =
             0.99447   0.00000
             0.00000   0.99999

          r =
            -0.14093  -1.24345   0.43737
             0.00000  -3.90043   2.57818
             0.00000   0.00000  -2.52599


     The code is a wrapper to the corresponding LAPACK dggsvd and zggsvd
     routines.

 -- : [G, Y] = planerot (X)
     Given a two-element column vector, return the 2 by 2 orthogonal
     matrix G such that ‘Y = G * X’ and ‘Y(2) = 0’.

     See also: *note givens: XREFgivens.

 -- : X = inv (A)
 -- : [X, RCOND] = inv (A)
     Compute the inverse of the square matrix A.

     Return an estimate of the reciprocal condition number if requested,
     otherwise warn of an ill-conditioned matrix if the reciprocal
     condition number is small.

     In general it is best to avoid calculating the inverse of a matrix
     directly.  For example, it is both faster and more accurate to
     solve systems of equations (A*x = b) with ‘Y = A \ b’, rather than
     ‘Y = inv (A) * b’.

     If called with a sparse matrix, then in general X will be a full
     matrix requiring significantly more storage.  Avoid forming the
     inverse of a sparse matrix if possible.

     See also: *note ldivide: XREFldivide, *note rdivide: XREFrdivide.

 -- : X = linsolve (A, B)
 -- : X = linsolve (A, B, OPTS)
 -- : [X, R] = linsolve (...)
     Solve the linear system ‘A*x = b’.

     With no options, this function is equivalent to the left division
     operator (‘x = A \ b’) or the matrix-left-divide function
     (‘x = mldivide (A, b)’).

     Octave ordinarily examines the properties of the matrix A and
     chooses a solver that best matches the matrix.  By passing a
     structure OPTS to ‘linsolve’ you can inform Octave directly about
     the matrix A.  In this case Octave will skip the matrix examination
     and proceed directly to solving the linear system.

     *Warning:* If the matrix A does not have the properties listed in
     the OPTS structure then the result will not be accurate AND no
     warning will be given.  When in doubt, let Octave examine the
     matrix and choose the appropriate solver as this step takes little
     time and the result is cached so that it is only done once per
     linear system.

     Possible OPTS fields (set value to true/false):

     LT
          A is lower triangular

     UT
          A is upper triangular

     UHESS
          A is upper Hessenberg (currently makes no difference)

     SYM
          A is symmetric or complex Hermitian (currently makes no
          difference)

     POSDEF
          A is positive definite

     RECT
          A is general rectangular (currently makes no difference)

     TRANSA
          Solve ‘A'*x = b’ by ‘transpose (A) \ b’

     The optional second output R is the inverse condition number of A
     (zero if matrix is singular).

     See also: *note mldivide: XREFmldivide, *note matrix_type:
     XREFmatrix_type, *note rcond: XREFrcond.

 -- : TYPE = matrix_type (A)
 -- : TYPE = matrix_type (A, "nocompute")
 -- : A = matrix_type (A, TYPE)
 -- : A = matrix_type (A, "upper", PERM)
 -- : A = matrix_type (A, "lower", PERM)
 -- : A = matrix_type (A, "banded", NL, NU)
     Identify the matrix type or mark a matrix as a particular type.

     This allows more rapid solutions of linear equations involving A to
     be performed.

     Called with a single argument, ‘matrix_type’ returns the type of
     the matrix and caches it for future use.

     Called with more than one argument, ‘matrix_type’ allows the type
     of the matrix to be defined.

     If the option "nocompute" is given, the function will not attempt
     to guess the type if it is still unknown.  This is useful for
     debugging purposes.

     The possible matrix types depend on whether the matrix is full or
     sparse, and can be one of the following

     "unknown"
          Remove any previously cached matrix type, and mark type as
          unknown.

     "full"
          Mark the matrix as full.

     "positive definite"
          Probable full positive definite matrix.

     "diagonal"
          Diagonal matrix.  (Sparse matrices only)

     "permuted diagonal"
          Permuted Diagonal matrix.  The permutation does not need to be
          specifically indicated, as the structure of the matrix
          explicitly gives this.  (Sparse matrices only)

     "upper"
          Upper triangular.  If the optional third argument PERM is
          given, the matrix is assumed to be a permuted upper triangular
          with the permutations defined by the vector PERM.

     "lower"
          Lower triangular.  If the optional third argument PERM is
          given, the matrix is assumed to be a permuted lower triangular
          with the permutations defined by the vector PERM.

     "banded"
     "banded positive definite"
          Banded matrix with the band size of NL below the diagonal and
          NU above it.  If NL and NU are 1, then the matrix is
          tridiagonal and treated with specialized code.  In addition
          the matrix can be marked as probably a positive definite.
          (Sparse matrices only)

     "singular"
          The matrix is assumed to be singular and will be treated with
          a minimum norm solution.

     Note that the matrix type will be discovered automatically on the
     first attempt to solve a linear equation involving A.  Therefore
     ‘matrix_type’ is only useful to give Octave hints of the matrix
     type.  Incorrectly defining the matrix type will result in
     incorrect results from solutions of linear equations; it is
     entirely *the responsibility of the user* to correctly identify the
     matrix type.

     Also, the test for positive definiteness is a low-cost test for a
     Hermitian matrix with a real positive diagonal.  This does not
     guarantee that the matrix is positive definite, but only that it is
     a probable candidate.  When such a matrix is factorized, a
     Cholesky factorization is first attempted, and if that fails the
     matrix is then treated with an LU factorization.  Once the matrix
     has been factorized, ‘matrix_type’ will return the correct
     classification of the matrix.

 -- : norm (A)
 -- : norm (A, P)
 -- : norm (A, P, OPT)
     Compute the p-norm of the matrix A.

     If the second argument is missing, ‘p = 2’ is assumed.

     If A is a matrix (or sparse matrix):

     P = ‘1’
          1-norm, the largest column sum of the absolute values of A.

     P = ‘2’
          Largest singular value of A.

     P = ‘Inf’ or "inf"
          Infinity norm, the largest row sum of the absolute values of
          A.

     P = "fro"
          Frobenius norm of A, ‘sqrt (sum (diag (A' * A)))’.

     other P, ‘P > 1’
          maximum ‘norm (A*x, p)’ such that ‘norm (x, p) == 1’

     If A is a vector or a scalar:

     P = ‘Inf’ or "inf"
          ‘max (abs (A))’.

     P = ‘-Inf’
          ‘min (abs (A))’.

     P = "fro"
          Frobenius norm of A, ‘sqrt (sumsq (abs (A)))’.

     P = 0
          Hamming norm - the number of nonzero elements.

     other P, ‘P > 1’
          p-norm of A, ‘(sum (abs (A) .^ P)) ^ (1/P)’.

     other P ‘P < 1’
          the p-pseudonorm defined as above.

     If OPT is the value "rows", treat each row as a vector and compute
     its norm.  The result is returned as a column vector.  Similarly,
     if OPT is "columns" or "cols" then compute the norms of each column
     and return a row vector.

     See also: *note cond: XREFcond, *note svd: XREFsvd.

 -- : null (A)
 -- : null (A, TOL)
     Return an orthonormal basis of the null space of A.

     The dimension of the null space is taken as the number of singular
     values of A not greater than TOL.  If the argument TOL is missing,
     it is computed as

          max (size (A)) * max (svd (A)) * eps

     See also: *note orth: XREForth.

 -- : orth (A)
 -- : orth (A, TOL)
     Return an orthonormal basis of the range space of A.

     The dimension of the range space is taken as the number of singular
     values of A greater than TOL.  If the argument TOL is missing, it
     is computed as

          max (size (A)) * max (svd (A)) * eps

     See also: *note null: XREFnull.

 -- : [Y, H] = mgorth (X, V)
     Orthogonalize a given column vector X with respect to a set of
     orthonormal vectors comprising the columns of V using the modified
     Gram-Schmidt method.

     On exit, Y is a unit vector such that:

            norm (Y) = 1
            V' * Y = 0
            X = [V, Y]*H'

 -- : pinv (X)
 -- : pinv (X, TOL)
     Return the pseudoinverse of X.

     Singular values less than TOL are ignored.

     If the second argument is omitted, it is taken to be

          tol = max (size (X)) * sigma_max (X) * eps,

     where ‘sigma_max (X)’ is the maximal singular value of X.

 -- : rank (A)
 -- : rank (A, TOL)
     Compute the rank of matrix A, using the singular value
     decomposition.

     The rank is taken to be the number of singular values of A that are
     greater than the specified tolerance TOL.  If the second argument
     is omitted, it is taken to be

          tol = max (size (A)) * sigma(1) * eps;

     where ‘eps’ is machine precision and ‘sigma(1)’ is the largest
     singular value of A.

     The rank of a matrix is the number of linearly independent rows or
     columns and determines how many particular solutions exist to a
     system of equations.  Use ‘null’ for finding the remaining
     homogenous solutions.

     Example:

          x = [1 2 3
               4 5 6
               7 8 9];
          rank (x)
            ⇒ 2

     The number of linearly independent rows is only 2 because the final
     row is a linear combination of -1*row1 + 2*row2.

     See also: *note null: XREFnull, *note sprank: XREFsprank, *note
     svd: XREFsvd.

 -- : C = rcond (A)
     Compute the 1-norm estimate of the reciprocal condition number as
     returned by LAPACK.

     If the matrix is well-conditioned then C will be near 1 and if the
     matrix is poorly conditioned it will be close to 0.

     The matrix A must not be sparse.  If the matrix is sparse then
     ‘condest (A)’ or ‘rcond (full (A))’ should be used instead.

     See also: *note cond: XREFcond, *note condest: XREFcondest.

 -- : trace (A)
     Compute the trace of A, the sum of the elements along the main
     diagonal.

     The implementation is straightforward: ‘sum (diag (A))’.

     See also: *note eig: XREFeig.

 -- : rref (A)
 -- : rref (A, TOL)
 -- : [R, K] = rref (...)
     Return the reduced row echelon form of A.

     TOL defaults to ‘eps * max (size (A)) * norm (A, inf)’.

     The optional return argument K contains the vector of "bound
     variables", which are those columns on which elimination has been
     performed.


File: octave.info,  Node: Matrix Factorizations,  Next: Functions of a Matrix,  Prev: Basic Matrix Functions,  Up: Linear Algebra

18.3 Matrix Factorizations
==========================

 -- : R = chol (A)
 -- : [R, P] = chol (A)
 -- : [R, P, Q] = chol (A)
 -- : [R, P, Q] = chol (A, "vector")
 -- : [L, ...] = chol (..., "lower")
 -- : [R, ...] = chol (..., "upper")
     Compute the upper Cholesky factor, R, of the real symmetric or
     complex Hermitian positive definite matrix A.

     The upper Cholesky factor R is computed by using the upper
     triangular part of matrix A and is defined by

          R' * R = A.

     Calling ‘chol’ using the optional "upper" flag has the same
     behavior.  In contrast, using the optional "lower" flag, ‘chol’
     returns the lower triangular factorization, computed by using the
     lower triangular part of matrix A, such that

          L * L' = A.

     Called with one output argument ‘chol’ fails if matrix A is not
     positive definite.  Note that if matrix A is not real symmetric or
     complex Hermitian then the lower triangular part is considered to
     be the (complex conjugate) transpose of the upper triangular part,
     or vice versa, given the "lower" flag.

     Called with two or more output arguments P flags whether the matrix
     A was positive definite and ‘chol’ does not fail.  A zero value of
     P indicates that matrix A is positive definite and R gives the
     factorization.  Otherwise, P will have a positive value.

     If called with three output arguments matrix A must be sparse and a
     sparsity preserving row/column permutation is applied to matrix A
     prior to the factorization.  That is R is the factorization of
     ‘A(Q,Q)’ such that

          R' * R = Q' * A * Q.

     The sparsity preserving permutation is generally returned as a
     matrix.  However, given the optional flag "vector", Q will be
     returned as a vector such that

          R' * R = A(Q, Q).

     In general the lower triangular factorization is significantly
     faster for sparse matrices.

     See also: *note hess: XREFhess, *note lu: XREFlu, *note qr: XREFqr,
     *note qz: XREFqz, *note schur: XREFschur, *note svd: XREFsvd, *note
     ichol: XREFichol, *note cholinv: XREFcholinv, *note chol2inv:
     XREFchol2inv, *note cholupdate: XREFcholupdate, *note cholinsert:
     XREFcholinsert, *note choldelete: XREFcholdelete, *note cholshift:
     XREFcholshift.

 -- : cholinv (A)
     Compute the inverse of the symmetric positive definite matrix A
     using the Cholesky factorization.

     See also: *note chol: XREFchol, *note chol2inv: XREFchol2inv, *note
     inv: XREFinv.

 -- : chol2inv (U)
     Invert a symmetric, positive definite square matrix from its
     Cholesky decomposition, U.

     Note that U should be an upper-triangular matrix with positive
     diagonal elements.  ‘chol2inv (U)’ provides ‘inv (U'*U)’ but it is
     much faster than using ‘inv’.

     See also: *note chol: XREFchol, *note cholinv: XREFcholinv, *note
     inv: XREFinv.

 -- : [R1, INFO] = cholupdate (R, U, OP)
     Update or downdate a Cholesky factorization.

     Given an upper triangular matrix R and a column vector U, attempt
     to determine another upper triangular matrix R1 such that

        • R1’*R1 = R’*R + U*U’ if OP is "+"

        • R1’*R1 = R’*R - U*U’ if OP is "-"

     If OP is "-", INFO is set to

        • 0 if the downdate was successful,

        • 1 if R’*R - U*U’ is not positive definite,

        • 2 if R is singular.

     If INFO is not present, an error message is printed in cases 1 and
     2.

     See also: *note chol: XREFchol, *note cholinsert: XREFcholinsert,
     *note choldelete: XREFcholdelete, *note cholshift: XREFcholshift.

 -- : R1 = cholinsert (R, J, U)
 -- : [R1, INFO] = cholinsert (R, J, U)
     Given a Cholesky factorization of a real symmetric or complex
     Hermitian positive definite matrix A = R’*R, R upper triangular,
     return the Cholesky factorization of A1, where A1(p,p) = A,
     A1(:,j) = A1(j,:)’ = u and p = [1:j-1,j+1:n+1].  u(j) should be
     positive.

     On return, INFO is set to

        • 0 if the insertion was successful,

        • 1 if A1 is not positive definite,

        • 2 if R is singular.

     If INFO is not present, an error message is printed in cases 1 and
     2.

     See also: *note chol: XREFchol, *note cholupdate: XREFcholupdate,
     *note choldelete: XREFcholdelete, *note cholshift: XREFcholshift.

 -- : R1 = choldelete (R, J)
     Given a Cholesky factorization of a real symmetric or complex
     Hermitian positive definite matrix A = R’*R, R upper triangular,
     return the Cholesky factorization of A(p,p), where
     p = [1:j-1,j+1:n+1].

     See also: *note chol: XREFchol, *note cholupdate: XREFcholupdate,
     *note cholinsert: XREFcholinsert, *note cholshift: XREFcholshift.

 -- : R1 = cholshift (R, I, J)
     Given a Cholesky factorization of a real symmetric or complex
     Hermitian positive definite matrix A = R’*R, R upper triangular,
     return the Cholesky factorization of A(p,p), where p is the
     permutation
     ‘p = [1:i-1, shift(i:j, 1), j+1:n]’ if I < J
     or
     ‘p = [1:j-1, shift(j:i,-1), i+1:n]’ if J < I.

     See also: *note chol: XREFchol, *note cholupdate: XREFcholupdate,
     *note cholinsert: XREFcholinsert, *note choldelete: XREFcholdelete.

 -- : H = hess (A)
 -- : [P, H] = hess (A)
     Compute the Hessenberg decomposition of the matrix A.

     The Hessenberg decomposition is ‘P * H * P' = A’ where P is a
     square unitary matrix (‘P' * P = I’, using complex-conjugate
     transposition) and H is upper Hessenberg (‘H(i, j) = 0 forall i >
     j+1)’.

     The Hessenberg decomposition is usually used as the first step in
     an eigenvalue computation, but has other applications as well (see
     Golub, Nash, and Van Loan, IEEE Transactions on Automatic Control,
     1979).

     See also: *note eig: XREFeig, *note chol: XREFchol, *note lu:
     XREFlu, *note qr: XREFqr, *note qz: XREFqz, *note schur: XREFschur,
     *note svd: XREFsvd.

 -- : [L, U] = lu (A)
 -- : [L, U, P] = lu (A)
 -- : [L, U, P, Q] = lu (S)
 -- : [L, U, P, Q, R] = lu (S)
 -- : [...] = lu (S, THRES)
 -- : Y = lu (...)
 -- : [...] = lu (..., "vector")
     Compute the LU decomposition of A.

     If A is full then subroutines from LAPACK are used, and if A is
     sparse then UMFPACK is used.

     The result is returned in a permuted form, according to the
     optional return value P.  For example, given the matrix ‘a = [1, 2;
     3, 4]’,

          [l, u, p] = lu (A)

     returns

          l =

            1.00000  0.00000
            0.33333  1.00000

          u =

            3.00000  4.00000
            0.00000  0.66667

          p =

            0  1
            1  0

     The matrix is not required to be square.

     When called with two or three output arguments and a sparse input
     matrix, ‘lu’ does not attempt to perform sparsity preserving column
     permutations.  Called with a fourth output argument, the sparsity
     preserving column transformation Q is returned, such that ‘P * A *
     Q = L * U’.

     Called with a fifth output argument and a sparse input matrix, ‘lu’
     attempts to use a scaling factor R on the input matrix such that ‘P
     * (R \ A) * Q = L * U’.  This typically leads to a sparser and more
     stable factorization.

     An additional input argument THRES, that defines the pivoting
     threshold can be given.  THRES can be a scalar, in which case it
     defines the UMFPACK pivoting tolerance for both symmetric and
     unsymmetric cases.  If THRES is a 2-element vector, then the first
     element defines the pivoting tolerance for the unsymmetric UMFPACK
     pivoting strategy and the second for the symmetric strategy.  By
     default, the values defined by ‘spparms’ are used ([0.1, 0.001]).

     Given the string argument "vector", ‘lu’ returns the values of P
     and Q as vector values, such that for full matrix, ‘A(P,:) = L *
     U’, and ‘R(P,:) * A(:,Q) = L * U’.

     With two output arguments, returns the permuted forms of the upper
     and lower triangular matrices, such that ‘A = L * U’.  With one
     output argument Y, then the matrix returned by the LAPACK routines
     is returned.  If the input matrix is sparse then the matrix L is
     embedded into U to give a return value similar to the full case.
     For both full and sparse matrices, ‘lu’ loses the permutation
     information.

     See also: *note luupdate: XREFluupdate, *note ilu: XREFilu, *note
     chol: XREFchol, *note hess: XREFhess, *note qr: XREFqr, *note qz:
     XREFqz, *note schur: XREFschur, *note svd: XREFsvd.

 -- : [L, U] = luupdate (L, U, X, Y)
 -- : [L, U, P] = luupdate (L, U, P, X, Y)
     Given an LU factorization of a real or complex matrix A = L*U,
     L lower unit trapezoidal and U upper trapezoidal, return the
     LU factorization of A + X*Y.’, where X and Y are column vectors
     (rank-1 update) or matrices with equal number of columns (rank-k
     update).

     Optionally, row-pivoted updating can be used by supplying a row
     permutation (pivoting) matrix P; in that case, an updated
     permutation matrix is returned.  Note that if L, U, P is a pivoted
     LU factorization as obtained by ‘lu’:

          [L, U, P] = lu (A);

     then a factorization of A+X*Y.’ can be obtained either as

          [L1, U1] = lu (L, U, P*X, Y)

     or

          [L1, U1, P1] = lu (L, U, P, X, Y)

     The first form uses the unpivoted algorithm, which is faster, but
     less stable.  The second form uses a slower pivoted algorithm,
     which is more stable.

     The matrix case is done as a sequence of rank-1 updates; thus, for
     large enough k, it will be both faster and more accurate to
     recompute the factorization from scratch.

     See also: *note lu: XREFlu, *note cholupdate: XREFcholupdate, *note
     qrupdate: XREFqrupdate.

 -- : [Q, R] = qr (A)
 -- : [Q, R, P] = qr (A) # non-sparse A
 -- : X = qr (A)
 -- : R = qr (A) # sparse A
 -- : [C, R] = qr (A, B)
 -- : [...] = qr (..., 0)
 -- : [...] = qr (..., 'vector')
 -- : [...] = qr (..., 'matrix')
     Compute the QR factorization of A, using standard LAPACK
     subroutines.  The QR factorization is ‘Q * R = A’ where Q is an
     orthogonal matrix and R is upper triangular.

     For example, given the matrix ‘A = [1, 2; 3, 4]’,

          [Q, R] = qr (A)

     returns

          Q =

            -0.31623  -0.94868
            -0.94868   0.31623

          R =

            -3.16228  -4.42719
             0.00000  -0.63246

     The ‘qr’ factorization has applications in the solution of least
     squares problems

          min norm(A x - b)

     for overdetermined systems of equations (i.e., A is a tall, thin
     matrix).

     If only a single return value is requested, then it is either R if
     A is sparse, or X such that ‘R = triu (X)’ if A is full.  (Note:
     Unlike most commands, the single return value is not the first
     return value when multiple are requested.)

     If the matrix A is full, the permuted QR factorization ‘[Q, R, P] =
     qr (A)’ forms the QR factorization such that the diagonal entries
     of R are decreasing in magnitude order.  For example, given the
     matrix ‘a = [1, 2; 3, 4]’,

          [Q, R, P] = qr (A)

     returns

          Q =

            -0.44721  -0.89443
            -0.89443   0.44721

          R =

            -4.47214  -3.13050
             0.00000   0.44721

          P =

             0  1
             1  0

     The permuted ‘qr’ factorization ‘[Q, R, P] = qr (A)’ factorization
     allows the construction of an orthogonal basis of ‘span (A)’.

     If the matrix A is sparse, then the sparse QR factorization of A is
     computed using CSPARSE.  As the matrix Q is in general a full
     matrix, it is recommended to request only one return value, which
     is the Q-less factorization R of A, such that ‘R = chol (A' * A)’.

     If an additional matrix B is supplied and two return values are
     requested, then ‘qr’ returns C, where ‘C = Q' * B’.  This allows
     the least squares approximation of ‘A \ B’ to be calculated as

          [C, R] = qr (A, B)
          x = R \ C

     If the final argument is the scalar 0 and the number of rows is
     larger than the number of columns, then an "economy" factorization
     is returned, omitting zeroes of R and the corresponding columns of
     Q.  That is, R will have only ‘size (A,1)’ rows.  In this case, P
     is a vector rather than a matrix.

     If the final argument is the string "vector" then P is a
     permutation vector instead of a permutation matrix.

     See also: *note chol: XREFchol, *note hess: XREFhess, *note lu:
     XREFlu, *note qz: XREFqz, *note schur: XREFschur, *note svd:
     XREFsvd, *note qrupdate: XREFqrupdate, *note qrinsert:
     XREFqrinsert, *note qrdelete: XREFqrdelete, *note qrshift:
     XREFqrshift.

 -- : [Q1, R1] = qrupdate (Q, R, U, V)
     Given a QR factorization of a real or complex matrix A = Q*R,
     Q unitary and R upper trapezoidal, return the QR factorization of
     A + U*V’, where U and V are column vectors (rank-1 update) or
     matrices with equal number of columns (rank-k update).  Notice that
     the latter case is done as a sequence of rank-1 updates; thus, for
     k large enough, it will be both faster and more accurate to
     recompute the factorization from scratch.

     The QR factorization supplied may be either full (Q is square) or
     economized (R is square).

     See also: *note qr: XREFqr, *note qrinsert: XREFqrinsert, *note
     qrdelete: XREFqrdelete, *note qrshift: XREFqrshift.

 -- : [Q1, R1] = qrinsert (Q, R, J, X, ORIENT)
     Given a QR factorization of a real or complex matrix A = Q*R,
     Q unitary and R upper trapezoidal, return the QR factorization of
     [A(:,1:j-1) x A(:,j:n)], where U is a column vector to be inserted
     into A (if ORIENT is "col"), or the QR factorization of
     [A(1:j-1,:);x;A(:,j:n)], where X is a row vector to be inserted
     into A (if ORIENT is "row").

     The default value of ORIENT is "col".  If ORIENT is "col", U may be
     a matrix and J an index vector resulting in the QR factorization of
     a matrix B such that B(:,J) gives U and B(:,J) = [] gives A.
     Notice that the latter case is done as a sequence of k insertions;
     thus, for k large enough, it will be both faster and more accurate
     to recompute the factorization from scratch.

     If ORIENT is "col", the QR factorization supplied may be either
     full (Q is square) or economized (R is square).

     If ORIENT is "row", full factorization is needed.

     See also: *note qr: XREFqr, *note qrupdate: XREFqrupdate, *note
     qrdelete: XREFqrdelete, *note qrshift: XREFqrshift.

 -- : [Q1, R1] = qrdelete (Q, R, J, ORIENT)
     Given a QR factorization of a real or complex matrix A = Q*R,
     Q unitary and R upper trapezoidal, return the QR factorization of
     [A(:,1:j-1), U, A(:,j:n)], where U is a column vector to be
     inserted into A (if ORIENT is "col"), or the QR factorization of
     [A(1:j-1,:);X;A(:,j:n)], where X is a row ORIENT is "row").  The
     default value of ORIENT is "col".

     If ORIENT is "col", J may be an index vector resulting in the
     QR factorization of a matrix B such that A(:,J) = [] gives B.
     Notice that the latter case is done as a sequence of k deletions;
     thus, for k large enough, it will be both faster and more accurate
     to recompute the factorization from scratch.

     If ORIENT is "col", the QR factorization supplied may be either
     full (Q is square) or economized (R is square).

     If ORIENT is "row", full factorization is needed.

     See also: *note qr: XREFqr, *note qrupdate: XREFqrupdate, *note
     qrinsert: XREFqrinsert, *note qrshift: XREFqrshift.

 -- : [Q1, R1] = qrshift (Q, R, I, J)
     Given a QR factorization of a real or complex matrix A = Q*R,
     Q unitary and R upper trapezoidal, return the QR factorization of
     A(:,p), where p is the permutation
     ‘p = [1:i-1, shift(i:j, 1), j+1:n]’ if I < J
     or
     ‘p = [1:j-1, shift(j:i,-1), i+1:n]’ if J < I.

     See also: *note qr: XREFqr, *note qrupdate: XREFqrupdate, *note
     qrinsert: XREFqrinsert, *note qrdelete: XREFqrdelete.

 -- : LAMBDA = qz (A, B)
 -- : LAMBDA = qz (A, B, OPT)
     QZ decomposition of the generalized eigenvalue problem (A x = s B
     x).

     There are three ways to call this function:
       1. ‘LAMBDA = qz (A, B)’

          Computes the generalized eigenvalues LAMBDA of (A - s B).

       2. ‘[AA, BB, Q, Z, V, W, LAMBDA] = qz (A, B)’

          Computes QZ decomposition, generalized eigenvectors, and
          generalized eigenvalues of (A - s B)


               A * V = B * V * diag (LAMBDA)
               W' * A = diag (LAMBDA) * W' * B
               AA = Q * A * Z, BB = Q * B * Z


          with Q and Z orthogonal (unitary)= I

       3. ‘[AA,BB,Z{, LAMBDA}] = qz (A, B, OPT)’

          As in form [2], but allows ordering of generalized eigenpairs
          for, e.g., solution of discrete time algebraic Riccati
          equations.  Form 3 is not available for complex matrices, and
          does not compute the generalized eigenvectors V, W, nor the
          orthogonal matrix Q.

          OPT
               for ordering eigenvalues of the GEP pencil.  The leading
               block of the revised pencil contains all eigenvalues that
               satisfy:

               "N"
                    = unordered (default)

               "S"
                    = small: leading block has all |lambda| ≤ 1

               "B"
                    = big: leading block has all |lambda| ≥ 1

               "-"
                    = negative real part: leading block has all
                    eigenvalues in the open left half-plane

               "+"
                    = non-negative real part: leading block has all
                    eigenvalues in the closed right half-plane

     Note: ‘qz’ performs permutation balancing, but not scaling (*note
     XREFbalance::).  The order of output arguments was selected for
     compatibility with MATLAB.

     See also: *note eig: XREFeig, *note balance: XREFbalance, *note lu:
     XREFlu, *note chol: XREFchol, *note hess: XREFhess, *note qr:
     XREFqr, *note qzhess: XREFqzhess, *note schur: XREFschur, *note
     svd: XREFsvd.

 -- : [AA, BB, Q, Z] = qzhess (A, B)
     Compute the Hessenberg-triangular decomposition of the matrix
     pencil ‘(A, B)’, returning ‘AA = Q * A * Z’, ‘BB = Q * B * Z’, with
     Q and Z orthogonal.

     For example:

          [aa, bb, q, z] = qzhess ([1, 2; 3, 4], [5, 6; 7, 8])
               ⇒ aa = [ -3.02244, -4.41741;  0.92998,  0.69749 ]
               ⇒ bb = [ -8.60233, -9.99730;  0.00000, -0.23250 ]
               ⇒  q = [ -0.58124, -0.81373; -0.81373,  0.58124 ]
               ⇒  z = [ 1, 0; 0, 1 ]

     The Hessenberg-triangular decomposition is the first step in Moler
     and Stewart’s QZ decomposition algorithm.

     Algorithm taken from Golub and Van Loan, ‘Matrix Computations, 2nd
     edition’.

     See also: *note lu: XREFlu, *note chol: XREFchol, *note hess:
     XREFhess, *note qr: XREFqr, *note qz: XREFqz, *note schur:
     XREFschur, *note svd: XREFsvd.

 -- : S = schur (A)
 -- : S = schur (A, "real")
 -- : S = schur (A, "complex")
 -- : S = schur (A, OPT)
 -- : [U, S] = schur (...)
     Compute the Schur decomposition of A.

     The Schur decomposition is defined as

          S = U' * A * U

     where U is a unitary matrix (‘U'* U’ is identity) and S is upper
     triangular.  The eigenvalues of A (and S) are the diagonal elements
     of S.  If the matrix A is real, then the real Schur decomposition
     is computed, in which the matrix U is orthogonal and S is block
     upper triangular with blocks of size at most ‘2 x 2’ along the
     diagonal.  The diagonal elements of S (or the eigenvalues of the ‘2
     x 2’ blocks, when appropriate) are the eigenvalues of A and S.

     The default for real matrices is a real Schur decomposition.  A
     complex decomposition may be forced by passing the flag "complex".

     The eigenvalues are optionally ordered along the diagonal according
     to the value of OPT.  ‘OPT = "a"’ indicates that all eigenvalues
     with negative real parts should be moved to the leading block of S
     (used in ‘are’), ‘OPT = "d"’ indicates that all eigenvalues with
     magnitude less than one should be moved to the leading block of S
     (used in ‘dare’), and ‘OPT = "u"’, the default, indicates that no
     ordering of eigenvalues should occur.  The leading K columns of U
     always span the A-invariant subspace corresponding to the K leading
     eigenvalues of S.

     The Schur decomposition is used to compute eigenvalues of a square
     matrix, and has applications in the solution of algebraic Riccati
     equations in control (see ‘are’ and ‘dare’).

     See also: *note rsf2csf: XREFrsf2csf, *note ordschur: XREFordschur,
     *note lu: XREFlu, *note chol: XREFchol, *note hess: XREFhess, *note
     qr: XREFqr, *note qz: XREFqz, *note svd: XREFsvd.

 -- : [U, T] = rsf2csf (UR, TR)
     Convert a real, upper quasi-triangular Schur form TR to a complex,
     upper triangular Schur form T.

     Note that the following relations hold:

     UR * TR * UR’ = U * T * U’ and ‘U' * U’ is the identity matrix I.

     Note also that U and T are not unique.

     See also: *note schur: XREFschur.

 -- : [UR, SR] = ordschur (U, S, SELECT)
     Reorders the real Schur factorization (U,S) obtained with the
     ‘schur’ function, so that selected eigenvalues appear in the upper
     left diagonal blocks of the quasi triangular Schur matrix.

     The logical vector SELECT specifies the selected eigenvalues as
     they appear along S’s diagonal.

     For example, given the matrix ‘A = [1, 2; 3, 4]’, and its Schur
     decomposition

          [U, S] = schur (A)

     which returns

          U =

            -0.82456  -0.56577
             0.56577  -0.82456

          S =

            -0.37228  -1.00000
             0.00000   5.37228


     It is possible to reorder the decomposition so that the positive
     eigenvalue is in the upper left corner, by doing:

          [U, S] = ordschur (U, S, [0,1])

     See also: *note schur: XREFschur.

 -- : ANGLE = subspace (A, B)
     Determine the largest principal angle between two subspaces spanned
     by the columns of matrices A and B.

 -- : S = svd (A)
 -- : [U, S, V] = svd (A)
 -- : [U, S, V] = svd (A, ECON)
     Compute the singular value decomposition of A

          A = U*S*V'

     The function ‘svd’ normally returns only the vector of singular
     values.  When called with three return values, it computes U, S,
     and V.  For example,

          svd (hilb (3))

     returns

          ans =

            1.4083189
            0.1223271
            0.0026873

     and

          [u, s, v] = svd (hilb (3))

     returns

          u =

            -0.82704   0.54745   0.12766
            -0.45986  -0.52829  -0.71375
            -0.32330  -0.64901   0.68867

          s =

            1.40832  0.00000  0.00000
            0.00000  0.12233  0.00000
            0.00000  0.00000  0.00269

          v =

            -0.82704   0.54745   0.12766
            -0.45986  -0.52829  -0.71375
            -0.32330  -0.64901   0.68867

     If given a second argument, ‘svd’ returns an economy-sized
     decomposition, eliminating the unnecessary rows or columns of U or
     V.

     See also: *note svd_driver: XREFsvd_driver, *note svds: XREFsvds,
     *note eig: XREFeig, *note lu: XREFlu, *note chol: XREFchol, *note
     hess: XREFhess, *note qr: XREFqr, *note qz: XREFqz.

 -- : VAL = svd_driver ()
 -- : OLD_VAL = svd_driver (NEW_VAL)
 -- : svd_driver (NEW_VAL, "local")
     Query or set the underlying LAPACK driver used by ‘svd’.

     Currently recognized values are "gesvd" and "gesdd".  The default
     is "gesvd".

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note svd: XREFsvd.

 -- : [HOUSV, BETA, ZER] = housh (X, J, Z)
     Compute Householder reflection vector HOUSV to reflect X to be the
     j-th column of identity, i.e.,

          (I - beta*housv*housv')x =  norm (x)*e(j) if x(j) < 0,
          (I - beta*housv*housv')x = -norm (x)*e(j) if x(j) >= 0

     Inputs

     X
          vector

     J
          index into vector

     Z
          threshold for zero (usually should be the number 0)

     Outputs (see Golub and Van Loan):

     BETA
          If beta = 0, then no reflection need be applied (zer set to 0)

     HOUSV
          householder vector

 -- : [U, H, NU] = krylov (A, V, K, EPS1, PFLG)
     Construct an orthogonal basis U of block Krylov subspace

          [v a*v a^2*v ... a^(k+1)*v]

     using Householder reflections to guard against loss of
     orthogonality.

     If V is a vector, then H contains the Hessenberg matrix such that
     a*u == u*h+rk*ek’, in which ‘rk = a*u(:,k)-u*h(:,k)’, and ek’ is
     the vector ‘[0, 0, ..., 1]’ of length ‘k’.  Otherwise, H is
     meaningless.

     If V is a vector and K is greater than ‘length (A) - 1’, then H
     contains the Hessenberg matrix such that ‘a*u == u*h’.

     The value of NU is the dimension of the span of the Krylov subspace
     (based on EPS1).

     If B is a vector and K is greater than M-1, then H contains the
     Hessenberg decomposition of A.

     The optional parameter EPS1 is the threshold for zero.  The default
     value is 1e-12.

     If the optional parameter PFLG is nonzero, row pivoting is used to
     improve numerical behavior.  The default value is 0.

     Reference: A. Hodel, P. Misra, ‘Partial Pivoting in the Computation
     of Krylov Subspaces of Large Sparse Systems’, Proceedings of the
     42nd IEEE Conference on Decision and Control, December 2003.

