=head1 NAME

PDL::FAQ - Frequently asked questions about PDL

=head1 VERSION

Current FAQ version:  0.6


=head1 DESCRIPTION

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

=head1 ABOUT THIS DOCUMENT

=head2 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 .




=head2 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 acknowledgement 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@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.




=head1 GENERAL QUESTIONS

=head2 Q: 2.1    What is PDL ?  
  

PDL stands for 
I< 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
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,
MATLAB 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.




=head2 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 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@jach.hawaii.edu , see below). If you would like to join in the
ongoing efforts to improve PDL please join this list.




=head2 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:


=over 4

=item *

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

=item *

PDL is based on a powerful and well designed scripting
language: Perl. In contrast to other scientific/numeric data
analysis languages it has been designed using the language
features of a proven language 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).

=item *

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

=item *

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.

=item *

Integral language features of Perl (regular expressions,
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 generator/parser/pre-processor that generates
PDL functions from concise descriptions.

=item *

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

=over 4

=item *

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

=item *

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.



=back

All existing languages violate at least one of these rules.

=item *

As a project for the future PDL should be able to use super
computer 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.

=item *

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



=back




=head2 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 multidimensional 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), 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.




=head2 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
functionality implemented by the package 
"
PDL
"
;




=head2 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
I< 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 
I< 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 distribution availabe, see "Binary
distributions" below.

If you can (or cannot) get PDL working on a new (previously
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.




=head2 Q: 2.7    Where do I get it?  
  

PDL is available as source distribution in the 
I< Comprehensive Perl Archive Network> , or
CPAN.  This archive contains 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/ 



=head2 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.




=head1 GETTING HELP/MORE INFORMATION

=head2 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 
C< man> command. 
C< man PDL::Intro> will lead the way to other PDL manual pages.
In any case (i.e. also on non-unixes) 
C< 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 
C< perldl> shell. Just
type 
C< perldl> at your system prompt. Once you are inside the
C< perldl> shell type 
C< help> .  Using the 
C< help> and 
C< 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 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.




=head2 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:


=over 4

=item *

PDL distributions 

=item *

Online documentation 

=item *

Pointers to an HTML archive of the PDL mailing lists

=item *

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

=item *

News about recently added features, ported libraries,
etc.

=item *

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



=back

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 message to 
perldl-request@jach.hawaii.edu containing a string in the following format:

   
   	subscribe me@my.email.address
         

where you should replace the string 
I< 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 containing a string in the following format:

   
   	subscribe me@my.email.address
         

where you should replace the string 
I< 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/pdl-porters/ .

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




=head2 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 
L<""CVS availability of PDL""> below. 




=head2 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 
I< me@my.email.address> with your email
address.
You can also read past and current mails in the searchable hypertext
version of the mailing list at 
http://www.xray.mpe.mpg.de/mailing-lists/pdl-porters/ . We are
always looking for people to write code and/or documentation ;).




=head2 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 at  whether
this bug has already been discussed. If you still haven't found
any explanations you can post a bug report to 
perldl@jach.hawaii.edu .




=head1 INSTALLATION

=head2 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
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.




=head2 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 
C< perl Makefile.PL  PDLCONF=your_file_name> next time you build PDL.




=head2 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.




=head2 Q: 4.4   PDL compilation ends with C< 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.




=head1 BINARY DISTRIBUTIONS


=head2 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. 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. 




=head2 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 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 
C< alien> .




=head2 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
Windows 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!




=head1 CVS AND ON-GOING DEVELOPMENT


=head2 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 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:

    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.




=head2 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 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 mailinglist,
check the archive of the 
C< pdl-porters> and 
C< perldl> mailing lists.




=head2 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@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.
   	  





=head1 PDL JARGON

=head2 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:


=over 4

=item *

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)

=item *

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 
C< inner $a, $b> of a (3) pdl 
C< $a> and a (3,5,4) pdl 
C< $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
L<"PDL::Indexing"> 


=back

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. 




=head2 Q: 5.2    What is a piddle C< (;)>  ?  
  

Well, PDL scalar variables (which are instances of a particular class
of perl objects, i.e. blessed thingies 
(see 
L<"man perlobj"> )) are
in common PDL parlance often called 
I< piddles> (for example, check the
mailing list archives). Err, clear? If not, simply use the term
I< 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.




=head1 TECHNICAL QUESTIONS

=head2 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.




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

Just type 
C< help> (shortcut = "?") at
the 
C< perldl> prompt and proceed from
there. Another useful command is the 
C< apropos> (shortcut = "??") command.

Also try the 
C< demo> command in the perldl
shell if you are new to PDL.




=head1 MANIPULATION OF PIDDLES


=head2 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.




=head2 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 (
L<"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 
B< not> arrays in the perl sense. Rather,
from the point of view of perl they are some special class
(which is currently implemented 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/methods to check are 
C< at> /
C< set> (see
L<"the section 'Sections' in PDL::Impatient"> ) or the powerful 
C< slice> function and friends (see 
L<"PDL::Slices"> and 
L<"PDL::Indexing"> ).

Finally, to confuse you completely, you can have perl arrays
of plds, 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 ;) 
C< @spec> .  This may
be confusing but is very useful !




=head2 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: 
C< $a =  pdl([$b, 0, 2])> , but this does not work. The way to
concatenate piddles is to use the function 
C< cat> . Similarly you can split piddles
using the command 
C< dog> .




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

This question is related to the 
C< inplace> function. From the
documentation (see 
L<"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
C< inplace> -safe functions.




=head2 Q: 6.7    What is this strange usage of the string concatenation operator  C< .=>  in PDL scripts?  
  

See next question on assignment in PDL.




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

This is caused by the fact that currently the assignment
operator 
C< => 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 
C< .=> for certain types of assignments.




=head2 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(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 will be incorporated into PDL when 5.6
is more widespread.




=head2 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 functions: 
C< any> and 
C< 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
   	  





=head2 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 
B< does not> work! What you are looking for is the 
B< 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.




=head1 ADVANCED TOPICS


=head2 Q: 6.12    What is a null pdl ?  
  

C< 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. 
I< Null> piddles can be used in
places where a PDL function expects an 
I< output> or 
I< temporary> argument. 
I< Output> and 
I< temporary> arguments are flagged in the
I< signature> of a PDL function with
the 
C< [o]> and 
C< [t]> qualifiers (see next question if you
don't know what the 
I< signature> of a
PDL function is).  For example, you can invoke the 
C< sumover> function as follows:

   
         sumover $a, $b=null;
       

which is equivalent to

   
         $b = sumover $a;
       

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




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

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

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

this says that 
C< maximum> takes two arguments, the first of which is
(at least) one-dimensional while the second one is zero-dimensional and
an 
I< output> argument (flagged by the 
C< [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 
I< threading> in PDL).

For details and further explanations consult 
L<"PDL::Indexing"> and
L<"PDL::PP"> .




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

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

The longer answer (extracted from 
L<"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 support to extent the PDL class via the 
I< has-a> relation for blessed hashes. You
can get the 
I< HAS-A> behave like 
I< IS-A> simply in that you assign the PDL
object to the attribute named 
C< 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
distribution.




=head2 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 
L<"PDL::Dataflow"> . There
are applications which will benefit from this feature (and it is already
at work behind the scenes).




=head2 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 
L<"PDL::PP"> and the
section on "Extensions of PDL".




=head2 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 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 modify the original argument, 
I< 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 
I< 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;
         }
   	




=head1 MISCELLANEOUS


=head2 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:


=over 4

=item *

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

=item *

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.


=item *

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

=item *

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

=item *

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.

=item *

On CPAN you can find the PDL-NetCDF module that works with the current
released version of PDL 2.004.



=back

For further details consult the documentation in the individual modules.




=head2 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 format recognised by
rpic (see 
L<"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 
C< .=> operator) to the
approriate slices of the 3D piddle 
C< $cube> .




=head2 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
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 
C< < testfile >> ; should match the pattern 
C< 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
C< tvrml*.p> for PDL generated dynamic VRML.

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




=head2 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 
C< help> but
not with 
C< apropos> .




=head1 EXTENSIONS OF PDL

=head2 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 
C< 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 
C< 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.




=head2 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
(
L<"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 
C< 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 
C< pp_end> which finishes the PP definitions.  For details see
the 
L<"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
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 
C< .pd> file. This is the file
containing PDL::PP code. We call this 
C< 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 
C< pp_addhdr> instead of linking it in. This is only for the purposes of
example, in a typical application you will use 
C< pp_addhdr> to include header
files. Note that the argument to 
C< pp_addhdr> is enclosed in quotes. 

What is most important in this example is however the
C< pp_def> command. The first
argument to this is the name of the new function 
I< eight > , then comes a hash which
the real meat:

=over 4

=item *

This gives the input parameters
(here 
C< a> ) and the output
parameters (here 
C< b> ).  The
latter are indicated by the 
C< [o]> specifier. 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. 


=item *

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. 




=back


Finally note the call to  
C< 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: 
C< perl Makefile.PL> .
This should give you a Makefile and running 
C< make> should compile the module for
you and 
C< make install> will
install it for you. 




=head2 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 
L<"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 
L<"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 convenience. 

The 
L<"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 
C< .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 minimum,
maximum and average of a piddle. On my machine the resulting
function is 8 times faster than the built-in function 
C< stats> (of course the latter also
calculates the median). 

Let's jump straight in. Here is the code (from a file called
C< quickstats.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
C< quickstats> .

The second line is very important as it specifies the
input and output parameters of the function.  
C< a(n)> tells us that there is one input
parameter that we will refer to as 
C< a> which is expected to be a vector of
length n (likewise matrices, both square and rectangular
would be written as 
C< a(n,n)> and
C< a(n,m)> respectively). To
indicate that something is an output parameter we put
C< [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
essentially pure C but with a couple of convenient
functions. 
C< $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 
C< loop(n)> construct is a
convenience function that loops over the dimension
called n in the parameter section. 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 output
parameters. 

Finally we finish our function declaration with 
C< 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: 
C< 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.




=head1 THE WHO WHEN WHAT

=head1 CHANGES


=over 4

=item *


=over 4

=item *

markers for alpha stage functionality removed 

=item *

restructured description                      

=item *

development/support of PDL                    

=item *

PDL and online help                           

=item *

subclassing piddles                           

=item *

new INSTALLATION section                      

=item *

how to stack 2D piddles -
>
3D piddle       

=item *

questions regarding TriD                      



=back


=item *


=over 4

=item *

use of perl5.004 is now required    

=item *

PDL I/O formats                     

=item *

piddles behave like perl references 

=item *

null PDL's and output arguments     

=item *

signature                           



=back


=item *


=over 4

=item *

questions about pdls and perl array syntax 

=item *

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

=item *

PDL jargon section                         

=item *

piddles                                    



=back


=item *


=over 4

=item *

upgraded released/alpha version numbers     

=item *

added another WYANDL reason                 

=item *

split into perldl/pdl-porters mailing lists 



=back


=item *


=over 4

=item *

initial revision 



=back




=back



=head1 BUGS

If you find any inaccuracies in this document (or disfunctional
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 ).


=head1 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.


=head1 CONTRIBUTORS

Many people have contributed or given feedback on the current
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 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.


=head1 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.
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. 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.