#
# BEGIN of pdlfaq.pod
#
# URLs are now enclosed in the F<> qualifier. This was done to enable
# you to use the new CoolHTML module (see
# http://www.enteract.com/~eryq/CPAN/Pod) for pretty
# podding. Unfortunately, this way of formatting URLs is not
# understood by some other pod converters (e.g. pod2html). However, it
# is much easier to remove the F<> format from URLs than inserting it
# later. If you want to strip the F<> format from URLs just do
# something like
#
#    perl -e 'while (<>) { s/F<(.*)>/$1/g unless /^#/; print; }' pdlfaq.pod
#          >myfaq.pod
#
# and process the output file as usual (don't pipe directly since most podders
# are multipass)
#


=head1 NAME

PDL::FAQ - Frequently asked questions about PDL

=head1 DESCRIPTION

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

This FAQ was generated on 5.3.98.

Current maintainer: Christian Soeller (F<csoelle@sghms.ac.uk>).

=head2 Where to find this document

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

=head2 How to contribute to this document

This is still an early version of the PDL FAQ. As such it is
almost certainly incomplete and maybe unclear in parts. 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 us
about it.

Send your comments, additions, suggestions or corrections
to the PDL mailing list at F<perldl@jach.hawaii.edu> (preferably) or to the
FAQ maintainer Christian Soeller (F<csoelle@sghms.ac.uk>). See below for instructions on how to join
the mailing lists.


=head1 GENERAL QUESTIONS

=head2 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
   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 B<[+]> Who supports PDL? Who develops it?

PDL is supported by its users. General informal support for PDL
is provided through the PDL mailing list (F<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
(F<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 Why yet another Data Language ?

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

=over 8

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

=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 2

=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 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/MesaGL) graphics display
capabilities and implements lots of numerical and semi-numerical algorithms.

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

Furthermore, you need the PDL package which will be installed as an
extension within your PERL installation. See below for directions how
and where to get the latest PDL distribution.

=head2 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 F<ftp://ftp.funet.fi>. You can find a more local
CPAN site by getting the file /pub/languages/perl/CPAN/MIRRORS from
F<ftp://ftp.funet.fi>. Alternatively, you can point your Web browser at
F<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 and the latest beta versions is
F<http://pdl.perl.org>. Thanks to the efforts of Frossie (F<frossie@jach.hawaii.edu>) there is now a mirror site in the US at F<http://www.jach.hawaii.edu/~frossie/pdl-mirror/>


=head2  What machines does PDL run on, then ?

Ideally, PDL should run on about every machine for which a port of
Perl5 is available that supports Xsubs and the package
Extutils::MakeMaker. You also need a C compiler on your machine to
compile those core routines that are written in C or XS. In practice, you
might run into problems if you would try to compile PDL on some
platform it has never been tested on before. A list of platforms on
which PDL has been successfully tested is available at
F<http://pdl.perl.org/ports.html>. If you don't have a compiler you can check if a
binary distribution for your platform is available (we haven't yet got
round to making binary versions/bundles available but it is definitely on
the TODO list) at the PDL home site located at F<http://pdl.perl.org>.

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
F<perldl@jach.hawaii.edu>. We will do our best to assist you in porting PDL
to a new system.


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

In the future, we hope to be able to supply bundles/binaries for a
number of popular architectures. However, as of this writing you will
have to find some means of how and where to compile the package
yourself.

=head2 B<[+]> 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 Are there other PDL information sources on the internet?

First of all, for all purely Perl-related questions (see above why we often
talk about Perl in the PDL FAQ) there are tons of sources on the
net. A good point to start is F<http://www.perl.com>.

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

=over 6

=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 (F<frossie@jach.hawaii.edu>) there is now a mirror site in the US at F<http://www.jach.hawaii.edu/~frossie/pdl-mirror/>


If you are interested in PDL in general you can join the PDL mailing
list F<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 F<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 F<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 F<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
F<pdl-porters@jach.hawaii.edu>. To subscribe, send a message to F<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
F<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 F<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 B<[!]> What is the current version of PDL ?

As of this writing (FAQ version 0.5 of 5.3.98) the
latest released version is 1.11. Currently in beta
test is 1.99. The latest versions should always be
available from a CPAN mirror site near you (see above for info on where
to get PDL).

If there are alpha releases that haven't yet been put onto CPAN interested
developers can find directions on where to get these distribs at
F<http://pdl.perl.org/alpha.html>.

=head2 I am looking for a package to do XXX in PDL. Where shall I look for it?

A good place to start is again F<http://pdl.perl.org>. We hope to get round
to compiling a list of packages that have already been/are in the
process of being interfaced to PDL RSN (you know what that
means...). This information will be accessible through the PDL home
site.

=head2 Where can I get help with PDL related problems (addiction...)?

Currently, the main PDL related information source is the PDL mailing
list at F<perldl@jach.hawaii.edu> (But see also the question on I<information sources>).
It is devoted to information exchange about
all general issues related to PDL. If you want to ask a development related
question there is the PDL development mailing list F<pdl-porters@jach.hawaii.edu>.
Check the question about I<information sources> for subscription directions
and locations of archives of past/recent messages.

Before you post your questions to the list(s) make sure

=over 3

=item *

that your problem has not already been dealt with in another section of
this FAQ.

=item *

that you have read the manual(s) (RTFM!!).

=item *

that your problem is not a general perl programming question in which
case you better check the perl FAQ (available at F<http://www.perl.com/perl/faq>) and/or
ask the question in the relevant perl newsgroups/mailing lists.

=back


=head2   There is this great XXX package on the net. Has it already been interfaced to PDL or how can I do it?

Check on PDL's home site F<http://pdl.perl.org> if the package in question
has already been ported/interfaced to PDL. How to interface a new
package to PDL is explained in L<PDL::PP> (see below if you don't know
what PDL::PP is). Note that people willing to write interfaces for new
packages should target them toward the upcoming beta versions since
the internals of PDL have changed I<a lot> since the latest released
version (1.11).

=head2 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 F<pdl-porters@jach.hawaii.edu>. To subscribe, send a message to F<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 F<http://www.xray.mpe.mpg.de/mailing-lists/pdl-porters/>. We are
always looking for people to write code and/or documentation ;).

=head2 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 F<perldl@jach.hawaii.edu>.

=head1 B<[+]> INSTALLATION

=head2 B<[+]> I have problems installing PDL. What shall I do?

First make sure you have read the file INSTALL in the distribution.
In particular, 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.

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 (F<perldl@jach.hawaii.edu>, see also above). Response
is often rapid.

=head2 B<[+]> 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 B<[+]> Do I have to build PDL myself? Are there binary distributions?

There are no binary distributions at this time. As soon as the developers
find the time there will be binary distributions for some popular
platforms. Please check the PDL home site and the mailing list for
announcements.

=head2 B<[+]> 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.

=head1 TECHNICAL QUESTIONS


=head2 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  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  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<sec> (see L<PDL::Impatient/"Sections">) 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  B<[!]> How do I get online help for PDL?

Just type C<help> at the C<perldl> prompt and proceed from there.

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

=head2  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  There is this strange pre-processor package (PDL::PP). Do I have to know about it?

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


=head2 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  What is this strange usage of the string concatenation operator C<.=> in PDL scripts ?

See next question on assignment in PDL.

=head2  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 (new
indexing features, dataflow) 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. For details see the
documentation about indexing/threading and dataflow that come with
those versions of PDL.

=head2  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;
  }

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

=item raw format

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

=item a more generic raw format

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

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

=item ASCII

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 image formats (TIFF, GIF, JPEG, etc)

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 NetCDF

On CPAN you can find the PDL-NetCDF module that works with the current
released version of PDL 1.11. A new version for use
with PDL 1.99 and higher is in the making.

=back

For further details consult the documentation in the individual modules.

=head2   What is a C<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 exspects 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   What is the I<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 B<[+]> 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 F<t/subclass.t> in the PDL
distribution.

=head2 B<[+]> 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 B<[+]> 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
F<Demos/TriD> in the distribution. After you have built PDL just
change to that directory and try

  perl -Mblib <testfile>

where C<E<lt>testfileE<gt>> 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
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 B<[+]> 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  PDL JARGON

=head2 B<[!]> Oops, what is threading (is PDL a newsreader) ?

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

=over 2

=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  What is a piddle C<(;)> ?

Well, PDL scalar variables (which are instances of a particular class
of perl objects, i.e. blessed thingies (see I<perlfaq>)) 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 CHANGES

=head2 0.5

=over 8

=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

=head2 0.4

=over 5

=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

=head2 0.3

=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

=head2 0.2

=over 3

=item *

upgraded released/alpha version numbers

=item *

added another WYANDL reason

=item *

split into perldl/pdl-porters mailing lists

=back

=head2 0.1

=over 1

=item *

initial revision

=back



=head1 BUGS

If you find any inaccuracies in this document (or disfunctional URLs)
please report to the perldl mailing list F<perldl@jach.hawaii.edu> or to the
current FAQ maintainer Christian Soeller (F<csoelle@sghms.ac.uk>).

=head1 ACKNOWLEDGEMENTS

Achim Bohnet (F<ach@mpe.mpg.de>) for suggesting CoolHTML as a
prettypodder and various other improvements. Suggestions for
some questions were taken from Perl Faq and adapted for PDL.

=cut



=head1 AUTHOR & COPYRIGHT

This document emerged from a joint effort of several PDL developers
(Karl Glazebrook (F<kgb@aaocbn1.aao.GOV.AU>), Tuomas J. Lukka
(F<lukka@husc.harvard.edu>), Christian Soeller
(F<csoelle@sghms.ac.uk>)) 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
Christian Soeller (F<csoelle@sghms.ac.uk>) or ask on the PDL mailing list F<perldl@jach.hawaii.edu>
if you are unclear.



=cut

#
# END of pdlfaq.pod
#