 ArrayTools - Maple Programming Help

ArrayTools

 Alias
 provide different view of rectangular Matrix, Vector, or Array

 Calling Sequence Alias(A, offset, bounds, orient, order, datatype, options)

Parameters

 A - rectangular storage Matrix, Vector, or Array of any data type and ordering offset - (optional) integer; offset into data for creation of new rtable bounds - (optional) list of integers or ranges of integers; bounds for the new alias orient - (optional) orientation of the output Vector alias ('row' or 'column'). This parameter can be specified only if the output is a Vector order - (optional) ordering of the output alias ('C_order' or 'Fortran_order') datatype - (optional) hardware datatype of the output alias options - other options

Options

 • offset = nonnegint
 The offset option is a nonnegative integer value that specifies the offset into the input at which the output alias begins. For example, an offset of 4 allows creation of an alias of the last 6 elements of a 10 element Vector as a 6 element Vector.
 • bounds = integer or list
 The bounds option is a list of integers or integer ranges that specify the Matrix, Vector, or Array bounds of the output alias. If bounds is a single integer value, then a Vector alias is returned. If bounds is a list of two integer values, then a Matrix alias is returned. If there are more than two values, or any one of the bounds is specified as a range $a..b$ (where $a$, $b$ are both integers with $a), then the output is an Array alias.
 In the case where bounds is a single element list with an integer value, the output will be a Vector alias, and the orientation can be set by passing orient with a value of either 'row' or 'column'.
 The combination of the new bounds and the offset must not extend past the data storage for the input rtable. If it does, an error is returned.
 • order = one of C_order or Fortran_order.
 • The order option describes the order of the output alias. The default value is chosen to be the same order as used for the input rtable.
 Note: No underlying data is changed by this operation, so this does not provide an order conversion, but rather a new view on the existing unchanged data. For more information on ordering, see the rtable order help page.
 • datatype = one of float, float, complex, integer, integer, integer, or integer.
 The datatype option describes the hardware datatype of the output alias. The default value is the same datatype as the input, A.
 Note: No underlying data is changed by this operation, so this does not provide data conversion.  Aliasing an 8 element integer byte array to a float array will result in a single element float array with its value given by the hardware byte pattern in the original array. As such the user must be aware of potential endianness issues.
 As hinted at above, different datatypes require different numbers of bytes of storage.  The specified dimensions designate the input selection area, and the output alias' size will be adjusted accordingly.  For example aliasing the first two elements of a complex array will result in an integer array with 16 elements, a integer array with 8 elements, a float array with 2 elements, etc.
 • readonly = true or false
 This option specifies whether the created alias is readonly. If the original rtable is readonly, then specifying this option to be false results in an error.
 Important: This option must be explicitly stated when aliasing to an rtable with an indexing function, as the alias will not have the indexing function, so it is possible to corrupt the indexed nature of the original rtable by assigning to an alias created with readonly=false.

Description

 • The Alias command provides a different view of the same data for an existing Matrix, Vector, or Array. The input Matrix, Vector, or Array must have rectangular (dense) storage.
 • Alias does not change the underlying data of the input rtable object. Instead, Alias casts it to another rtable object with the same data but a different description that can be specified through options. In contrast to ArrayTools[Reshape], Alias does not create a copy of the underlying data, but instead creates and returns a new rtable object which references the same block of internal data as the input. As such, changes to the contents of the view also affect the contents of the original input rtable, and vice-versa. A limited form of casting to a different data type is also available from ArrayTools[ComplexAsFloat].
 Note: If the original rtable has an indexing function, then you must create the alias as readonly. More information on this is provided for the readonly option.
 • If the original Matrix, Vector, or Array has been unassigned, it will still exist in the attributes of the view, but changing the data will only affect the current view and other views defined on the same rtable.
 Important: Use this function with caution. If you remove the table reference from the attributes and unassign the original input object, accessing or changing the data in the view will crash Maple. If a persistent and permanent copy of the data is desired, then use copy, ArrayTools[Copy], or ArrayTools[Reshape] instead.
 • This function is part of the ArrayTools package, so it can be used in the short form Alias(..) only after executing the command with(ArrayTools).  However, it can always be accessed through the long form of the command by using ArrayTools[Alias](..).

Examples

 > $\mathrm{with}\left(\mathrm{ArrayTools}\right):$

Viewing a 10 element Vector as a 2 x 5 Matrix - shown for both orderings

 > $V≔\mathrm{Vector}\left[\mathrm{row}\right]\left(10,i↦i\right)$
 ${V}{≔}\left[\begin{array}{cccccccccc}{1}& {2}& {3}& {4}& {5}& {6}& {7}& {8}& {9}& {10}\end{array}\right]$ (1)
 > $\mathrm{Af}≔\mathrm{Alias}\left(V,\left[2,5\right],\mathrm{Fortran_order}\right)$
 ${\mathrm{Af}}{≔}\left[\begin{array}{ccccc}{1}& {3}& {5}& {7}& {9}\\ {2}& {4}& {6}& {8}& {10}\end{array}\right]$ (2)
 > $\mathrm{Ac}≔\mathrm{Alias}\left(V,\left[2,5\right],\mathrm{C_order}\right)$
 ${\mathrm{Ac}}{≔}\left[\begin{array}{ccccc}{1}& {2}& {3}& {4}& {5}\\ {6}& {7}& {8}& {9}& {10}\end{array}\right]$ (3)

Viewing the last 6 elements of a 10 element Vector as a 6 element Array

 > $\mathrm{A6}≔\mathrm{Alias}\left(V,4,\left[1..6\right]\right)$
 ${\mathrm{A6}}{≔}\left[\begin{array}{cccccc}{5}& {6}& {7}& {8}& {9}& {10}\end{array}\right]$ (4)
 > $\mathrm{type}\left(\mathrm{A6},\mathrm{Array}\right)$
 ${\mathrm{true}}$ (5)

Viewing a 3 x 4 Matrix as a 12 element row Vector

 > $A≔\mathrm{Matrix}\left(3,4,\left(i,j\right)↦10\cdot i+j,\mathrm{order}=\mathrm{C_order}\right)$
 ${A}{≔}\left[\begin{array}{cccc}{11}& {12}& {13}& {14}\\ {21}& {22}& {23}& {24}\\ {31}& {32}& {33}& {34}\end{array}\right]$ (6)
 > $V≔\mathrm{Alias}\left(A,\left[12\right],\mathrm{row}\right)$
 ${V}{≔}\left[\begin{array}{cccccccccccc}{11}& {12}& {13}& {14}& {21}& {22}& {23}& {24}& {31}& {32}& {33}& {34}\end{array}\right]$ (7)
 > $\mathrm{op}\left(0,V\right)$
 ${{\mathrm{Vector}}}_{{\mathrm{row}}}$ (8)

or as an Array

 > $V≔\mathrm{Alias}\left(A,\left[1..12\right]\right)$
 ${V}{≔}\left[\begin{array}{cccccccccccc}{11}& {12}& {13}& {14}& {21}& {22}& {23}& {24}& {31}& {32}& {33}& {34}\end{array}\right]$ (9)
 > $\mathrm{op}\left(0,V\right)$
 ${\mathrm{Array}}$ (10)

The data itself does not move, but specification of different bounds can make it appear to. Conversion of the Matrix A to a 2-D Array with indices starting at zero

 > $\mathrm{Ar}≔\mathrm{Alias}\left(A,\left[0..2,0..3\right]\right)$
  (11)
 > $A\left[1,1\right],\mathrm{Ar}\left[0,0\right]$
 ${11}{,}{11}$ (12)
 > $A\left[2,4\right],\mathrm{Ar}\left[1,3\right]$
 ${24}{,}{24}$ (13)
 > $A\left[3,2\right],\mathrm{Ar}\left[2,1\right]$
 ${32}{,}{32}$ (14)

Note that the data is shared between the input rtable and its view.

 > $A≔\mathrm{Matrix}\left(3,4,\left(i,j\right)↦10\cdot i+j,\mathrm{order}=\mathrm{C_order}\right)$
 ${A}{≔}\left[\begin{array}{cccc}{11}& {12}& {13}& {14}\\ {21}& {22}& {23}& {24}\\ {31}& {32}& {33}& {34}\end{array}\right]$ (15)
 > $V≔\mathrm{Alias}\left(A,\left[12\right],\mathrm{row}\right)$
 ${V}{≔}\left[\begin{array}{cccccccccccc}{11}& {12}& {13}& {14}& {21}& {22}& {23}& {24}& {31}& {32}& {33}& {34}\end{array}\right]$ (16)
 > $A\left[1,1\right]≔0:$$A\left[2,3\right]≔0:$
 > $V$
 $\left[\begin{array}{cccccccccccc}{0}& {12}& {13}& {14}& {21}& {22}& {0}& {24}& {31}& {32}& {33}& {34}\end{array}\right]$ (17)

Obtain a transpose that changes with the original Matrix.

 > $A≔\mathrm{Matrix}\left(3,4,\left(i,j\right)↦10\cdot i+j,\mathrm{order}=\mathrm{C_order}\right)$
 ${A}{≔}\left[\begin{array}{cccc}{11}& {12}& {13}& {14}\\ {21}& {22}& {23}& {24}\\ {31}& {32}& {33}& {34}\end{array}\right]$ (18)
 > $\mathrm{At}≔\mathrm{Alias}\left(A,\left[4,3\right],\mathrm{Fortran_order}\right)$
 ${\mathrm{At}}{≔}\left[\begin{array}{ccc}{11}& {21}& {31}\\ {12}& {22}& {32}\\ {13}& {23}& {33}\\ {14}& {24}& {34}\end{array}\right]$ (19)
 > $A·\mathrm{At}$
 $\left[\begin{array}{ccc}{630}& {1130}& {1630}\\ {1130}& {2030}& {2930}\\ {1630}& {2930}& {4230}\end{array}\right]$ (20)
 > $A\left[1,1\right]≔0:$$A\left[1,2\right]≔0:$$A\left[1,3\right]≔0:$$A\left[1,4\right]≔1:$
 > $A,\mathrm{At}$
 $\left[\begin{array}{cccc}{0}& {0}& {0}& {1}\\ {21}& {22}& {23}& {24}\\ {31}& {32}& {33}& {34}\end{array}\right]{,}\left[\begin{array}{ccc}{0}& {21}& {31}\\ {0}& {22}& {32}\\ {0}& {23}& {33}\\ {1}& {24}& {34}\end{array}\right]$ (21)
 > $A·\mathrm{At}$
 $\left[\begin{array}{ccc}{1}& {24}& {34}\\ {24}& {2030}& {2930}\\ {34}& {2930}& {4230}\end{array}\right]$ (22)

Another example using the order option. A has the default Fortran order.

 > $A≔\mathrm{Matrix}\left(4,4,\left(i,j\right)↦4\cdot j-4+i\right)$
 ${A}{≔}\left[\begin{array}{cccc}{1}& {5}& {9}& {13}\\ {2}& {6}& {10}& {14}\\ {3}& {7}& {11}& {15}\\ {4}& {8}& {12}& {16}\end{array}\right]$ (23)
 > $\mathrm{Alias}\left(A,\mathrm{C_order}\right)$
 $\left[\begin{array}{cccc}{1}& {2}& {3}& {4}\\ {5}& {6}& {7}& {8}\\ {9}& {10}& {11}& {12}\\ {13}& {14}& {15}& {16}\end{array}\right]$ (24)
 > $B≔\mathrm{Array}\left(\left[3.14,-2.22\right],\mathrm{datatype}=\mathrm{float}\left[8\right]\right)$
 ${B}{≔}\left[\begin{array}{cc}{3.14000000000000}& {-2.22000000000000}\end{array}\right]$ (25)
 > $\mathrm{writebytes}\left("alias_test",B\right)$
 ${16}$ (26)
 > $\mathrm{fclose}\left("alias_test"\right)$
 > $A≔\mathrm{Array}\left(1..16,\mathrm{datatype}=\mathrm{integer}\left[1\right]\right)$
 ${A}{≔}\left[\begin{array}{cccccccccccccccc}{0}& {0}& {0}& {0}& {0}& {0}& {0}& {0}& {0}& {0}& {0}& {0}& {0}& {0}& {0}& {0}\end{array}\right]$ (27)
 > $\mathrm{readbytes}\left("alias_test",A\right)$
 $\left[\begin{array}{cccccccccccccccc}{31}& {-123}& {-21}& {81}& {-72}& {30}& {9}& {64}& {-61}& {-11}& {40}& {92}& {-113}& {-62}& {1}& {-64}\end{array}\right]$ (28)
 > $\mathrm{ArrayTools}:-\mathrm{Alias}\left(A,\mathrm{float}\left[8\right]\right)$
 $\left[\begin{array}{cc}{3.14000000000000}& {-2.22000000000000}\end{array}\right]$ (29)
 > $\mathrm{ArrayTools}:-\mathrm{Alias}\left(A,\mathrm{complex}\left[8\right]\right)$
 $\left[\begin{array}{c}{3.14000000000000}{-}{2.22000000000000}{}{I}\end{array}\right]$ (30)

Note that convert(..., bytes) gives unsigned integer results that need to be scaled to fit into an integer array.  You may also need to reorder the elements to get the correct endianness.

 > $\mathrm{data}≔\mathrm{convert}\left(3.14,\mathrm{bytes}\right)$
 ${\mathrm{data}}{≔}\left[{64}{,}{9}{,}{30}{,}{184}{,}{81}{,}{235}{,}{133}{,}{31}\right]$ (31)
 > $A≔\mathrm{Array}\left(\mathrm{map}\left(x↦\mathrm{if}\left(127
 ${A}{≔}\left[\begin{array}{cccccccc}{64}& {9}& {30}& {-72}& {81}& {-21}& {-123}& {31}\end{array}\right]$ (32)
 > $B≔\mathrm{ArrayTools}:-\mathrm{FlipDimension}\left(A,2\right)$
 ${B}{≔}\left[\begin{array}{cccccccc}{31}& {-123}& {-21}& {81}& {-72}& {30}& {9}& {64}\end{array}\right]$ (33)
 > $\mathrm{Alias}\left(B,\mathrm{float}\left[8\right]\right)$
 $\left[\begin{array}{c}{3.14000000000000}\end{array}\right]$ (34)

Compatibility

 • The readonly option was introduced in Maple 16.