copy a block of several segments of elements from one Matrix, Vector, or Array to another - Maple Help

Online Help

All Products    Maple    MapleSim


Home : Support : Online Help : Programming : Low-level Manipulation : Matrices, Vectors, and Arrays : ArrayTools : ArrayTools/BlockCopy

ArrayTools[BlockCopy] - copy a block of several segments of elements from one Matrix, Vector, or Array to another

Calling Sequence

BlockCopy(A,offsetA,skipA,segsizeA,numsegsA,B,offsetB,skipB,segsizeB,numsegsB)

Parameters

A

-

source; rectangular storage Matrix, Vector, or Array of any data type and ordering

offsetA

-

(optional); offset for source

skipA

-

increment for source; the number of elements between the start of consecutive segments

segsizeA

-

(optional); segment size for source; the number of elements in each segment. Must not be larger than skipA. Can be specified only if offsetA is specified

numsegsA

-

(optional); number of segments to copy from source. Can only be specified if segsizeA is specified

B

-

target; rectangular storage Matrix, Vector, or Array of matching data type and any ordering

offsetB

-

(optional); offset for target

skipB

-

increment for target; the number of elements between the start of consecutive segments

segsizeB

-

(optional); segment size for target, if different from segsizeA. Must not be larger than skipB. Can be specified only if offsetB is specified

numsegsB

-

(optional); number of segments to write data to when copying into target. Can only be specified if segsizeB is specified

Description

• 

The BlockCopy command copies a block of data from an existing Matrix, Vector, or Array (source) to another Matrix, Vector, or Array (target). The data types of the source and target must match, or an error results. In addition, the source and target must both have rectangular (dense) storage.

• 

In contrast to ArrayTools[Copy], which copies a single segment of data from the source to the target, BlockCopy copies multiple equally spaced equal-sized segments of elements from the source to the target.  Such segments must be groups of contiguous elements when the underlying one-dimensional ordering of the source rtable is considered.  The result depends only upon the internal ordering of the elements in the input rtable, and is independent of the shape of the source or target rtables. Consequently, this routine requires knowledge of the storage structure of multi-dimensional rectangular rtables under different data orderings (C_order and Fortran_order).  For a description of storage under these orderings, see Fortran_order.

• 

With the source and target segment sizes set to 1, BlockCopy behaves in the same manner as ArrayTools[Copy].  The command ArrayTools[Copy](num,A,offsetA,skipA,B,offsetB,skipB) performs the same data movements as the command ArrayTools[BlockCopy](A,offsetA,skipA,1,num,B,offsetB,skipB,1,num).

• 

The parameters offsetA, skipA, segsizeA, numsegsA, offsetB, skipB, segsizeB, and numsegsB provide a mechanism for specifying the size, shape, and location of the source and destination blocks.  The data copied from the source is a block of numsegsA segments of segsizeA elements.  The first segment starts at position offsetA+1, and each subsequent segment begins skipA elements after the previous one.  These segsizeA*numsegsA elements are copied into numsegsB segments of segsizeB elements in the target.  The first target segment starts at position offsetB+1, and each subsequent segment begins skipA elements after the previous one.

• 

The default values of the optional parameters are described as follows:

– 

offsetA and offsetB are 0 (start at the very beginning)

– 

segsizeA and numsegsA are 1 (copy one segment of one element)

– 

segsizeB is equal to segsizeA (copy each source segment into a target segment of equal size)

– 

numsegsB is equal to segsizeAnumsegsAsegsizeB (copy the source block into a target block containing an equal number of elements; numsegsB will be exactly numsegsA if segsizeB is also unspecified.)

• 

The skipA and skipB parameters must be specified.  When copying a submatrix of elements from a 2-dimensional Array or Matrix, skipA and skipB are usually set to the number of rows (for Fortran order rtables) or the number of columns (for C order rtables) of the source and target rtables, respectively.  Making the source and target increments equal to the number of rows (or number of columns, for C order rtables) tells BlockCopy to copy using the same offset in each column (or row), thereby copying a physical rectangular submatrix of elements.

• 

As an example, copying the upper-right p by q block of an n by m C order Matrix A (where pn and qm) corresponds to accessing the elements mq+i1+mj1 of the underlying rtable data structure (for i=1..q and j=1..p).  The source offset would be mq, since the first mq elements are skipped.  The source increment would be m (the number of columns in the input rtable), since each segment begins exactly one row, or m elements, after the previous one.  The segment size and number of segments would be q and p, respectively.  To copy this into a p by q C order Matrix B, only skipB would need to be computed, since the default values for the other parameters would copy a block of identical size and shape into B.  The command to accomplish this would then be BlockCopy(A,m-q,m,q,p,B,q) (where m, n, p, and q are fixed values corresponding to the problem.)

• 

In contrast, the same operation for an n by m Fortran order rtable must be specified differently. The source offset will now be nmq, since all the values in the first m-q columns are skipped. The source increment will be n (the number of rows) and the segment size and number of segments become reversed, giving us q segments of p elements instead of p segments of q elements.  If the destination is a p by q Fortran order Matrix, the command to accomplish this is BlockCopy(A,n*(m-q),n,p,q,B,p).

• 

This function is part of the ArrayTools package, so it can be used in the short form BlockCopy(..) only after executing the command with(ArrayTools).  However, it can always be accessed through the long form of the command by using ArrayTools[BlockCopy](..).

Examples

withArrayTools:

Copy the upper-right 3x2 block of a Fortran order Matrix into another Matrix:

A:=Matrix11,12,13,14,21,22,23,24,31,32,33,34,41,42,43,44

A:=11121314212223243132333441424344

(1)

B:=Matrix3,2:

BlockCopyA,8,4,3,2,B,3

B

131423243334

(2)

Use the offset parameter to copy the block into the lower left of another Fortran order Matrix:

C:=Matrix5,3:

BlockCopyA,8,4,3,2,C,2,5

C

000000131402324033340

(3)

Copy the same block, but reshape it into a 6x1 column Vector:

V:=Vector6:

BlockCopyA,8,4,3,2,V,0,6,6,1

V

132333142434

(4)

The original example, but with a C order Matrix instead.  Note the different parameter values:

A:=Matrix11,12,13,14,21,22,23,24,31,32,33,34,41,42,43,44,order=C_order

A:=11121314212223243132333441424344

(5)

B:=Matrix3,2,order=C_order:

BlockCopyA,2,4,2,3,B,2

B

131423243334

(6)

BlockCopy can be used to create a Matrix from several sub-matrices.

J1:=Matrix1,0,0,1

J1:=1001

(7)

J2:=Matrix0,1,1,0

J2:=0110

(8)

J:=Matrix4,4

J:=0000000000000000

(9)

BlockCopyJ1,0,2,2,2,J,0,4,2,2

BlockCopyJ2,0,2,2,2,J,2,4,2,2

BlockCopyJ2,0,2,2,2,J,8,4,2,2

BlockCopyJ1,0,2,2,2,J,10,4,2,2

J

1001011001101001

(10)

Extract every second row of a C order Matrix, and concatenate them into a row vector.  Here, since you are skipping every second row, the skipA parameter is not equal to the number of columns:

A:=Matrix5,3,i,j→10i+j,order=C_order

A:=111213212223313233414243515253

(11)

V:=Vectorrow9

V:=000000000

(12)

BlockCopyA,0,6,3,3,V,0,9,9,1

V

111213313233515253

(13)

See Also

ArrayTools, ArrayTools[Copy], ArrayTools[Fill], C_order, Fortran_order


Download Help Document

Was this information helpful?



Please add your Comment (Optional)
E-mail Address (Optional)
What is ? This question helps us to combat spam