rtable  construct an rtable

Calling Sequence


rtable(indfcns, dims, init, opts)


Parameters


indfcns



(optional) procedure(s); indexing function(s)

dims



(optional) range(s) of integers; dimension(s)

init



(optional) Maple procedure, function, table, list, rtable, set of equations, expression of type algebraic; initial values for the rtable

opts



(optional) equations of the form keyword = value; specifies additional properties of the rtable





Description


•

The rtable(..) function is the low level routine used by Maple to build an Array, a Matrix or a Vector. The user level commands for constructing these objects are Array(..), Matrix(..), and Vector(..), respectively. See their help pages for more information.

•

Each of the parameters in the calling sequence is optional. If no parameters are provided, an empty 0dimensional Array is returned.


If dims and init are not specified, or if only a scalar value is specified for init, a 0dimensional Array containing a single element is constructed.

•

The following sections describe permissible values for each parameter if it is included in the calling sequence.


Indexing Function(s)


•

Indexing functions are used to index into an rtable to retrieve or store a value. An rtable has zero or more indexing functions, which are specified by name when the rtable is constructed. The name of an indexing function is always of the form "index/indfcn". When specifying an indexing function indfcn in the calling sequence, only the indfcn part of the name is specified.


Note: If the initializer (see below) is an existing rtable, the indexing functions are not inherited.

•

The indexing function can be builtin or userdefined. For more information regarding indexing functions, see rtable_indexfcn.



Dimension(s)


•

The number of dimensions of an rtable can range from 0 to 63. Each of the dimensions dims in the calling sequence must be specified as a range of integers.



Initializer



The init parameter specifies the initial values of the rtable in one of the following formats.

•

list of values (in the case of a multidimensional rtable, nested lists are used)

•

set of equations of the form (indices) = value

•

initializer function (procedure)

•

function call of the following form:

–

random(range, density) For each stored element, produces a random integer value in the specified range, with probability density of being nonzero. (See below for details.)

–

frandom(range, density) For each stored element, produces a random floating point value in the specified range, with probability density of being nonzero. (See below for details.)

Note:These functions are available for use only with the rtable constructor. They do not work with the Array, Matrix, or Vector constructor commands. See LinearAlgebra[RandomMatrix] or LinearAlgebra[RandomVector] for other methods.

If the initial values are specified as a list of values or an existing rtable, the number of dimensions of the initial values must match the bounds (if they are specified). If dimensions are not specified, the new rtable inherits the same dimensions from the list or rtable. A list initializer that has variable length sublists has its dimensions derived from the first element only. That is, [[1,2],[3]] creates a 2x2 rtable, but [[1],[2,3]] creates a 2x1 rtable. By explicitly specifying the dimensions, you can force both cases to output a 2x2 (or other size) rtable with the given fill value (or 0) inserted where no element exists in the initializer.


If the initial values are specified as a procedure, table, set of equations, or either of random() or frandom(), the dimensions must be specified. For table and set of equations initializers, the indices of the initializers must be within those dimensions.


If a function is specified, that function is called for each member of a set of indices, determined by the indexing function. The function must return a value for the specified element of the rtable.


Each initial value can be any Maple expression, but this expression must be able to be evaluated to a value of the datatype of the rtable (see Options below). For hardware floatingpoint rtables, this must be a hardware floatingpoint number, or one of the special expressions representing undefined or +infinity. For hardware integer rtables, the expressions must be able to be evaluated to a machine integer. Failure to evaluate to the datatype generates an event.


The list form of initializer for a two or more dimensional rtable is specified in rowmajor order unless the transpose option (see below) is specified.


If the bounds are determined from the list form of the initializer, then the bounds of each dimension are determined from the first object in that dimension. For example, for a 2dimensional rtable, the number of rows is determined by the number of sublists in the main list. The number of columns is determined by the number of elements in the first sublist, and so on for higher dimensioned rtables. If transpose is specified, then dimension determination starts with the last dimension (that is, the number of columns is determined by the number of sublists in the main list, and so on).


For both random or frandom, the range and density parameters are optional. If you do not specify these parameters, the default range is all possible integers for random and $0..1$ for frandom, and the default density is $1$ for both. The range is a range of the form $a..b$, where $a$ and $b$ are of type integer for random, and type float for frandom. The density is a probability between $0$ and $1$. The probability of a zero element increases if zero is within the specified range.


If there are too few initializer values for a dimension, the remainder of that dimension is filled with an appropriate default for the type of rtable (either an appropriate zero, the value specified by the fill option (see below), or a value determined by the indexing functions). If there are too many initializer values, an exception is raised.


A 0dimensional rtable can be initialized by specifying a literal value (i.e. a 0level nesting of lists). For example, rtable(2) creates a 0dimensional rtable containing the single element, 2. This form can only be used if the value is of a type that cannot be confused with one of the other forms of initializer. If it is desired to initialize a 0dimensional rtable with a more complex type, the fill option or setofequations form should be used (for example, rtable(fill=[2, 3])) would create a 0dimensional rtable containing the single value [2, 3]).


An rtable with scalar storage (see Options below) is initialized in the usual way. Any form of initializer works, although the most efficient method would be a set which contains one equation, or by using the fill parameter.



Option(s)


•

The opts parameter is used to specify one or more additional properties of the rtable. If a property is included in the calling sequence, it must be an equation of the form keyword = value. The permissible properties are described in the following sections.


Specifies the datatype of the rtable elements, and can be one of integer[n], float[n], double, complex[n], or any Maple type specification (such as is accepted by type() or ::).


For integer[n], n can be 1, 2, 4, or 8, indicating the number of bytes per integer. For float[n], n can be 4 or 8. The double datatype is the same as the float[8] datatype. For complex[n], the only allowable value of n is currently 8. The default datatype is the Maple type anything.


Note: When the initializer is an existing rtable, and datatype = value is not specified, the datatype is inherited from the initializer.


The datatypes boolean[n] and truefalse[n] are equivalent to datatype integer[n]. This is simply a convenience notation usually used in conjunction with external code. See define_external,types for more information.


Specifies the type of the constructed rtable object. Allowable values are Array, Matrix, Vector[row], and Vector[column].


The default subtype is Array.


Note: When the initializer is an existing rtable, and subtype=value is not specified, the subtype is inherited from the initializer.


Specifies the storage of the rtable. Permissible values are:


sparse



sparse[upper]



sparse[lower]



empty



scalar



diagonal



band[b1,b2]



rectangular



triangular[upper]



triangular[upper,strict]



Hessenberg[upper]



triangular[lower]



triangular[lower,strict]



Hessenberg[lower]





The default value of storage is determined by the last indexing function specified. If the initializer is an rtable and no storage option is included in the calling sequence, then the resulting rtable has sparse storage if the initializer has any kind of sparse storage; otherwise, the resulting rtable has rectangular shape.


Specifies the internal ordering of the structure. Permissible values are C_order and Fortran_order. The default order is Fortran_order.


Note: When the initializer is an existing rtable, and order is not specified, the order is inherited from the initializer.


Specifies whether the rtable is mutable. Permissible values are true or false. If readonly=true is included in the calling sequence (or equivalently, just readonly), it specifies that the rtable is immutable, in which case any attempt to modify an rtable element raises an exception.


Note: When the initializer is an existing rtable, readonly is not inherited from the initializer, since a common use for copying an rtable is to create a writable version of a readonly one.


Specifies the attributes with which the rtable is created. Anything that is a valid argument to setattribute can appear as attribute values. The default is to have no attributes.


Note: When the initializer is an existing rtable, and attributes are not specified, the attributes are inherited from the initializer.


If transpose or transpose=true is included in the calling sequence, it specifies that the initializer is to be transposed before filling in the rtable (or determining its dimensions if no dimensions are specified). In other words, the initializer is assumed to be in columnmajor order.


Specifies the default value with which unspecified rtable elements are filled. This value must meet the same evaluation requirements as initializer values.


Note: The fill value is only used to fill those elements of the rtable that are unspecified in spite of the indexing function. For instance, the fill value is not used to fill the lower triangle of an upper triangular Matrix. For a sparse rtable, the fill value is always ignored.


Note: The transpose and fill options are only constructor options. They are not returned as part of the result of an op(1, ...) call (the last operand of the rtable, its options).



Other Information


•

After creation, it is possible to change the entries and some of the properties of the rtable. See rtable assignment and rtable options for more information.

•

For additional information on accessing elements or groups of elements of an rtable, see rtable indexing.

•

Only small rtables are displayed inline in Maple. A small rtable is defined as a 1 or 2dimensional object whose dimensions are in the range 1..25 (TTY version of Maple) or the range 1..10 (GUI version of Maple). Any rtable whose dimension(s) are larger than this size is displayed by using a placeholder. For information on how to view the contents of a placeholder, see structuredview.


You can display larger rtables inline by using the interface(rtablesize=value) command, where value is an integer that represents the upper bound of the dimension range.


To change the environment so that Maple always displays rtables inline, include the interface(rtablesize=infinity) command in a Maple initialization file (see maple).




Compatibility


•

The datatype option was updated in Maple 2015.



Thread Safety


•

The rtable command is threadsafe as of Maple 15.



Examples


>

$\mathrm{rtable}\left(1..3\,\mathrm{subtype}\={\mathrm{Vector}}_{\mathrm{column}}\,\mathrm{readonly}\right)$

$\left[\begin{array}{r}{0}\\ {0}\\ {0}\end{array}\right]$
 (1) 
>

$\mathrm{rtable}\left(1..2\,1..2\,\mathrm{frandom}\left(100..200\,0.5\right)\right)$

$\left[\begin{array}{cc}{0.}& {0.}\\ {191.337585613901922}& {0.}\end{array}\right]$
 (2) 
>

$A:=\mathrm{rtable}\left(\mathrm{symmetric}\,1..2\,1..2\,1\,\mathrm{storage}\={\mathrm{triangular}}_{\mathrm{upper}}\right)$

${A}{:=}\left[\begin{array}{rr}{1}& {1}\\ {1}& {1}\end{array}\right]$
 (3) 
${{A}}_{{2}{\,}{1}}{:=}{2}$
 (4) 
$\left[\begin{array}{rr}{1}& {2}\\ {2}& {1}\end{array}\right]$
 (5) 


See Also


Array, interface, list, maple, Matrix, procedure, rtable dimensions, rtable elements, rtable evaluation, rtable indexing functions, rtable options, rtable scan block, set, structuredview, table, type[algebraic], Vector

