hfarray  create an array of hardware floats

Calling Sequence


hfarray(bounds, list)


Parameters


bounds



(optional) sequence of ranges

list



(optional) list of initial values





Description


•

An array of hardware floatingpoint numbers (an hfarray) is a mutable, indexable, homogeneous, multidimensional structure consisting of one or more doubleprecision IEEE754 floatingpoint values. The special IEEE754 values +Infinity, Infinity, and Quiet NaN are supported.


Note: The hfarray structure was introduced in Maple V Release 5 as an intermediate measure to allow more efficient manipulation of large dense arrays of hardware floatingpoint values. In Maple 6, the hfarray structure was replaced by a generic rectangular table structure (see rtable) which allows for efficient representation of a variety of dense and sparse array formats, with elements of various hardware or Maple data types.


For backwards compatibility, the hfarray function continues to work as before, but actually creates an Array (a subtype of rtable) with dense rectangular storage, a datatype of float[8], and C ordering. This is displayed slightly differently than an hfarray, but operations that worked on hfarrays work on this new structure.

•

The result of executing the hfarray function is to create an hfarray. For example, V := hfarray(1..10) creates a one dimensional hfarray of length 10 with undefined entries (IEEE Quiet NaN, displayed as undefined). The command A := hfarray(1..m,1..n) creates a two dimensional hfarray with m rows and n columns.

•

The optional bounds consists of one or more integer ranges specifying the lower and upper bounds of each dimension of the array. If the bounds are not specified, they are determined from the initializer list, with a lower bound of 1 for each dimension. The upper and lower bounds are constrained to the size of a machine integer (2,147,483,648 to 2,147,483,647 on a 32bit architecture, and 9,223,372,036,854,775,808 to 9,223,372,036,854,775,807 on a 64bit architecture).

•

The optional list specifies the initial values of the array. In the case of a multidimensional array, nested lists are used. If the initial values are specified, the number of dimensions of the initial values must match the bounds if they were specified. Each initial value can be any Maple expression that can be evaluated to a floatingpoint number, or one of the special expressions undefined, infinity, or infinity.

•

If the bounds are determined from the initial values, then the bounds of each dimension are determined from the first object in that dimension. For example, for a two dimensional array, 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 arrays.

•

If there are too few initializer values for a dimension, the remainder of that dimension is filled with undefined (IEEE Quiet NaN). If there are too many, the rest are discarded.

•

The op function can be used to pick apart an hfarray structure. op(1,A) always yields NULL, for compatibility with regular arrays (where op(1,A) yields the indexing function, or NULL if there is none). op(2,A) yields bounds; and op(3,A) yields a nested list of the values in the array. Note that this is an expensive operation, since all the elements of the array must be converted from hardware floats to Maple software floats.

•

When executing inside evalhf, the call array(bounds) is equivalent to hfarray(bounds), except that the values are all initialized to zero instead of undefined.

•

Creating, assigning to elements, and retrieving elements of hfarrays outside the evalhf environment are inefficient operations, since conversion between hardware floats and Maple software floats is required.

•

When indexing into an hfarray (see selection), it is permitted to specify fewer indices than the number of dimensions of the hfarray. This will produce a new hfarray which is a copy of a lesserdimensional subpart of the hfarray being indexed. No conversion between hardware and Maple floats takes place in this case.

•

An hfarray can be efficiently (with no conversion to Maple floats) printed (to the session, a file, or a string) using the "%e", "%f", "%g", or "%x" formats of the printf family of functions. An hfarray can be efficiently parsed (from the session, a file, or a string) using the "%he", "%hf", "%hg", or "%hx" formats of the scanf family of functions.



Thread Safety


•

The hfarray command is threadsafe as of Maple 15.



Examples


>

$v:=\mathrm{hfarray}\left(1..4\right)\:$

>

$\mathbf{for}\phantom{\rule[0.0ex]{0.5em}{0.0ex}}i\phantom{\rule[0.0ex]{0.5em}{0.0ex}}\mathbf{to}\phantom{\rule[0.0ex]{0.5em}{0.0ex}}3\phantom{\rule[0.0ex]{0.5em}{0.0ex}}\mathbf{do}\phantom{\rule[0.0ex]{0.5em}{0.0ex}}{v}_{i}:={i}^{2}\phantom{\rule[0.0ex]{0.5em}{0.0ex}}\mathbf{end\; do}\:$$\mathrm{print}\left(v\right)$

$\left[\begin{array}{cccc}{1.}& {4.}& {9.}& {\mathrm{HFloat}}{}\left({\mathrm{undefined}}\right)\end{array}\right]$
 (1) 
If one tries to refer to an element not in the array, one gets an error:
>

$A:=\mathrm{hfarray}\left(1..2\,1..2\right)\:$

>

${A}_{1\,2}:=3.14\:$

>

${A}_{1\,1}:=\mathrm{\π}$

${{A}}_{{1}{\,}{1}}{:=}{\mathrm{\π}}$
 (3) 
>

$\mathrm{print}\left(A\right)$

$\left[\begin{array}{cc}{3.14159265358979}& {3.14000000000000}\\ {\mathrm{HFloat}}{}\left({\mathrm{undefined}}\right)& {\mathrm{HFloat}}{}\left({\mathrm{undefined}}\right)\end{array}\right]$
 (5) 
>

$\mathrm{op}\left(2\,A\right)$

${1}{..}{2}{\,}{1}{..}{2}$
 (6) 
>

$\mathrm{op}\left(3\,A\right)$

$\left\{\left({1}{\,}{1}\right){\=}{3.14159265358979}{\,}\left({1}{\,}{2}\right){\=}{3.14000000000000}{\,}\left({2}{\,}{1}\right){\=}{\mathrm{HFloat}}{}\left({\mathrm{undefined}}\right){\,}\left({2}{\,}{2}\right){\=}{\mathrm{HFloat}}{}\left({\mathrm{undefined}}\right)\right\}$
 (7) 

