putarray#

Purpose#

Puts a contiguous subarray into an N-dimensional array and returns the resulting array.

Format#

y = putarray(dest, loc, src)#

Parameters:

dest (N-dimensional array) – destination data
loc (Mx1 vector) – indices into the array to locate the subarray of interest, where M is a value from 1 to N.
src ([N-M]-dimensional array or matrix or scalar.) – source data

Returns:

y (N-dimensional array) – resulting array with destination data in a inserted into the source data.

Examples#

Example 1: 3D array#

// Create a 2x3x4 dimensional array filled with zeros
dest = arrayinit(2|3|4, 0);

// Create a 3x4 matrix of random numbers
rndseed 54324;
src = rndn(3,4);

// Place the contents of 'src' into the
// first 3x4 submatrix of the array
loc = 1;
a = putarray(dest, loc, src);

After the above code, a will equal:

Plane [1,.,.]

 -2.4904   0.5745  -2.6505   1.1118
  0.8425   1.3397  -1.1305   0.8991
 -1.3205  -0.3568   1.8457   0.6052

Plane [2,.,.]

  0.0000   0.0000   0.0000   0.0000
  0.0000   0.0000   0.0000   0.0000
  0.0000   0.0000   0.0000   0.0000

Note that in the above call to putarray(), a complete copy of the dest array will be made to copy into a. In this case, it is obvious that is is needed. However, even if we change the code to:

dest = putarray(dest, loc, src);

a complete copy of dest will be made. This will significantly slow down your code. We can avoid this in one of two ways. The first is to use an index assignment instead of putarray() like this:

// An index assignment avoids a complete copy
// of the array and improves performance
dest[loc,.,.] = src;

The other option is to use the move keyword to tell GAUSS that it does not need to keep the original version of dest, like this:

// 'move' tells GAUSS it does not need to keep
// the original copy of 'dest', which will improve performance
dest = putarray(move(dest), loc, src);

Example 2: Arrays with more than 3 dimensions#

To use putarray() with arrays with more than three dimensions, the location variable will need to have two fewer dimensions than the array being assigned to. Our example array below has four dimensions, so the location variable has two dimensions.

// Initialize a 2x2x3x4 array with zeros
a = arrayinit(2|2|3|4, 0);

// Fill the [2, 1, ., .] submatrix
// with the value of pi
loc = { 2, 1 };
src = ones(3, 4) .* pi;
a = putarray(a, loc, src);

After the above code, a is equal to:

Plane [1,1,.,.]

0000   0.0000   0.0000   0.0000
0000   0.0000   0.0000   0.0000
0000   0.0000   0.0000   0.0000

Plane [1,2,.,.]

0000   0.0000   0.0000   0.0000
0000   0.0000   0.0000   0.0000
0000   0.0000   0.0000   0.0000

Plane [2,1,.,.]

1416   3.1416   3.1416   3.1416
1416   3.1416   3.1416   3.1416
1416   3.1416   3.1416   3.1416

Plane [2,2,.,.]

0000   0.0000   0.0000   0.0000
0000   0.0000   0.0000   0.0000
0000   0.0000   0.0000   0.0000

Remarks#

See the performance indications in example 1 above.

If loc is an Nx1 vector, then src must be a scalar. If loc is an [N-1]x1 vector, then src must be a 1-dimensional array or a 1xL vector, where L is the size of the fastest moving dimension of the array. If loc is an [N-2]x1 vector, then src must be a KxL matrix, or a KxL 2-dimensional array, where K is the size of the second fastest moving dimension.

Otherwise, if loc is an Mx1 vector, then src must be an [N-M]-dimensional array, whose dimensions are the same size as the corresponding dimensions of array dest.