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:number2:number3

Take the range number1 to number2 with step number3.

*

Add a new dummy index of width 1.

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.

subthread

dummy

        $a->dummy(n[,m])

Inserts a dummy dimension as dimension n of $a. A dummy dimension has increment of 0 and dimension of one by default or m if given.

asvector

        $a->asvector()

This changes the whole pdl structure into one-dimensional vector. The idea is that after this it is easy to do minimum/maximum/other such functions over the vector without worrying about the logical structure. Warning: NEVER use this after some other mapping operation has been performed on the pdl: very strange things will happen.

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)

cpanm PDL

perl -MCPAN -e shell
install PDL