Unix Man page/Perldoc/Info page, English-Chinese Dictionary, Chinese-English Dictionary

PDL::FAQ

FAQ(1p) User Contributed Perl Documentation FAQ(1p)

NAME
PDL::FAQ - Frequently asked questions about PDL

VERSION
Current FAQ version: 0.7

DESCRIPTION
This is version 0.7 of the PDL FAQ, a collection of frequently asked
questions about PDL - the Perl Data Language.

ABOUT THIS DOCUMENT
Q: 1.1 Where to find this document

You can find the latest version of this document at http://pdl.source-
forge.net/FAQ .

Q: 1.2 How to contribute to this document

This is a considerably reworked version of the PDL FAQ. As such many
errors might have crept in and many updates might not have made it in.
You are explicitly encouraged to let us know about questions which you
think should be answered in this document but currently aren't. Simi-
larly, if you think parts of this document are unclear, please tell the
FAQ maintainer about it. Where a specific answer is taken in full from
someone's posting the authorship should be indicated, let the FAQ main-
tainer know if it isn't. For more general information explicit acknowl-
edgement is not made in the text, but rather there is an incomplete
list of contributors at the end of this docuement. Please contact the
FAQ maintainer if you feel hard done by.

Send your comments, additions, suggestions or corrections to the PDL
mailing list at perldl AT jach.edu. See below for instructions on
how to join the mailing lists.

GENERAL QUESTIONS
Q: 2.1 What is PDL ?

PDL stands for Perl Data Language . To say it with the words of Karl
Glazebrook, initiator of the PDL project:

The PDL concept is to give standard perl5 the ability
to COMPACTLY store and SPEEDILY manipulate the large
N-dimensional data sets which are the bread and butter
of scientific computing. e.g. $a=$b+$c can add two
2048x2048 images in only a fraction of a second.

It provides tons of useful functionality for scientific and numeric
analysis.

For readers familiar with other scientific data evaluation packages it
may be helpful to add that PDL is in many respects similar to IDL, MAT-
LAB and similar packages. However, it tries to improve on a number of
issues which were perceived (by the authors of PDL) as shortcomings of
those existing packages.

Q: 2.2 Who supports PDL? Who develops it?

PDL is supported by its users. General informal support for PDL is pro-
vided through the PDL mailing list (perldl AT jach.edu , see
below).

As a Perl extension (see below) it is devoted to the idea of free and
open development put forth by the Perl community. PDL was and is being
actively developed by a loosely knit group of people around the world
who coordinate their activities through the PDL development mailing
list (pdl-porters AT jach.edu , see below). If you would like to
join in the ongoing efforts to improve PDL please join this list.

Q: 2.3 Why yet another Data Language ?

There are actually several reasons and everyone should decide for him-
self which are the most important ones:

o PDL is "free software". The authors of PDL think that this concept
has several advantages: everyone has access to the sources -> bet-
ter debugging, easily adaptable to your own needs, extensible for
your purposes, etc... In comparison with commercial packages such
as Matlab and IDL this is of considerable importance for workers
who want to do some work at home and cannot afford the considerable
cost to buy commercial packages for personal use.

o PDL is based on a powerful and well designed scripting language:
Perl. In contrast to other scientific/numeric data analysis lan-
guages it has been designed using the features of a proven language
instead of having grown into existence from scratch. Defining the
control structures while features were added during development
leads to languages that often appear clumsy and badly planned for
most existing packages with similar scope as PDL.

o Using Perl as the basis a PDL programmer has all the powerful fea-
tures of Perl at his hand, right from the start. This includes reg-
ular expressions, associative arrays (hashes), well designed inter-
faces to the operating system, network, etc. Experience has shown
that even in mainly numerically oriented programming it is often
extremely handy if you have easy access to powerful semi-numerical
or completely non-numerical functionality as well. For example, you
might want to offer the results of a complicated computation as a
server process to other processes on the network, perhaps directly
accepting input from other processes on the network. Using Perl and
existing Perl extension packages things like this are no problem at
all (and it all will fit into your "PDL script").

o Extremely easy extensibility and interoperability as PDL is a Perl
extension; development support for Perl extensions is an integral
part of Perl and there are already numerous extensions to standard
Perl freely available on the network.

o Integral language features of Perl (regular expressions, hashes,
object modules) immensely facilitated development and implementa-
tion of key concepts of PDL. One of the most striking examples for
this point is probably PDL::PP (see below), a code genera-
tor/parser/pre-processor that generates PDL functions from concise
descriptions.

o None of the existing DLs follow the Perl language rules, which the
authors firmly believe in:

o TIMTOWTDI: There is more than one way to do it. Minimalist
languages are interesting for computer scientists, but for
users, a little bit of redundancy makes things wildly easier to
cope with and allows individual programming styles - just as
people speak in different ways. For many people this will
undoubtedly be a reason to avoid PDL ;)

o Simple things are simple, complicated things possible: Things
that are often done should be easy to do in the language,
whereas seldom done things shouldn't be too cumbersome.

All existing languages violate at least one of these rules.

o As a project for the future PDL should be able to use super com-
puter features, e.g. vector capabilities/parallel processing. This
will probably be achieved by having PDL::PP (see below) generate
appropriate code on such architectures to exploit these features.

o [ fill in your personal 111 favourite reasons here...]

Q: 2.4 What is PDL good for ?

Just in case you do not yet know what the main features of PDL are and
what one could do with them, here is a (necessarily selective) list of
key features:

PDL is well suited for matrix computations, general handling of multi-
dimensional data, image processing, general scientific computation,
numerical applications. It supports I/O for many popular image and data
formats, 1D (line plots), 2D (images) and 3D (volume visualisation,
surface plots via OpenGL - for instance impelmented using Mesa), graph-
ics display capabilities and implements lots of numerical and semi-
numerical algorithms.

Through the powerful pre-processor it is also easy to interface Perl to
your favourite C routines, more of that further below.

Q: 2.5 What is the connection between PDL and Perl ?

PDL is a Perl5 extension package. As such it needs an existing Perl5
installation (see below) to run. Furthermore, much of PDL is written in
perl (+ some core functionality that is written in C). PDL programs are
(syntactically) just perl scripts that happen to use some of the func-
tionality implemented by the package "PDL".

Q: 2.6 What do I need to run PDL on my machine ?

Since PDL is just a Perl package you need first of all an installation
of Perl on your machine. As of this writing PDL requires version 5.6 of
Perl, version 5.8 or higher is strongly recommended. More information
on where and how to get a Perl installation can be found at the Perl
home page http://www.perl.org and at many CPAN sites (if you do not
know what CPAN is check the answer to the next question).

To build PDL you also need a working C compiler and support for Xsubs
the package Extutils::MakeMaker. See also
http://pdl.perl.org/ports.html for a list of machines where PDL has
been tested. If you don't have a compiler there might be a binary dis-
tribution availabe, see "Binary distributions" below.

If you can (or cannot) get PDL working on a new (previously unsup-
ported) platform we would like to hear about it. Please, report your
success/failure to the PDL mailing list at perldl AT jach.edu . We
will do our best to assist you in porting PDL to a new system.

Q: 2.7 Where do I get it?

PDL is available as source distribution in the Comprehensive Perl
Archive Network , or CPAN. This archive contains not only the PDL dis-
tribution but also just about everything else that is Perl-related.
CPAN is mirrored by dozens of sites all over the world. The main site
is http://www.cpan.org , and local CPAN sites (mirrors) can be found
there. Within CPAN you find the latest released version of PDL in the
directory /modules/by-module/PDL/. PDLs homepage is at
http://pdl.perl.org and the latest version can also be downloaded from
there.

Q: 2.8 What do I have to pay to get PDL?

We are delighted to be able to give you the nicest possible answer on a
question like this: PDL is *free software* and all sources are publicly
available. But still, there are some copyrights to comply with. So
please, try to be as nice as we (the PDL authors) are and try to comply
with them.

Oh, before you think it is *completely* free: you have to invest some
time to pull the distribution from the net, compile and install it and
(maybe) read the manuals.

GETTING HELP/MORE INFORMATION
Q: 3.1 Where can I get information on PDL?

The complete PDL documentation is available with the PDL distribution.
If you have PDL installed on your machine and are on a unix like system
then you can read the PDL manuals with the " man" command. " man PDL"
get you started, " man PDL::FAQ" will let you read this document, etc.
In any case (i.e. also on non-unixes) " perldoc PDL::Intro" should
work, and if you don't want to type that much, " pdldoc intro" should
also work.

The easiest way by far, however, to get familiar with PDL is to use the
PDL online help facility from within the " perldl" shell. Just type "
perldl" at your system prompt. Once you are inside the " perldl" shell
type " help" . Using the " help" and " apropos" commands inside the
shell you should be able to find the way round the documentation. Even
better, you can immediately try your newly acquired knowledge about PDL
by issuing PDL/perl commands directly at the command line. To illus-
trate this process, here is the record of a typical perldl session of a
PDL beginner (lengthy output is only symbolically reproduced in braces
( <... ...> ) ):

unix> perldl
perldl> help
<.... help output ....>
perldl> help PDL::Impatient
<.... man page ....>
perldl> $a = pdl (1,5,7.3,1.0)
perldl> $b = sequence float, 4, 4
perldl> help inner
<.... help on the 'inner' function ....>
perldl> $c = inner $a, $b
perldl> p $c
[22.6 79.8 137 194.2]

For further sources of information that are accessible through the
internet see next question.

Q: 3.2 Are there other PDL information sources on the internet?

First of all, for all purely Perl-related questions there are tons of
sources on the net. Good points to start are http://www.perl.com and
http://www.perl.org .

The PDL home site can be accessed by pointing your web browser to
http://pdl.perl.org . It has tons of goodies for anyone interested in
PDL:

o PDL distributions

o Online documentation

o Pointers to an HTML archive of the PDL mailing lists

o A list of platforms on which PDL has been successfully tested.

o News about recently added features, ported libraries, etc.

o Name of the current pumpkin holders for the different PDL modules
(if you want to know what that means you better had a look at the
web pages).

If you are interested in PDL in general you can join the PDL mailing
list perldl AT jach.edu. This is a forum to discuss programming
issues in PDL, report bugs, seek assistance with PDL related problems,
etc. To subscribe, send a message to perldl-request AT jach.edu
containing a string in the following format:

subscribe me AT my.address

where you should replace the string " me AT my.address" with your
email address. A searchable archive and a hypertext version of the
traffic on this list (1997-2004) can be found at
http://www.xray.mpe.mpg.de/mailing-lists/perldl/ . More recent messages
(since June 2005) can be found at http://mailman.jach.hawaii.edu/mail-
man/listinfo/perldl

If you are interested in all the technical details of the ongoing PDL
development you can join the PDL developers mailing list
pdl-porters AT jach.edu . To subscribe, send a message to
pdl-porters-request AT jach.edu containing a string in the follow-
ing format:

subscribe me AT my.address

where you should replace the string " me AT my.address" with your
email address. A searchable archive and a hypertext version of the
traffic on this list (1997-2004) can be found at
http://www.xray.mpe.mpg.de/mailing-lists/pdl-porters/ . More recent
messages (since June 2005) can be found at http://mail-
man.jach.hawaii.edu/mailman/listinfo/pdl-porters

Crossposting between these lists should be avoided unless there is a
very good reason for doing that.

Q: 3.3 What is the current version of PDL ?

As of this writing (FAQ version 0.7 of April 2006) version 2.4.3 is
nearing release. The latest stable version should always be available
from a CPAN mirror site near you (see Question 2.7 for info on where to
get PDL.

The most current (possibly unstable) version of PDL can be obtained
from the CVS repository, see Question 4.8

Q: 3.4 I want to contribute to the further development of PDL. How
can I help?

If you have a certain project in mind you should check if somebody else
is already working on it or if you could benefit from existing modules.
Do so by posting your planned project to the PDL developers mailing
list at pdl-porters AT jach.edu . See the subscription instructions
in Question 3.2. We are always looking for people to write code and/or
documentation ;).

Q: 3.5 I think I have found a bug in the current version of PDL.
What shall I do?

First, make sure that the bug/problem you came across has not already
been dealt with somewhere else in this FAQ. Secondly, you can check the
searchable archive of the PDL mailing list to find whether this bug has
already been discussed. If you still haven't found any explanations you
can post a bug report to perldl AT jach.edu , or through the Bugs
link on http://pdl.perl.org .

INSTALLATION
Q: 4.1 I have problems installing PDL. What shall I do?

First make sure you have read the file INSTALL in the distribution.
This contains a list of common problems which are unnecessary to repeat
here. Next, check the file perldl.conf to see if by editing the config-
uration options in that file you will be able to successfully build
PDL. Some of the modules need additional software installed, please
refer to the file DEPENDENCIES for further details. Make sure to edit
the location of these packages in perldl.conf if you have them in non-
standard locations.

If you would like to save an edited perldl.conf for future builds just
copy it as ~/.perldl.conf into your home directory where it will be
picked up automatically during the PDL build process.

If you still can't make it work properly please submit a bug report
including detailed information on the problems you encountered to the
perldl mailing list ( perldl AT jach.edu , see also above).
Response is often rapid.

Q: 4.2 Are there configuration files for PDL I have to edit?

Most users should not have to edit any configuration files manually.
However, in some cases you might have to supply some information about
akwardly placed include files/libraries or you might want to explicitly
disable building some of the optional PDL modules. Check the files
INSTALL and perldl.conf for details.

If you had to manually edit perldl.conf and are happy with the results
you can keep the file handy for future reference. Place it in
~/.perldl.conf where it will be picked up automatically or use " perl
Makefile.PL PDLCONF=your_file_name" next time you build PDL.

Q: 4.3 Do I need other software for successfull operation?

For the basic PDL functionality you don't need any additional software.
However, some of the optional PDL modules included in the distribution
(notably most graphics and some I/O modules) require certain other
libraries/programs to be installed. Check the file DEPENDENCIES in the
distribution for details and directions on how to get these.

Q: 4.4 PDL compilation ends with " Error: PL_na not declared" or
similar

You have probably upgraded perl to 5.6 and tried to recompile an old
version of PDL. The solution to this problem is to upgrade to a version
(>2.005) which should have this fixed.

If the latest version of PDL does not fix this problem for you, and you
have made sure your old installation is not interfering, you should
post a message to the mailing-list.

BINARY DISTRIBUTIONS
Q: 4.5 What binary distributions are available?

Information about binary distributions of PDL can be found on
http://pdl.perl.org . At present there are binary distributions of PDL
for Linux (RedHat and Debian), FreeBSD and Windows, though they might
not be the most recent version. If someone is interested in providing
binary distributions for other architectures, that would be very
welcome. Let us know on the pdl-porters AT jach.edu mailing list.
Also check your Linux distibution's package manager as many now include
PDL.

Q: 4.6 Does PDL run on Linux? (And what about packages?)

Yes, PDL does run on Linux and indeed much of the development has been
done under Linux. On http://pdl.perl.org you can find links to packages
for some of the major distributions. Also check your distribution's
package manager (yum, apt, urpmi, ...) as PDL is now found by many of
these.

Q: 4.7 Does PDL run under Windows?

PDL builds fine on Win32 using MinGW or Microsoft compilers. See the
Win32/INSTALL file for details. Other compilers have not been
tested--input is welcome. A main worry on Windows platforms is the
lack of a good graphics interface, any help with this would be very
welcome.

There is also a distribution of PDL through ActiveState's ppm, though
it might not always be the latest version.

CVS AND ON-GOING DEVELOPMENT
Q: 4.8 Can I get PDL via CVS?

Yes, as of December 1999, PDL is available at the CVS repository on
http://www.sourceforge.net . The tree is updated by developers who have
accounts on Sourceforge and snapshots of the tree are released regu-
larly by the pumpkin holder (the pumpking).

If you wish to access the CVS repository and install PDL from there all
you need are two simple commands, however make sure you read some of
the documentation on Sourceforge as well for full information, but the
basic command is case sensitive and is:

cvs -d:pserver:anonymous AT pdl.net:/cvsroot/pdl login
cvs -z3 -d:pserver:anonymous AT pdl.net:/cvsroot/pdl co PDL

When prompted for a password just press the Enter key. Note however
that the CVS tree is to be considered a development release and as such
you are very welcome to try it out, but it is not recommended for mis-
sion critical use and might crash unexpectedly.

Q: 4.9 I had a problem with the CVS version, how do I check if some-
one has submitted a patch?

The Sourceforge system contains a patch-manager which contains patches
that have not yet been applied to the distribution. This can be
accessed by first accessing the Sourceforge web site and search for
PDL. This will show you the project page for PDL and will give you
access to the Patch manager.

In addition, if you are not subscribing to the mailing list, check the
archive of the " pdl-porters" and " perldl" mailing lists.

Q: 4.10 I have gotten developer access to CVS, but I have trouble
committing uploads.

The first you should do is to read the Sourceforge documentation and
learn the basics about CVS. But assuming you know this here is a quick
intro from Karl Glazebrook:

Delete your entire CVS directory structure and START AGAIN
(there is state)

In a clean directory:

setenv CVS_RSH ssh
setenv CVSROOT kgb AT pdl.net:/cvsroot/pdl

cvs co PDL

You will need to type your password. every time you issue a cvs
command. there is no way around this if you use non-anon
access and you can't mix the two.

However cvs commits will now work and write back to the server.

You will continue to have to type your password until you upload
a key to the sourcefourge web page. Once you have done this it
becomes painless.

PDL JARGON
Q: 5.1 What is threading (is PDL a newsreader) ?

Unfortunately, in the context of PDL the term threading can have two
different (but related) meanings:

o When mentioned in the INSTALL directions and possibly during the
build process we have the usual computer science meaning of multi-
threading in mind (useful mainly on multiprocessor machines or
clusters)

o PDL threading of operations on piddles (as mentioned in the index-
ing docs) is the iteration of a basic operation over appropriate
subslices of piddles, e.g. the inner product " inner $a, $b" of a
(3) pdl $a and a (3,5,4) pdl $b results in a (5,4) piddle where
each value is the result of an inner product of the (3) pdl with a
(3) subslice of the (3,5,4) piddle. For details check PDL::Index-
ing

PDL threading leads naturally to potentially parallel code which can
make use of multithreading on multiprocessor machines/networks; there
you have the connection between the two types of use of the term.

Q: 5.2 What is a piddle?

Well, PDL scalar variables (which are instances of a particular class
of perl objects, i.e. blessed thingies (see "man perlobj" )) are in
common PDL parlance often called piddles (for example, check the mail-
ing list archives). Err, clear? If not, simply use the term piddle
when you refer to a PDL variable (an instance of a PDL object as you
might remember) regardless of what actual data the PDL variable con-
tains.

TECHNICAL QUESTIONS
Q: 6.1 What is perldl?

Sometimes perldl is used as a synonym for PDL. Strictly speaking, how-
ever, the name perldl is reserved for the little shell that comes with
the PDL distribution and is supposed to be used for the interactive
prototyping of PDL scripts. For details check perldl.

Q: 6.2 How do I get online help for PDL?

Just type " help" (shortcut = "?") at the " perldl" prompt and proceed
from there. Another useful command is the " apropos" (shortcut = "??")
command. Also try the " demo" command in the perldl shell if you are
new to PDL.

MANIPULATION OF PIDDLES
Q: 6.3 I want to access the third element of a pdl but $a[2] doesn't
work ?!

See answer to the next question why the normal perl array syntax
doesn't work for pdls.

Q: 6.4 The docs say pdls are some kind of array. But why doesn't the
perl array syntax work with pdls then ?

Ok, you are right in a way. The docs say that pdls can be thought of
arrays. More specifically, it says ( PDL::Impatient ):

I find when using perlDL it is most useful to think of
standard perl @x variables as "lists" of generic
"things" and PDL variables like $x as
"arrays" which can be contained in lists or
hashes.

So, while pdls can be thought of as some kind of multi-dimensional
array they are not arrays in the perl sense. Rather, from the point of
view of perl they are some special class (which is currently imple-
mented as an opaque pointer to some stuff in memory) and therefore need
special functions (or 'methods' if you are using the OO version) to
access individual elements or a range of elements. The functions/meth-
ods to check are " at" / " set" (see the section 'Sections' in
PDL::Impatient ) or the powerful " slice" function and friends (see
PDL::Slices and PDL::Indexing ).

Finally, to confuse you completely, you can have perl arrays of pdls,
e.g. $spec[3] can refer to a pdl representing ,e.g, a spectrum, where
$spec[3] is the fourth element of the perl list (or array ;) @spec .
This may be confusing but is very useful !

Q: 6.5 How do I concatenate piddles?

Most people will try to form new piddles from old piddles using some
variation over the theme: " $a = pdl([$b, 0, 2])" , but this does not
work. The way to concatenate piddles is to use the function " cat" (see
also " append" and " glue"). Similarly you can split piddles using the
command " dog" .

Q: 6.6 Sometimes I am getting these strange results when using
inplace operations?

This question is related to the " inplace" function. From the documen-
tation (see PDL::Impatient):

Most functions, e.g. log(), return a result which is
a transformation of their argument. This makes for
good programming practice. However many operations can
be done "in-place" and this may be required when large
arrays are in use and memory is at a premium. For these
circumstances the operator inplace() is provided which
prevents the extra copy and allows the argument to be
modified. e.g.:

$x = log($array); # $array unaffected
log( inplace($bigarray) ); # $bigarray changed in situ

And also from the doc !!:

Obviously when used with some functions which can
not be applied in situ (e.g. convolve()) unexpected
effects may occur!

Check the list of PDL functions at the end of PDL.pod which points out
" inplace" -safe functions.

Q: 6.7 What is this strange usage of the string concatenation opera-
tor " .=" in PDL scripts?

See next question on assignment in PDL.

Q: 6.8 Why are there two different kinds of assignment in PDL ?

This is caused by the fact that currently the assignment operator " ="
allows only restricted overloading. For some purposes of PDL it turned
out to be necessary to have more control over the overloading of an
assignment operator. Therefore, PDL peruses the operator " .=" for cer-
tain types of assignments.

Q: 6.9 How do I set a set of values in a piddle?

With versions of Perl prior to 5.6 this has to be done using a tempo-
rary variable.

perldl> $a = sequence(5); p $a
[0 1 2 3 4]
perldl> $tmp = $a->slice('1:2'); p $tmp;
[1 2]
perldl> $tmp .= pdl([5, 6]); # Note .= !!
perldl> p $a
[0 5 6 3 4]

This can also be made into one expression, which is often seen in PDL
code:

perldl> ($tmp = $a->slice('1:2')) .= pdl([5,6])
perldl> p $a
[0 5 6 3 4]

In Perl 5.6 this assignment can be simplified using lvalue subroutines,
and this is now incorporated into PDL by requiring at least Perl 5.6.

Q: 6.10 Can I use a piddle in a conditional expression?

Yes you can, but not in the way you probably tried first. It is not
possible to use a piddle directly in a conditional expression since
this is usually poorly defined. Instead PDL has two very useful func-
tions: " any" and " all" . Use these to test if any or all elements in
a piddle fulfils some criterion:

perldl> $a=pdl ( 1, -2, 3);
perldl> print '$a has at least one element < 0' if (any $a < 0);
$a has at least one element < 0

perldl> print '$a is not positive definite' unless (all $a > 0);
$a is not positive definite

Q: 6.11 Logical operators and piddles - '||' and ' & & ' doesn't
work!

It is a common problem that you try to make a mask array or something
similar using a construct such as

$mask = which($piddle > 1 && $piddle < 2);

This does not work! What you are looking for is the bitwise logical
operators '|' and '&' which work on an element-by-element basis. So it
is really very simple: Do not use logial operators on multi-element
piddles since that really doesn't make sense, instead write the example
as:

$mask = which($piddle > 1 & $piddle < 2);

which works correctly.

ADVANCED TOPICS
Q: 6.12 What is a null pdl ?

" null" is a special token for 'empty piddle'. A null pdl can be used
to flag to a PDL function that it should create an appropriately sized
and typed piddle. Null piddles can be used in places where a PDL func-
tion expects an output or temporary argument. Output and temporary
arguments are flagged in the signature of a PDL function with the "
[o]" and " [t]" qualifiers (see next question if you don't know what
the signature of a PDL function is). For example, you can invoke the
" sumover" function as follows:

sumover $a, $b=null;

which is equivalent to

$b = sumover $a;

If this seems still a bit murky check PDL::Indexing and PDL::PP for
details about calling conventions, the signature and threading (see
also below).

Q: 6.13 What is the signature of a PDL function ?

The signature of a function is an important concept in PDL. Many (but
not all) PDL function have a signature which specifies the arguments
and their (minimal) dimensionality. As an example, look at the signa-
ture of the " maximum" function:

'a(n); [o] b;'

this says that " maximum" takes two arguments, the first of which is
(at least) one-dimensional while the second one is zero-dimensional and
an output argument (flagged by the " [o]" qualifier). If the function
is called with pdls of higher dimension the function will be repeatedly
called with slices of these pdls of appropriate dimension(this is
called threading in PDL).

For details and further explanations consult PDL::Indexing and PDL::PP
.

Q: 6.14 How can I subclass (inherit from) piddles?

The short answer is: read PDL::Objects (e.g. type " help PDL::Objects"
in the perldl shell).

The longer answer (extracted from PDL::Objects ): Since a PDL object is
an opaque reference to a C struct, it is not possible to extend the PDL
class by e.g. extra data via subclassing (as you could do with a hash
based perl object). To circumvent this problem PDL has built-in sup-
port to extent the PDL class via the has-a relation for blessed
hashes. You can get the HAS-A behave like IS-A simply in that you
assign the PDL object to the attribute named " PDL" and redefine the
method initialize(). For example:

package FOO;

@FOO::ISA = qw(PDL);
sub initialize {
my $class = shift;
my $self = {
creation_time => time(), # necessary extension :-)
PDL => PDL->null, # used to store PDL object
};
bless $self, $class;
}

For another example check the script t/subclass.t in the PDL distribu-
tion.

Q: 6.15 What on earth is this dataflow stuff ?

Dataflow is an experimental project that you don't need to concern
yourself with (it should not interfere with your usual programming).
However, if you want to know, have a look at PDL::Dataflow . There are
applications which will benefit from this feature (and it is already at
work behind the scenes).

Q: 6.16 What is PDL::PP?

Simple answer: PDL::PP is both a glue between external libraries and
PDL and a concise language for writing PDL functions.

Slightly longer answer: PDL::PP is used to compile very concise defini-
tions into XSUB routines implemented in C that can easily be called
from PDL and which automatically support threading, dataflow and other
things without you having to worry about it.

For further details check PDL::PP and the section below on Extensions
of PDL.

Q: 6.17 What happens when I have several references to the same PDL
object in different variables (cloning, etc?) ?

Piddles behave like perl references in many respects. So when you say

$a = pdl [0,1,2,3];
$b = $a;

then both $b and $a point to the same object, e.g. then saying

$b++;

will *not* create a copy of the original piddle but just increment in
place, of which you can convince yourself by saying

print $a;
[1 2 3 4]

This should not be mistaken for dataflow which connects several *dif-
ferent* objects so that data changes are propagated between the so
linked piddles (though, under certain circumstances, dataflown piddles
can share physically the same data).

It is important to keep the "reference nature" of piddles in mind when
passing piddles into subroutines. If you modify the input pdls you mod-
ify the original argument, not a copy of it. This is different from
some other array processing languages but makes for very efficient
passing of piddles between subroutines. If you do not want to modify
the original argument but rather a copy of it just create a copy
explicitly (this example also demonstrates how to properly check for an
explicit request to process inplace, assuming your routine can work
inplace):

sub myfunc {
my $pdl = shift;
if ($pdl->is_inplace)
{$pdl->set_inplace(0)}
else # modify a copy by default
{$pdl = $pdl->copy}
$pdl->set(0,0);
return $pdl;
}

MISCELLANEOUS
Q: 6.18 What I/O formats are supported by PDL ?

The current versions of PDL already support quite a number of different
I/O formats. However, it is not always obvious which module implements
which formats. To help you find the right module for the format you
require, here is a short list of the current list of I/O formats and a
hint in which module to find the implementation:

o A home brew fast raw (binary) I/O format for PDL is implemented by
the FastRaw module

o The FlexRaw module implements generic methods for the input and
output of `raw' data arrays. In particular, it is designed to read
output from FORTRAN 77 UNFORMATTED files and the low-level C write
function, even if the files are compressed or gzipped.

It is possible that the FastRaw functionality will be included in
the FlexRaw module at some time in the future.

o FITS I/O is implemented by the wfits/rfits functions in
PDL::IO::Misc.

o Ascii file I/O in various formats can be achieved by using the "
rcols" and " rgrep" functions, also in PDL::IO::Misc.

o PDL::IO::Pic implements an interface to the netpbm/pbm+ filters to
read/write several popular image formats; also supported is output
of image sequences as MPEG movies.

o On CPAN you can find the PDL-NetCDF module that works with the cur-
rent released version of PDL 2.4.3.

For further details consult the documentation in the individual mod-
ules.

Q: 6.19 How can I stack a set of 2D arrays (images) into a 3D pid-
dle?

Assuming all arrays are of the same size and in some format recognised
by rpic (see PDL::IO::Pic ) you could say:

use PDL::IO::Pic;
@names = qw/name1.tif .... nameN.tif/; # some file names
$dummy = PDL->rpic($names[0]);
$cube = PDL->zeroes($dummy->type,$dummy->dims,$#names+1); # make 3D piddle
for (0..$#names)
{($tmp = $cube->slice(":,:,($_)")) .= PDL->rpic($names[$_])}

The for loop reads the actual images into a temporary 2D piddle whose
values are then assigned (using the overloaded " .=" operator) to the
approriate slices of the 3D piddle $cube .

Q: 6.20 Where are testfiles for the graphics modules?

This answer applies mainly to PDL::Graphics::TriD (PDL's device inde-
pendent 3D graphics model) which is the trickiest one in this respect.
You find some test scripts in Demos/TriD in the distribution. After you
have built PDL just change to that directory and try

perl -Mblib <testfile>

where " < testfile "> ; should match the pattern " test[3-9].p" and
watch the results. Some of the tests should bring up a window where you
can control (twiddle) the 3D objects with the mouse. Try using MB1 for
turning the objects in 3D space, MB3 to zoom in and out, and 'q' to
advance to the next stage of the test.

If you have a VRML viewer plugin for netscape you can also try "
tvrml*.p" for PDL generated dynamic VRML.

Some demos of 3D graphics with PDL can also be invoked using the "
demo" command within the perldl shell.

Q: 6.21 What is TriD or PDL::TriD or PDL::Graphics::TriD?

Questions like this should be a thing of the past with the PDL online
help system in place. Just try (after installation):

un*x> perldl
perldl> apropos trid

Check the output for promising hits and then try to look up some of
them, e.g.

perldl> help PDL::Graphics::TriD

Note that case matters with " help" but not with " apropos" .

Q: 6.22 PGPLOT does not write out PNG files.

There are a few sources of trouble with PGPLOT and PNG files. First,
when compiling the pgplot libraries, make sure you uncommented the PNG
entries in the drivers.list file. Then when running 'make' you probably
got an error like

"make: *** No rule to make target `png.h', needed by `pndriv.o'.
Stop."

To fix this, find the line in the 'makefile' that starts with
'pndriv.o:' (it's near the bottom). Change, for example, ./png.h to
/usr/include/png.h, if that is where your header files are (you do have
the libpng and libz devel packages, don't you?). Do this for all four
entries on that line, then go back and run "make".

Second, if you already have the PGPLOT Perl module and PDL installed,
you probably tried to write out a png file and got fatal error message
like:

"undefined symbol: png_create_write_struct"

This is because the PGPLOT perl module does not automatically link
against the png and z libraries. So when you are installing the PGPLOT
perl module (version 2.19) from CPAN, don't do "install PGPLOT", but
just do "get PGPLOT". Then exit from CPAN and manually install PGPLOT,
calling the makefile thusly:

"perl Makefile.PL EXLIB=png,z EXDIR=/usr/lib"

assuming that there exist files such as /usr/lib/libpng.so.*,
/usr/lib/libz.so.*. Then do the standard "make;make test;make install;"
sequence. Now you can write png files from PDL!

EXTENSIONS OF PDL
Q: 7.1 I am looking for a package to do XXX in PDL. Where shall I
look for it?

The first stop is again " perldl" or the PDL documentation. There is
already a lot of functionality in PDL which you might be aware of. The
easiest way to look for functionality is to use the " apropos" command:

perldl> apropos 'integral'
ceil Round to integral values in floating-point format
floor Round to integral values in floating-point format
intover Project via integral to N-1 dimensions
rint Round to integral values in floating-point format

Since the apropos command is no sophisticated search engine make sure
that you search on a couple of related topics and use short phrases.

However there is a good chance that what you need is not part of the
PDL distribution. You are then well advised to check out
http://pdl.perl.org where there is a list of packages using PDL. If
that does not solve your problem, ask on the mailing-list, if nothing
else you might get assistance which will let you interface your package
with PDL yourself, see also the next question.

Q: 7.2 Can I access my C/Fortran library routines in PDL?

Yes, you can, in fact it is very simple for many simple applications.
What you want is the PDL pre-prosessor PP (PDL::PP ). This will allow
you to make a simple interface to your C routine.

The two functions you need to learn (at least first) are " pp_def"
which defines the calling interface to the function, specifying input
and output parameters, and contains the code that links to the external
library. The other command is " pp_end" which finishes the PP defini-
tions. For details see the PDL::PP man-page, but we also have a worked
example here.

double eight_sum(int n)
{
int i;
double sum, x;

sum = 0.0; x=0.0;
for (i=1; i<=n; i++) {
x++;
sum += x/((4.0*x*x-1.0)*(4.0*x*x-1.0));
}
return 1.0/sum;
}

We will here show you an example of how you interface C code with PDL.
This is the first example and will show you how to approximate the num-
ber 8...

The C code is shown above and is a simple function returning a double,
and expecting an integer - the number of terms in the sum - as input.
This function could be defined in a library or, as we do here, as an
inline function.

We will postpone the writing of the Makefile till later. First we will
construct the " .pd" file. This is the file containing PDL::PP code. We
call this " eight.pd" .

#
# pp_def defines a PDL function.
#
pp_addhdr (
'
double eight_sum(int n)
{
int i;
double sum, x;

sum = 0.0; x=0.0;
for (i=1; i<=n; i++) {
x++;
sum += x/((4.0*x*x-1.0)*(4.0*x*x-1.0));
}
return 1.0/sum;

}
');

pp_def (
'eight',
Pars => 'int a(); double [o]b();',
Code => '$b()=eight_sum($a());'
);

# Always make sure that you finish your PP declarations with
# pp_done

pp_done();

A peculiarity with our example is that we have included the entire code
with " pp_addhdr" instead of linking it in. This is only for the
purposes of example, in a typical application you will use " pp_addhdr"
to include header files. Note that the argument to " pp_addhdr" is
enclosed in quotes.

What is most important in this example is however the " pp_def" com-
mand. The first argument to this is the name of the new function eight
, then comes a hash which the real meat:

o This gives the input parameters (here " a" ) and the output parame-
ters (here " b" ). The latter are indicated by the " [o]" speci-
fier. Both arguments can have a type specification as shown here.

Many variations and further flexibility in the interface can be
specified. See the manpage for details.

o This switch contains the code that should be executed. As you can
see this is a rather peculiar mix of C and Perl, but essentially it
is just as you would write it in C, but the variables that are
passed from PDL are treated differently and have to be referred to
with a preceding '$'.

There are also simple macros to pass pointers to data and to obtain
the values of other Perl quantities, see the manual page for fur-
ther details.

Finally note the call to " pp_done()" at the end of the file. This is
necessary in all PP files.

Ok. So now we have a file with code that we dearly would like to use in
Perl via PDL. To do this we need to compile the function, and to do
that we need a Makefile.

use PDL::Core::Dev;
use ExtUtils::MakeMaker;
PDL::Core::Dev->import();

$package = ["eight.pd",Eight,PDL::Eight];
%hash = pdlpp_stdargs($package);

WriteMakefile( %hash );

sub MY::postamble {pdlpp_postamble($package)};

The code above should go in a file called Makefile.PL, which should
subsequently be called in the standard Perl way: " perl Makefile.PL" .
This should give you a Makefile and running " make" should compile the
module for you and " make install" will install it for you.

Q: 7.3 How can I interface package XXX in PDL?

This question is closely related to the previous one, and as we said
there, the PDL::PP pre-processor is the standard way of interfacing
external packages with PDL. The most usual way to use PDL::PP is to
write a short interface routine, see the PDL::PP manpage and the answer
to the previous question for examples.

However it is also possible to interface a package to PDL by re-writing
your function in PDL::PP directly. This can be convenient in certain
situations, in particular if you have a routine that expects a function
as input and you would like to pass the function a Perl function for
convenience.

The PDL::PP manpage is the main source of information for writing
PDL::PP extensions, but it is very useful to look for files in the dis-
tribution of PDL as many of the core functions are written in PDL::PP.
Look for files that end in " .pd" which is the generally accepted suf-
fix for PDL::PP files. But we also have a simple example here.

The following example will show you how to write a simple function that
automatically allows threading. To make this concise the example is of
an almost trivial function, but the intention is to show the basics of
writing a PDL::PP interface.

We will write a simple function that calculates the minimum, maximum
and average of a piddle. On my machine the resulting function is 8
times faster than the built-in function " stats" (of course the latter
also calculates the median).

Let's jump straight in. Here is the code (from a file called " quick-
stats.pd" )

#
pp_def('quickstats',
Pars => 'a(n); [o]avg(); [o]max(); [o]min()',
Code => '$GENERIC(a) curmax, curmin;
$GENERIC(a) tmp=0;
loop(n) %{
tmp += $a();
if (!n || $a() > curmax) { curmax = $a();}
if (!n || $a() < curmin) { curmin = $a();}
%}
$avg() = tmp/$SIZE(n);
$max() = curmax;
$min() = curmin;
'
);

pp_done();

The above might look like a confusing mixture of C and Perl, but behind
the peculiar syntax lies a very powerful language. Let us take it line
by line.

The first line declares that we are starting the definition of a PDL:PP
function called " quickstats" .

The second line is very important as it specifies the input and output
parameters of the function. a(n) tells us that there is one input
parameter that we will refer to as " a" which is expected to be a vec-
tor of length n (likewise matrices, both square and rectangular would
be written as " a(n,n)" and " a(n,m)" respectively). To indicate that
something is an output parameter we put " [o]" in front of their names,
so referring back to the code we see that avg, max and min are three
output parameters, all of which are scalar (since they have no dimen-
sional size indicated.

The third line starts the code definition which is essentially pure C
but with a couple of convenient functions. $GENERIC is a function
that returns the C type of its argument - here the input parameter a.
Thus the first two lines of the code section are variable declarations.

The loop(n) construct is a convenience function that loops over the
dimension called n in the parameter section. Inside this loop we calcu-
late the cumulative sum of the input vector and keep track of the maxi-
mum and minimum values. Finally we assign the resulting values to the
output parameters.

Finally we finish our function declaration with " pp_done()" .

To compile our new function we need to create a Makefile, which we will
just list since its creation is discussed in an earlier question.

use PDL::Core::Dev;
use ExtUtils::MakeMaker;
PDL::Core::Dev->import();

$package = ["quickstats.pd",Quickstats,PDL::Quickstats];
%hash = pdlpp_stdargs($package);

WriteMakefile( %hash );

sub MY::postamble {pdlpp_postamble($package)};

An example Makefile.PL

Our new statistic function should now compile using the tried and
tested perl way: " perl Makefile.PL; make" .

You should experiment with this function, changing the calculations and
input and output parameters. In conjunction with the PDL::PP manpage
this should allow you to quickly write more advanced routines directly
in PDL::PP.

THE WHO WHEN WHAT
CHANGES
o
o General minor update: mailing list info, links, version, date,
some text.

o Removed FAQ maintainer.

o
o markers for alpha stage functionality removed

o restructured description

o development/support of PDL

o PDL and online help

o subclassing piddles

o new INSTALLATION section

o how to stack 2D piddles - > 3D piddle

o questions regarding TriD

o
o use of perl5.004 is now required

o PDL I/O formats

o piddles behave like perl references

o null PDL's and output arguments

o signature

o
o questions about pdls and perl array syntax

o added requirement for C compiler in answer to 'what
machines...' question

o PDL jargon section

o piddles

o
o upgraded released/alpha version numbers

o added another WYANDL reason

o split into perldl/pdl-porters mailing lists

o
o initial revision

BUGS
If you find any inaccuracies in this document (or disfunctional URLs)
please report to the perldl mailing list perldl AT jach.edu.

ACKNOWLEDGEMENTS
Achim Bohnet (ach AT mpe.de ) for suggesting CoolHTML as a prettypod-
der (although we have switched to XML now) and various other improve-
ments. Suggestions for some questions were taken from Perl Faq and
adapted for PDL.

CONTRIBUTORS
Many people have contributed or given feedback on the current version
of the FAQ, here is an incomplete list of individuals whose contribu-
tions or posts to the mailing-list have improved this FAQ at some point
in time alphabetically listed by first name: Christian Soeller, Doug
Burke, Doug Hunt, Frank Schmauder, Jarle Brinchmann, John Cerney, Karl
Glazebrook, Kurt Starsinic, Thomas Yengst, Tuomas J. Lukka.

AUTHOR AND COPYRIGHT
This document emerged from a joint effort of several PDL developers
(Karl Glazebrook ( kgb AT aaoepp.au ), Tuomas J. Lukka (
lukka AT iki.fi ), Christian Soeller ( c.soeller AT auckland.nz )) to com-
pile a list of the most frequently asked questions about PDL with
answers. Permission is granted for verbatim copying (and formatting)
of this material as part of PDL. Permission is explicitly not granted
for distribution in book or any corresponding form. Ask on the PDL
mailing list perldl AT jach.edu if some of the issues covered in
here are unclear.

perl v5.8.8 2003-05-21 FAQ(1p)