|
PDL::FAQ - Frequently asked questions about PDL |
Error: PL_na not declared or similar .= in PDL scripts?
PDL::FAQ - Frequently asked questions about PDL
Current FAQ version: 0.6
This is version 0.6 of the PDL FAQ, a collection of frequently asked questions about PDL - the Perl Data Language.
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 .
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.
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.
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.
There are actually several reasons and everyone should decide for himself which are the most important ones:
All existing languages violate at least one of these rules.
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.
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 '' ;
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 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.
PDL is available as source distribution in the 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/
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.
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
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.
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:
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 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 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 very good reason for doing that.
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.
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 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 ;).
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 .
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.
Most users should not have to edit any configuration files manually. However, in some cases you might have to supply some information about akwardly placed include files/libraries or you might want to explicitly disable building some of the optional PDL modules. Check the files INSTALL and perldl.conf for details.
If you had to manually edit perldl.conf and are happy with the
results you can keep the file handy for future
reference. Place it in ~/.perldl.conf where it will be picked
up automatically or use
perl Makefile.PL PDLCONF=your_file_name next time you build PDL.
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.
Error: PL_na not declared or similarYou 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.
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.
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
alien .
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!
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.
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
pdl-porters and
perldl mailing lists.
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.
Unfortunately, in the context of PDL the term threading can have two different (but related) meanings:
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.
(;) ?Well, PDL scalar variables (which are instances of a particular class of perl objects, i.e. blessed thingies (see man perlobj )) are in common PDL parlance often called piddles (for example, check the 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.
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.
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.
See answer to the next question why the normal perl array syntax doesn't work for pdls.
Ok, you are right in a way. The docs say that pdls can be thought of arrays. More specifically, it says ( PDL::Impatient ):
I find when using perlDL it is most useful to think of
standard perl @x variables as "lists" of generic
"things" and PDL variables like $x as
"arrays" which can be contained in lists or
hashes.
So, while pdls can be thought of as some kind of
multi-dimensional array they are
not arrays in the perl sense. Rather,
from the point of view of perl they are some special class
(which is currently 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
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 representing ,e.g,
a spectrum, where $spec[3] is the fourth element of the perl
list (or array ;)
@spec . This may
be confusing but is very useful !
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 .
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.
.= in PDL scripts?See next question on 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.
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.
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:
any and
all . Use these to test if any or
all elements in a piddle fulfils some criterion:
perldl> $a=pdl ( 1, -2, 3); perldl> print '$a has at least one element < 0' if (any $a < 0); $a has at least one element < 0
perldl> print '$a is not positive definite' unless (all $a > 0); $a is not positive definite
It is a common problem that you try to make a mask array or something similar using a construct such as
$mask = which($piddle > 1 && $piddle < 2);
This does not work! What you are looking for is the bitwise logical operators '|' and ' & ' which work on an element-by-element basis. So it is really very simple: Do not use logial operators on multi-element piddles since that really doesn't make sense, instead write the example as:
$mask = which($piddle > 1 & $piddle < 2);
which works correctly.
null is a special token for 'empty
piddle'. A null pdl can be used to flag to a PDL function that
it should create an appropriately sized and typed
piddle.
Null piddles can be used in
places where a PDL 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 signature and threading (see also below).
The
signature of a function is an important concept in PDL.
Many (but not all) PDL function have a
signature which specifies the arguments and their (minimal)
dimensionality. As an example, look at the signature of the
maximum function:
'a(n); [o] b;'
this says that
maximum takes two arguments, the first of which is
(at least) one-dimensional while the second one is zero-dimensional and
an
output argument (flagged by the
[o] qualifier). If the function
is called with pdls of higher dimension the function will be repeatedly
called with slices of these pdls of appropriate dimension(this is
called
threading in PDL).
For details and further explanations consult PDL::Indexing and PDL::PP .
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 support to extent the PDL class via the
has-a relation for blessed hashes. You
can get the
HAS-A behave like
IS-A simply in that you assign the PDL
object to the attribute named
PDL and
redefine the method initialize(). For example:
package FOO;
@FOO::ISA = qw(PDL);
sub initialize {
my $class = shift;
my $self = {
creation_time => time(), # necessary extension :-)
PDL => PDL->null, # used to store PDL object
};
bless $self, $class;
}
For another example check the script t/subclass.t in the PDL distribution.
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).
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''.
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, not a copy of it. This is different from some other array processing languages but makes for very efficient passing of piddles between subroutines. If you do not want to modify the original argument but rather a copy of it just create a copy explicitly (this example also demonstrates how to properly check for an explicit request to process inplace, assuming your routine can work inplace):
sub myfunc {
my $pdl = shift;
if ($pdl->is_inplace)
{$pdl->set_inplace(0)}
else # modify a copy by default
{$pdl = $pdl->copy}
$pdl->set(0,0);
return $pdl;
}
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:
It is possible that the FastRaw functionality will be included in the FlexRaw module at some time in the future.
rcols and
rgrep functions, also in PDL::IO::Misc.
For further details consult the documentation in the individual modules.
Assuming all arrays are of the same size and in some format recognised by rpic (see PDL::IO::Pic ) you could say:
use PDL::IO::Pic;
@names = qw/name1.tif .... nameN.tif/; # some file names
$dummy = PDL->rpic($names[0]);
$cube = PDL->zeroes($dummy->type,$dummy->dims,$#names+1); # make 3D piddle
for (0..$#names)
{($tmp = $cube->slice(":,:,($_)")) .= PDL->rpic($names[$_])}
The for loop reads the actual images into a temporary 2D piddle whose
values are then assigned (using the overloaded
.= operator) to the
approriate slices of the 3D piddle
$cube .
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
< 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.
Questions like this should be a thing of the past with the PDL online help system in place. Just try (after installation):
un*x> perldl
perldl> apropos trid
Check the output for promising hits and then try to look up some of them, e.g.
perldl> help PDL::Graphics::TriD
Note that case matters with
help but
not with
apropos .
The first stop is again
perldl or the
PDL documentation. There is already a lot of functionality in
PDL which you might be aware of. The easiest way to look for
functionality is to use the
apropos command:
perldl> apropos 'integral'
ceil Round to integral values in floating-point format
floor Round to integral values in floating-point format
intover Project via integral to N-1 dimensions
rint Round to integral values in floating-point format
Since the apropos command is no sophisticated search engine make sure that you search on a couple of related topics and use short phrases.
However there is a good chance that what you need is not part of the PDL distribution. You are then well advised to check out http://pdl.perl.org where there is a list of packages using PDL. If that does not solve your problem, ask on the mailing-list, if nothing else you might get assistance which will let you interface your package with PDL yourself, see also the next question.
Yes, you can, in fact it is very simple for many simple applications. What you want is the PDL pre-prosessor PP ( PDL::PP ). This will allow you to make a simple interface to your C routine.
The two functions you need to learn (at least first) are
pp_def which defines the calling
interface to the function, specifying input and output
parameters, and contains the code that links to the external
library. The other command is
pp_end which finishes the PP 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 returning a double, and expecting an integer - the number of terms in the sum - as input. This function could be defined in a library or, as we do here, as an inline function.
We will postpone the writing of the Makefile till
later. First we will construct the
.pd file. This is the file
containing PDL::PP code. We call this
eight.pd .
#
# pp_def defines a PDL function.
#
pp_addhdr (
'
double eight_sum(int n)
{
int i;
double sum, x;
sum = 0.0; x=0.0;
for (i=1; i<=n; i++) {
x++;
sum += x/((4.0*x*x-1.0)*(4.0*x*x-1.0));
}
return 1.0/sum;
} ');
pp_def (
'eight',
Pars => 'int a(); double [o]b();',
Code => '$b()=eight_sum($a());'
);
# Always make sure that you finish your PP declarations with # pp_done
pp_done();
A peculiarity with our example is that we have included
the entire code with
pp_addhdr instead of linking it in. This is only for the purposes of
example, in a typical application you will use
pp_addhdr to include header
files. Note that the argument to
pp_addhdr is enclosed in quotes.
What is most important in this example is however the
pp_def command. The first
argument to this is the name of the new function
eight , then comes a hash which
the real meat:
a ) and the output
parameters (here
b ). The
latter are indicated by the
[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.
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 Makefile and running
make should compile the module for
you and
make install will
install it for you.
This question is closely related to the previous one, and as we said there, the PDL::PP pre-processor is the standard way of interfacing external packages with PDL. The most usual way to use PDL::PP is to write a short interface routine, see the PDL::PP manpage and the answer to the previous question for examples.
However it is also possible to interface a package to 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
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 minimum,
maximum and average of a piddle. On my machine the resulting
function is 8 times faster than the built-in function
stats (of course the latter also
calculates the median).
Let's jump straight in. Here is the code (from a file called
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
quickstats .
The second line is very important as it specifies the
input and output parameters of the function.
a(n) tells us that there is one input
parameter that we will refer to as
a which is expected to be a vector of
length n (likewise matrices, both square and rectangular
would be written as
a(n,n) and
a(n,m) respectively). To
indicate that something is an output parameter we put
[o] in front of their names, so
referring back to the code we see that avg, max and min
are three output parameters, all of which are scalar
(since they have no dimensional size indicated.
The third line starts the code definition which is
essentially pure C but with a couple of convenient
functions.
$GENERIC is a
function that returns the C type of its argument - here
the input parameter a. Thus the first two lines of the
code section are variable declarations.
The
loop(n) construct is a
convenience function that loops over the dimension
called n in the parameter section. Inside this loop we
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
pp_done() .
To compile our new function we need to create a Makefile, which we will just list since its creation is discussed in an earlier question.
use PDL::Core::Dev; use ExtUtils::MakeMaker; PDL::Core::Dev->import();
$package = ["quickstats.pd",Quickstats,PDL::Quickstats]; %hash = pdlpp_stdargs($package);
WriteMakefile( %hash );
sub MY::postamble {pdlpp_postamble($package)};
An example Makefile.PL
Our new statistic function should now compile using the
tried and tested perl way:
perl Makefile.PL; make .
You should experiment with this function, changing the calculations and input and output parameters. In conjunction with the PDL::PP manpage this should allow you to quickly write more advanced routines directly in PDL::PP.
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 ).
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.
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.
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.
|
PDL::FAQ - Frequently asked questions about PDL |