PDL::FAQ

FAQ(Q) User Contributed Perl Documentation FAQ(Q)

NAME
PDL::FAQ - Frequently asked questions about PDL

VERSION
Current FAQ version: 0.6

DESCRIPTION
This is version 0.6 of the PDL FAQ, a collection of fre-
quently asked questions about PDL - the Perl Data Lan-
guage.

ABOUT THIS DOCUMENT
Q: 1.1 Where to find this document

You can find the latest version of this document at
http://pdl.perl.org/faq.html . This FAQ will be monthly
posted to the PDL mailing list perldl@jach.hawaii.edu .

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. Similarly,
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 maintainer know if it
isn't. For more general information explicit acknowledge-
ment is not made in the text, but rather there is an
incomplete list of contributors at the end of this docue-
ment. 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@jach.hawaii.edu or to
the FAQ maintainer Jarle Brinchmann ( jarle@astro.ox.ac.uk
). 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 is hoped to eventually provide tons of useful function-
ality 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, MATLAB and similar packages. How-
ever, 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 provided through the PDL mailing list (
perldl@jach.hawaii.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 commu-
nity. 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@jach.hawaii.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 himself 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 - > better debugging, easily
adaptable to your own needs, extensible for your pur-
poses, etc... In comparison with commercial packages
such as Matlab and IDL this is of considerable impor-
tance 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 scien-
tific/numeric data analysis languages it has been
designed using the language features of a proven lan-
guage instead of having grown into existence from
scratch defining the control structures while features
were added during development (leading 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 features of Perl at his hand, right from the
start. This includes regular expressions, associative
arrays (hashes), well designed interfaces to the oper-
ating system, network, etc. Experience has shown that
even in mainly numerically oriented programming it is
often extremely handy if you have easy access to pow-
erful semi-numerical or completely non-numerical func-
tionality 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, per-
haps 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 expres-
sions, hashes, object modules) immensely facilitated
development and implementation 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 redun-
dancy 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 pos-
sible: 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 computer features, e.g. vector capabilities/par-
allel 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 (neces-
sarily selective) list of key features:

PDL is well suited for matrix computations, general han-
dling of multidimensional data, image processing, general
scientific computation, numerical applications. It sup-
ports 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), graphics 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. Further-
more, much of PDL is written in perl (+ some core func-
tionality that is written in C). PDL programs are (syntac-
tically) just perl scripts that happen to use some of the
functionality 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.004 of Perl, version 5.004_4 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.com 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 sup-
port 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 distribution availabe, see "Binary
distributions" below.

If you can (or cannot) get PDL working on a new (previ-
ously unsupported) platform we would like to hear about
it. Please, report your success/failure to the PDL mailing
list at perldl@jach.hawaii.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 Comprehen-
sive Perl Archive Network , or CPAN. This archive con-
tains not only the PDL distribution 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
ftp://ftp.funet.fi . You can find a more local CPAN site
by getting the file /pub/languages/perl/CPAN/MIRRORS from
ftp://ftp.funet.fi . Alternatively, you can point your Web
browser at http://www.perl.com and use its CPAN multiplex
service. Within CPAN you find the latest released version
of PDL in the directory CPAN/modules/by-module/PDL/.
Another site that has the latest PDL distribution is
http://pdl.perl.org . Thanks to the efforts of Frossie (
frossie@jach.hawaii.edu ) there is now a mirror site in
the US at http://www.jach.hawaii.edu/~frossie/pdl-mirror/

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

We are delighted to be able to give you the nicest possi-
ble 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::Intro" will
lead the way to other PDL manual pages. In any case (i.e.
also on non-unixes) " perldoc PDL::Intro" should 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 documenta-
tion. Even better, you can immediately try your newly
acquired knowledge about PDL by issuing PDL/perl commands
directly at the command line. To illustrate 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. A good point to start is
http://www.perl.com .

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).

Thanks to the efforts of Frossie ( frossie@jach.hawaii.edu
) there is now a mirror site in the US at
http://www.jach.hawaii.edu/~frossie/pdl-mirror/ If you are
interested in PDL in general you can join the PDL mailing
list perldl@jach.hawaii.edu . This is a forum to discuss
programming issues in PDL, report bugs, seek assistance
with PDL related problems, etc. To subscribe, send a mes-
sage to perldl-request@jach.hawaii.edu containing a string
in the following format:

subscribe me@my.email.address

where you should replace the string me@my.email.address
with your email address. Past messages can be retrieved in
digest format by anonymous ftp from
ftp://ftp.jach.hawaii.edu/pub/ukirt/frossie/pdlp/ . A
searchable archive and a hypertext version of the traffic
on this list can be found at
http://www.xray.mpe.mpg.de/mailing-lists/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@jach.hawaii.edu . To subscribe,
send a message to pdl-porters-request@jach.hawaii.edu con-
taining a string in the following format:

subscribe me@my.email.address

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.6 of 01/06/2000 ) the
latest released version is 2.006 . The latest versions
should always be available from a CPAN mirror site near
you (see above for info on where to get PDL).

The most current version of PDL can be obtained from the
CVS repository see ""CVS availability of PDL"" below.

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@jach.hawaii.edu . To subscribe, send a message
to pdl-porters-request@jach.hawaii.edu containing a string
in the following format:

subscribe me@my.email.address

where you should replace the string me@my.email.address
with your email address. You can also read past and cur-
rent mails in the searchable hypertext version of the
mailing list at http://www.xray.mpe.mpg.de/mail-
ing-lists/pdl-porters/ . 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 ver-
sion 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 at whether this bug has already been dis-
cussed. If you still haven't found any explanations you
can post a bug report to perldl@jach.hawaii.edu .

INSTALLATION

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

First make sure you have read the file INSTALL in the dis-
tribution. 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 configuration 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@jach.hawaii.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 refer-
ence. Place it in ~/.perldl.conf where it will be picked
up automatically or use " perl Makefile.PL PDL-
CONF=your_file_name" next time you build PDL.

Q: 4.3 Do I need other software for successfull opera-
tion?

For the basic PDL functionality you don't need any addi-
tional software. However, some of the optional PDL mod-
ules included in the distribution (notably most graphics
and some I/O modules) require certain other libraries/pro-
grams 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 recom-
pile 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 mail-
ing-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 dis-
tributions of PDL for Linux (RedHat and Debian), FreeBSD
and Windows. If someone is interested in providing binary
distributions for other architectures, that would be very
welcome. Let us know on the pdl-porters@jach.hawaii.edu
mailing list.

Q: 4.6 Does PDL run on Linux? (And what about pack-
ages?)

Yes, PDL does run on Linux and indeed much of the develop-
ment has been done under Linux. On http://pdl.perl.org you
can find links to Debian packages, as well as the more
actively updated RedHat packages. These should also work
with Mandrake, and can possibly be converted to Debian
using " alien" .

Q: 4.7 Does PDL run under Windows?

To some extent is probably the fairest answer. There is no
official effort to port PDL to Windows with each release
of the software, and a volunteering effort would be much
appreciated. However a port of ( 2.001 ) does already
exist thanks to Christian Soeller. A main worry on Win-
dows platforms is the lack of a good graphics interface,
any help with this would be very welcome.

It is also important to note that there is no distribution
of PDL through ActiveState's ppm. Such a compilation would
be very welcome!

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 regularly by the pump-
kin 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 Source-
forge as well for full information, but the basic command
is:

cvs -d:pserver:anonymous@cvs.PDL.sourceforge.net:/cvsroot/PDL login
cvs -z3 -d:pserver:anonymous@cvs.PDL.sourceforge.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 mission critical
use and might crash unexpectedly.

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

The Sourceforge system contains a patch-manager which con-
tains patches that have not yet been applied to the dis-
tribution. 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 mail-
inglist, 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 docu-
mentation 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@cvs.PDL.sourceforge.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.

Howevery cvs committs 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 sourcefourve 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 possible
during the build process we have the usual computer
science meaning of multithreading in mind (useful
mainly on multiprocessor machines or clusters)

o PDL threading of operations on piddles (as mentioned
in the indexing 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::Indexing"

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 par-
ticular class of perl objects, i.e. blessed thingies (see
"man perlobj" )) are in common PDL parlance often called
piddles (for example, check the mailing 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 contains.

TECHNICAL QUESTIONS
Q: 6.1 What is perldl?

Sometimes perldl is used as a synonym for PDL. Strictly
speaking, however, 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 the perldl man page.

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 spe-
cial class (which is currently implemented as an opaque
pointer to some stuff in memory) and therefore need spe-
cial functions (or 'methods' if you are using the OO ver-
sion) to access individual elements or a range of ele-
ments. The functions/methods 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 plds, e.g. $spec[3] can refer to a pdl repre-
senting ,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" . 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 documentation (see "PDL::Impatient" manpage):

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 con-
catenation operator " .=" 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 certain
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 temporary variable.

perldl> $a = sequence(e); 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 will be incorporated into PDL when
5.6 is more widespread.

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 condi-
tional expression since this is usually poorly defined.
Instead PDL has two very useful functions: " any" and "
all" . Use these to test if any or all elements in a pid-
dle 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 bit-
wise logical operators '|' and ' & ' which work on an ele-
ment-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 cre-
ate an appropriately sized and typed piddle. Null pid-
dles can be used in places where a PDL function 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 sig-
nature 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) dimen-
sionality. As an example, look at the signature of the "
maximum" function:

'a(a); [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 dimen-
sion(this is called threading in PDL).

For details and further explanations consult "PDL::Index-
ing" 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(w);
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 distribution.

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 definitions 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 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 *different* objects so that data changes are prop-
agated between the so linked piddles (though, under cer-
tain circumstances, dataflown piddles can share physically
the same data).

It is important to keep the " reference nature " of pid-
dles in mind when passing piddles into subroutines. If you
modify the input pdls you modify 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 mod-
ify 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(e)}
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 obvi-
ous 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 UNFOR-
MATTED 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 current released version of PDL 2.004.

For further details consult the documentation in the indi-
vidual modules.

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

Assuming all arrays are of the same size and in some for-
mat 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 over-
loaded " .=" 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 independent 3D graphics model) which is the tricki-
est 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[0-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 and MB3 to zoom in and out.

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::Graph-
ics::TriD?

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

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 " apro-
pos" .

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 documenta-
tion. There is already a lot of functionality in PDL which
you might be aware of. The easiest way to look for func-
tionality 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 inter-
face to your C routine.

The two functions you need to learn (at least first) are "
pp_def" which defines the calling interface to the func-
tion, 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 definitions.
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 number 8...

The C code is shown above and is a simple function return-
ing 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 func-
tion.

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" command. 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 parameters (here " b" ). The latter are indi-
cated by the " [o]" specifier. Both arguments can have
a type specification as shown here.

Many variations and further flexibility in the inter-
face 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 further 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 Make-
file 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 stan-
dard way of interfacing external packages with PDL. The
most usual way to use PDL::PP is to write a short inter-
face 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 PLD
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 conve-
nience.

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 distribution 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 suffix 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 mini-
mum, 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 " quickstats.pd" )

#
pp_def('quickstats',
Pars => 'a(a); [o]avg(); [o]max(); [o]min()',
Code => '$GENERIC(C) curmax, curmin;
$GENERIC(C) tmp=0;
loop(p) %{
tmp += $a();
if (!n || $a() > curmax) { curmax = $a();}
if (!n || $a() < curmin) { curmin = $a();}
%}
$avg() = tmp/$SIZE(E);
$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 defini-
tion 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(a) tells
us that there is one input parameter that we will refer to
as " a" which is expected to be a vector of length n
(likewise matrices, both square and rectangular would be
written as " a(n,n)" and " a(n,m)" respectively). To indi-
cate 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 dimensional size
indicated.

The third line starts the code definition which is essen-
tially 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(p) construct is a convenience function that
loops over the dimension called n in the parameter sec-
tion. Inside this loop we calculate the cumulative sum of
the input vector and keep track of the maximum and minimum
values. Finally we assign the resulting values to the out-
put 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 conjunc-
tion 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 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 disfunc-
tional URLs) please report to the perldl mailing list
perldl@jach.hawaii.edu or to the current FAQ maintainer
Jarle Brinchmann ( jarle@astro.ox.ac.uk ).

ACKNOWLEDGEMENTS
Achim Bohnet ( ach@mpe.mpg.de ) for suggesting CoolHTML as
a prettypodder (although we have switched to XML now) and
various other improvements. Suggestions for some questions
were taken from Perl Faq and adapted for PDL.

CONTRIBUTORS
Many people have contributed or given feedback on the cur-
rent version of the FAQ, here is an incomplete list of
individuals whose contributions or posts to the mailing-
list have improved this FAQ at some point in time alpha-
betically 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@aaoepp.aao.gov.au ),
Tuomas J. Lukka ( lukka@iki.fi ), Christian Soeller (
c.soeller@auckland.ac.nz )) to compile a list of the most
frequently asked questions about PDL with answers. Per-
mission 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. Email the current FAQ maintainer Jarle Brinchmann (
jarle@astro.ox.ac.uk ) or ask on the PDL mailing list
perldl@jach.hawaii.edu if some of the issues covered in
here are unclear.

perl v5.6.1 2000-06-02 FAQ(Q)

about this index... about Greenstone...