NAME
PDL::Thread -- Funny PDL index manipulations
DESCRIPTION
This package provides several routines to be used with PDL xsubs compiled with PDL::PP. PDL::PP-compiled routines know how to interpret the fields Incs, ThreadDims, ThreadIncs and Offs which makes these routines possible.
map
$a->map('ind0,ind1...')This function takes a rectangular slice of $a. The part "ind0" specifies what happens to the index 0 etc. The specification can have the following forms:
- :
-
The whole dimension i.e. don't slice
- number
-
Take only the values at "number" so the dimension of this index becomes 1.
- (number)
-
Same as the previous but additionally, remove the index.
- number1:number2
-
Take the range number1 to number2
- number1:number:number2
-
Take the range number1 to number2 with step number
thread
$a->thread(indices)This command is used to do "explicit threading". See PDL::PP for background on threading. Explicit threading requires there to be matching number of thread indices for each of the arguments to the function, so
func($a->thread(1),$b->thread(2,3));is currently illegal.
The arguments to the $a-thread> call refer to the dimensions of $a and when calling the xsub function, the arguments in the same place in the different parameters refer to the same thread index, that is:
func($a->thread(2,3),$b->thread(0,1));Means that there are two dimensions over which a we are threading. This corresponds to the pseudocode (assuming that both $a and $b have 4 dimensions)
func($a(:,:,0,0),$b(0,0,:,:));
func($a(:,:,0,1),$b(0,1,:,:));
func($a(:,:,0,2),$b(0,2,:,:));
.
.
func($a(:,:,1,0),$b(1,0,:,:));
.
.
func($a(:,:,x,y),$b(x,y,:,:));A parameter -1 to thread means that this pdl should not be threaded over that thread dimension and a dummy index is created.
Depending on what you are doing, you have to choose between explicit and implicit threading or a combination of the two.
xchg
$a->xchg(ind1,ind2)Exchanges the indices with each other.
dummy
$a->dummy(n)Inserts a dummy dimension as dimension n of $a. A dummy dimension has increment of 0 and dimension of one.
printdims
$a->printdims()Prints the dimensions of $a to standard output. Just for debugging.
BUGS
All this is WAY too powerless yet: we need more power!
The documentation is currently written by the author.
The implementation is tentative: everything may change.
This really needs to be rewritten in C once eveything solidifies and PDL starts converting the struct to C. Now it's more comfortable to hone the interface in Perl.
These routines only work with xsubs compiled with PDL::PP. The results of using these in other ways are highly unpredictable.
AUTHOR
Tuomas J. Lukka (lukka@fas.harvard.edu)