Arrays
======

Maxima supports 3 array-like constructs:

  * If one tries to write to an indexed variable without creating a list first an undeclared array (also named hashed array) is created that grows dynamically and allows numbers, symbols and strings as indices:

          (%i1) a["feww"]:1;
          (%o1)                           1

          (%i2) a[qqwdqwd]:3;
          (%o2)                           3

          (%i3) a[5]:99;
          (%o3)                          99

          (%i4) a[qqwdqwd];
          (%o4)                           3

          (%i5) a[5];
          (%o5)                          99

          (%i6) a["feww"];
          (%o6)                           1

     Since lisp handles hashed arrays and memoizing functions similar to arrays many of the  functions that can be applied to arrays can be applied to them, as well.

  * Lists (see makelist allow for fast addition and removal of elements, can be created without knowing their final size.

  * Declared arrays that allow fast access to random elements at the cost that their size needs to be known at construction time. (see Performance considerations for Lists.)

Functions and Variables for Arrays
----------------------------------

 -- Function: array
     array (NAME, DIM_1, ..., DIM_N)
     array (NAME, TYPE, DIM_1, ..., DIM_N)
     array ([NAME_1, ..., NAME_M], DIM_1, ..., DIM_N)

     Creates an n-dimensional array.  n may be less than or equal to 5. The subscripts for the i'th dimension are the integers running from 0 to DIM_I.

     array (NAME, DIM_1, ..., DIM_N) creates a general array.

     array (NAME, TYPE, DIM_1, ..., DIM_N) creates an array, with elements of a specified type.  TYPE can be fixnum for integers of limited size or flonum for floating-point numbers.

     array ([NAME_1, ..., NAME_M], DIM_1, ..., DIM_N) creates m arrays, all of the same dimensions.

     See also arraymake arrayinfo and make_array

     Categories: Arrays

 -- Function: arrayapply (A, [I_1, ..., I_N])

     Evaluates A [I_1, ..., I_N], where A is an array and I_1, ..., I_N are integers.

     This is reminiscent of apply except the first argument is an array instead of a function.

     Categories: Expressions Arrays

 -- Function: arrayinfo (A)

     Returns information about the array A. The argument A may be a declared array, a hashed array a memoizing function or a subscripted function.

     For declared arrays, arrayinfo returns a list comprising the atom declared, the number of dimensions, and the size of each dimension. The elements of the array, both bound and unbound, are returned by listarray

     For undeclared arrays (hashed arrays), arrayinfo returns a list comprising the atom hashed, the number of subscripts, and the subscripts of every element which has a value. The values are returned by listarray

     For memoizing functions arrayinfo returns a list comprising the atom hashed, the number of subscripts, and any subscript values for which there are stored function values. The stored function values are returned by listarray

     For subscripted functions, arrayinfo returns a list comprising the atom hashed, the number of subscripts, and any subscript values for which there are lambda expressions. The lambda expressions are returned by listarray

     See also listarray

     Examples:

     arrayinfo and listarray applied to a declared array.

          (%i1) array (aa, 2, 3);
          (%o1)                          aa

          (%i2) aa [2, 3] : %pi;
          (%o2)                          %pi

          (%i3) aa [1, 2] : %e;
          (%o3)                          %e

          (%i4) arrayinfo (aa);
          (%o4)                 [declared, 2, [2, 3]]

          (%i5) listarray (aa);
          (%o5) [#####, #####, #####, #####, #####, #####, %e, #####,
                                                  #####, #####, #####, %pi]

     arrayinfo and listarray applied to an undeclared array (hashed array).

          (%i1) bb [FOO] : (a + b)^2;
                                             2
          (%o1)                       (b + a)

          (%i2) bb [BAR] : (c - d)^3;
                                             3
          (%o2)                       (c - d)

          (%i3) arrayinfo (bb);
          (%o3)               [hashed, 1, [BAR], [FOO]]

          (%i4) listarray (bb);
                                        3         2
          (%o4)                 [(c - d) , (b + a) ]

     arrayinfo and listarray applied to a memoizing function

          (%i1) cc [x, y] := y / x;
                                               y
          (%o1)                      cc     := -
                                       x, y    x

          (%i2) cc [u, v];
                                          v
          (%o2)                           -
                                          u

          (%i3) cc [4, z];
                                          z
          (%o3)                           -
                                          4

          (%i4) arrayinfo (cc);
          (%o4)              [hashed, 2, [4, z], [u, v]]

          (%i5) listarray (cc);
                                        z  v
          (%o5)                        [-, -]
                                        4  u

     Using arrayinfo in order to convert an undeclared array to a declared array:

          (%i1) for i:0 thru 10 do a[i]:i^2$

          (%i2) indices:map(first,rest(rest(arrayinfo(a))));
          (%o2)          [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

          (%i3) array(A,fixnum,length(indices)-1)$
          (%i4) fillarray(A,map(lambda([x],a[x]),indices))$

          (%i5) listarray(A);
          (%o5)       [0, 1, 4, 9, 16, 25, 36, 49, 64, 81, 100]

     arrayinfo and listarray applied to a subscripted function.

          (%i1) dd [x] (y) := y ^ x;
                                               x
          (%o1)                     dd (y) := y
                                      x

          (%i2) dd [a + b];
                                              b + a
          (%o2)                  lambda([y], y     )

          (%i3) dd [v - u];
                                              v - u
          (%o3)                  lambda([y], y     )

          (%i4) arrayinfo (dd);
          (%o4)             [hashed, 1, [b + a], [v - u]]

          (%i5) listarray (dd);
                                   b + a                v - u
          (%o5)      [lambda([y], y     ), lambda([y], y     )]

     Categories: Arrays

 -- Function: arraymake (A, [I_1, ..., I_N])

     Returns the expression A[I_1, ..., I_N]. The result is an unevaluated array reference.

     arraymake is reminiscent of funmake except the return value is an unevaluated array reference instead of an unevaluated function call.

     Examples:

          (%i1) arraymake (A, [1]);
          (%o1)                          A
                                          1

          (%i2) arraymake (A, [k]);
          (%o2)                          A
                                          k

          (%i3) arraymake (A, [i, j, 3]);
          (%o3)                       A
                                       i, j, 3

          (%i4) array (A, fixnum, 10);
          (%o4)                           A

          (%i5) fillarray (A, makelist (i^2, i, 1, 11));
          (%o5)                           A

          (%i6) arraymake (A, [5]);
          (%o6)                          A
                                          5

          (%i7) ''%;
          (%o7)                          36

          (%i8) L : [a, b, c, d, e];
          (%o8)                    [a, b, c, d, e]

          (%i9) arraymake ('L, [n]);
          (%o9)                          L
                                          n

          (%i10) ''%, n = 3;
          (%o10)                          c

          (%i11) A2 : make_array (fixnum, 10);
          (%o11)        {Lisp Array: #(0 0 0 0 0 0 0 0 0 0)}

          (%i12) fillarray (A2, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
          (%o12)        {Lisp Array: #(1 2 3 4 5 6 7 8 9 10)}

          (%i13) arraymake ('A2, [8]);
          (%o13)                         A2
                                           8

          (%i14) ''%;
          (%o14)                          9

     Categories: Expressions Arrays

 -- System variable: arrays
     Default value: []

     arrays is a list of arrays that have been allocated. These comprise arrays declared by array hashed arrays that can be constructed by implicit definition (assigning something to an element that isn't yet declared as a list or an array), and memoizing functions defined by := and define Arrays defined by make_array are not included.

     See also array arrayapply arrayinfo arraymake fillarray listarray and rearray

     Examples:

          (%i1) array (aa, 5, 7);
          (%o1)                          aa

          (%i2) bb [FOO] : (a + b)^2;
                                             2
          (%o2)                       (b + a)

          (%i3) cc [x] := x/100;
                                             x
          (%o3)                      cc  := ---
                                       x    100

          (%i4) dd : make_array ('any, 7);
          (%o4)     {Lisp Array: #(NIL NIL NIL NIL NIL NIL NIL)}

          (%i5) arrays;
          (%o5)                     [aa, bb, cc]

     Categories: Arrays Global variables

 -- Function: arraysetapply (A, [I_1, ..., I_N], X)

     Assigns X to A[I_1, ..., I_N], where A is an array and I_1, ..., I_N are integers.

     arraysetapply evaluates its arguments.

     Categories: Expressions Arrays

 -- Function: fillarray (A, B)

     Fills array A from B, which is a list or an array.

     If a specific type was declared for A when it was created, it can only be filled with elements of that same type; it is an error if an attempt is made to copy an element of a different type.

     If the dimensions of the arrays A and B are different, A is filled in row-major order.  If there are not enough elements in B the last element is used to fill out the rest of A.  If there are too many, the remaining ones are ignored.

     fillarray returns its first argument.

     Examples:

     Create an array of 9 elements and fill it from a list.

          (%i1) array (a1, fixnum, 8);
          (%o1)                          a1

          (%i2) listarray (a1);
          (%o2)              [0, 0, 0, 0, 0, 0, 0, 0, 0]

          (%i3) fillarray (a1, [1, 2, 3, 4, 5, 6, 7, 8, 9]);
          (%o3)                          a1

          (%i4) listarray (a1);
          (%o4)              [1, 2, 3, 4, 5, 6, 7, 8, 9]

     When there are too few elements to fill the array, the last element is repeated. When there are too many elements, the extra elements are ignored.

          (%i1) a2 : make_array (fixnum, 8);
          (%o1)           {Lisp Array: #(0 0 0 0 0 0 0 0)}

          (%i2) fillarray (a2, [1, 2, 3, 4, 5]);
          (%o2)           {Lisp Array: #(1 2 3 4 5 5 5 5)}

          (%i3) fillarray (a2, [4]);
          (%o3)           {Lisp Array: #(4 4 4 4 4 4 4 4)}

          (%i4) fillarray (a2, makelist (i, i, 1, 100));
          (%o4)           {Lisp Array: #(1 2 3 4 5 6 7 8)}

     Multiple-dimension arrays are filled in row-major order.

          (%i1) a3 : make_array (fixnum, 2, 5);
          (%o1)      {Lisp Array: #2A((0 0 0 0 0) (0 0 0 0 0))}

          (%i2) fillarray (a3, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
          (%o2)      {Lisp Array: #2A((1 2 3 4 5) (6 7 8 9 10))}

          (%i3) a4 : make_array (fixnum, 5, 2);
          (%o3)   {Lisp Array: #2A((0 0) (0 0) (0 0) (0 0) (0 0))}

          (%i4) fillarray (a4, a3);
          (%o4)   {Lisp Array: #2A((1 2) (3 4) (5 6) (7 8) (9 10))}

     Categories: Arrays

 -- Function: listarray (A)

     Returns a list of the elements of the array A. The argument A may be an array, an undeclared array (hashed array), a memoizing function or a subscripted function.

     Elements are listed in row-major order. That is, elements are sorted according to the first index, then according to the second index, and so on.  The sorting order of index values is the same as the order established by orderless

     For undeclared arrays (hashed arrays), memoizing functions and subscripted functions, the elements correspond to the index values returned by arrayinfo

     Unbound elements of general arrays (that is, not fixnum and not flonum) are returned as #####. Unbound elements of fixnum or flonum arrays are returned as 0 or 0.0, respectively. Unbound elements of hashed arrays, memoizing functions and subscripted functions are not returned.

     Examples:

     listarray and arrayinfo applied to a declared array.

          (%i1) array (aa, 2, 3);
          (%o1)                          aa

          (%i2) aa [2, 3] : %pi;
          (%o2)                          %pi

          (%i3) aa [1, 2] : %e;
          (%o3)                          %e

          (%i4) listarray (aa);
          (%o4) [#####, #####, #####, #####, #####, #####, %e, #####,
                                                  #####, #####, #####, %pi]

          (%i5) arrayinfo (aa);
          (%o5)                 [declared, 2, [2, 3]]

     listarray and arrayinfo applied to an undeclared array (hashed array).

          (%i1) bb [FOO] : (a + b)^2;
                                             2
          (%o1)                       (b + a)

          (%i2) bb [BAR] : (c - d)^3;
                                             3
          (%o2)                       (c - d)

          (%i3) listarray (bb);
                                        3         2
          (%o3)                 [(c - d) , (b + a) ]

          (%i4) arrayinfo (bb);
          (%o4)               [hashed, 1, [BAR], [FOO]]

     listarray and arrayinfo applied to a memoizing function

          (%i1) cc [x, y] := y / x;
                                               y
          (%o1)                      cc     := -
                                       x, y    x

          (%i2) cc [u, v];
                                          v
          (%o2)                           -
                                          u

          (%i3) cc [4, z];
                                          z
          (%o3)                           -
                                          4

          (%i4) listarray (cc);
                                        z  v
          (%o4)                        [-, -]
                                        4  u

          (%i5) arrayinfo (cc);
          (%o5)              [hashed, 2, [4, z], [u, v]]

     listarray and arrayinfo applied to a subscripted function.

          (%i1) dd [x] (y) := y ^ x;
                                               x
          (%o1)                     dd (y) := y
                                      x

          (%i2) dd [a + b];
                                              b + a
          (%o2)                  lambda([y], y     )

          (%i3) dd [v - u];
                                              v - u
          (%o3)                  lambda([y], y     )

          (%i4) listarray (dd);
                                   b + a                v - u
          (%o4)      [lambda([y], y     ), lambda([y], y     )]

          (%i5) arrayinfo (dd);
          (%o5)             [hashed, 1, [b + a], [v - u]]

     Categories: Arrays

 -- Function: make_array (TYPE, DIM_1, ..., DIM_N)

     Creates and returns a Lisp array.  TYPE may be any, flonum, fixnum, hashed or functional. There are n indices, and the i'th index runs from 0 to DIM_I - 1.

     The advantage of make_array over array is that the return value doesn't have a name, and once a pointer to it goes away, it will also go away. For example, if y: make_array (...) then y points to an object which takes up space, but after y: false, y no longer points to that object, so the object can be garbage collected.

     Examples:

          (%i1) A1 : make_array (fixnum, 10);
          (%o1)         {Lisp Array: #(0 0 0 0 0 0 0 0 0 0)}

          (%i2) A1 [8] : 1729;
          (%o2)                         1729

          (%i3) A1;
          (%o3)        {Lisp Array: #(0 0 0 0 0 0 0 0 1729 0)}

          (%i4) A2 : make_array (flonum, 10);
          (%o4) {Lisp Array: #(0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0)}

          (%i5) A2 [2] : 2.718281828;
          (%o5)                      2.718281828

          (%i6) A2;
          (%o6)
           {Lisp Array: #(0.0 0.0 2.718281828 0.0 0.0 0.0 0.0 0.0 0.0 0.0)}

          (%i7) A3 : make_array (any, 10);
          (%o7) {Lisp Array: #(NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL)}

          (%i8) A3 [4] : x - y - z;
          (%o8)                     (- z) - y + x

          (%i9) A3;
          (%o9) {Lisp Array: #(NIL NIL NIL NIL
                         ((MPLUS SIMP) $X ((MTIMES SIMP) -1 $Y) ((MTIMES S\
          IMP) -1 $Z))
                         NIL NIL NIL NIL NIL)}

          (%i10) A4 : make_array (fixnum, 2, 3, 5);
          (%o10) {Lisp Array: #3A(((0 0 0 0 0) (0 0 0 0 0) (0 0 0 0 0))
                           ((0 0 0 0 0) (0 0 0 0 0) (0 0 0 0 0)))}

          (%i11) fillarray (A4, makelist (i, i, 1, 2*3*5));
          (%o11) {Lisp Array: #3A(((1 2 3 4 5) (6 7 8 9 10) (11 12 13 14 1\
          5))
                           ((16 17 18 19 20) (21 22 23 24 25) (26 27 28 29\
           30)))}

          (%i12) A4 [0, 2, 1];
          (%o12)                         12

     Categories: Arrays

 -- Function: rearray (A, DIM_1, ..., DIM_N)

     Changes the dimensions of an array. The new array will be filled with the elements of the old one in row-major order.  If the old array was too small, the remaining elements are filled with false, 0.0 or 0, depending on the type of the array.  The type of the array cannot be changed.

     Categories: Arrays

 -- Function: remarray
     remarray (A_1, ..., A_N)
     remarray (all)

     Removes arrays and array associated functions and frees the storage occupied. The arguments may be declared arrays, hashed arrays array functions, and subscripted functions.

     remarray (all) removes all items in the global list arrays

     It may be necessary to use this function if it is desired to clear the cache of a memoizing function

     remarray returns the list of arrays removed.

     remarray quotes its arguments.

     Categories: Arrays

 -- Function: subvar (X, I)

     Evaluates the subscripted expression X[I].

     subvar evaluates its arguments.

     arraymake (X, [I]) constructs the expression X[I], but does not evaluate it.

     Examples:

          (%i1) x : foo $
          (%i2) i : 3 $

          (%i3) subvar (x, i);
          (%o3)                         foo
                                           3

          (%i4) foo : [aa, bb, cc, dd, ee]$

          (%i5) subvar (x, i);
          (%o5)                          cc

          (%i6) arraymake (x, [i]);
          (%o6)                         foo
                                           3

          (%i7) ''%;
          (%o7)                          cc

     Categories: Expressions Arrays

 -- Function: subvarp (EXPR)

     Returns true if EXPR is a subscripted variable, for example a[i].

     Categories: Predicate functions

 -- Option variable: use_fast_arrays
     Default value: false

     When use_fast_arrays is true, arrays declared by array are values instead of properties, and undeclared arrays (hashed arrays) are implemented as Lisp hashed arrays.

     When use_fast_arrays is false, arrays declared by array are properties, and undeclared arrays are implemented with Maxima's own hashed array implementation.

     Note that the code use_fast_arrays switches to is not necessarily faster than the default one; Arrays created by make_array are not affected by use_fast_arrays.

     See also translate_fast_arrays

     Categories: Arrays Global flags

 -- Option variable: translate_fast_arrays
     Default value: false

     When translate_fast_arrays is true, the Maxima-to-Lisp translator generates code that assumes arrays are values instead of properties, as if use_fast_arrays were true.

     When translate_fast_arrays is false, the Maxima-to-Lisp translator generates code that assumes arrays are properties, as if use_fast_arrays were false.

     Categories: Arrays Translation flags and variables